Generating SDKs

• The CAPT API is defined as a protocol buffer specification, a proto file. This file allows a developer to auto-generate client SDKs for a number of different programming languages.

• The CAPT proto definition, cobaltspeech/capt/v1/capt.proto, is supplied to you as part of your release, together with pre-generated Go and Python bindings. If you only need those two languages you can skip straight to Using the pre-generated SDKs; to generate bindings for another language, see Generating SDKs.

The relevant part of your release looks like this:

release.tar.bz2
└── api
    ├── proto
    │   └── cobaltspeech
    │       └── capt
    │           └── v1
    │               └── capt.proto
    └── gen
        ├── go
        │   └── cobaltspeech/capt/v1/{capt.pb.go, capt_grpc.pb.go}
        └── py
            └── cobaltspeech/capt/v1/{capt_pb2.py, capt_pb2_grpc.py, capt_pb2.pyi}

Using the pre-generated SDKs

Golang

Copy the api/gen/go tree into your module, or add it as a dependency, and import the package:

import captpb "github.com/your-org/your-module/gen/go/cobaltspeech/capt/v1"

You will also need the gRPC and protobuf runtime libraries:

go get google.golang.org/protobuf
go get google.golang.org/grpc

Python

The Python bindings depend on Python >= 3.8. Place api/gen/py on your PYTHONPATH, or copy the cobaltspeech package into your project, and install the runtime dependencies:

pip install --upgrade pip
pip install --upgrade protobuf grpcio

Then import the modules:

import cobaltspeech.capt.v1.capt_pb2 as capt
import cobaltspeech.capt.v1.capt_pb2_grpc as capt_grpc

Generating SDKs from the proto

To generate bindings for a language we do not ship, generate them yourself from capt.proto. We recommend using buf, a command line tool that can generate documentation, schemas and SDK code for many languages.

Step 1. Installing buf

• Linux (from Github)
• MacOS

COBALT="${HOME}/cobalt"
mkdir -p "${COBALT}/bin"

VERSION="1.72.0"
URL="https://github.com/bufbuild/buf/releases/download/v${VERSION}/buf-$(uname -s)-$(uname -m)"
curl -L ${URL} -o "${COBALT}/bin/buf"

# Give executable permissions and add to $PATH.
chmod +x "${COBALT}/bin/buf"
export PATH="${PATH}:${COBALT}/bin"

brew install bufbuild/buf/buf

Step 2. Writing a buf.gen.yaml

Create a buf.gen.yaml next to the api/proto directory from your release. The example below generates Go and Python; other plugins can be added for more languages.

version: v1

managed:
  enabled: true
  go_package_prefix:
    default: github.com/your-org/your-module/gen

plugins:
  # Golang
  - plugin: buf.build/grpc/go
    out: gen/go
    opt: paths=source_relative

  - plugin: buf.build/protocolbuffers/go
    out: gen/go
    opt: paths=source_relative

  # Python
  - plugin: buf.build/grpc/python
    out: gen/py

  - plugin: buf.build/protocolbuffers/python
    out: gen/py

  - plugin: buf.build/protocolbuffers/pyi
    out: gen/py

Step 3. Generating code

# Removing any previously generated files.
rm -rf ./gen

# Generating code for the proto files inside the `proto` directory.
buf generate proto

You should now have a gen folder containing the generated code. The latest version of the CAPT API is v1. Import or copy the generated files into your project as per the conventions of your language.

• Python
• Golang

gen
└── py
  └── cobaltspeech
    └── capt
      └── v1
        ├── capt_pb2_grpc.py
        ├── capt_pb2.py
        └── capt_pb2.pyi

gen
└── go
  └── cobaltspeech
    └── capt
      └── v1
        ├── capt_grpc.pb.go
        └── capt.pb.go

Once you have an SDK, continue to connecting to the server.