gRPC

Soniox provides a gRPC-based API for the entire Soniox Speech Recognition service.

gRPC is an open source high performance RPC (Remote Procedure Call) framework that can run in any environment. It can efficiently connect services in and across data centers. You can read more about it on the gRPC Home Page.

Soniox provides a gRPC-based API for almost all Soniox features. This includes speech recogniton with associated features (such as Speaker Diarization, Speaker Identification and Customization).

You only need to use gRPC directly if a Soniox client library is not available for your programming language. When using a Soniox client library, the library abstract away many aspects of gRPC. Please refer to the gRPC Documentation for instructions on how to use the client library.

Soniox Proto File

We have defined all the RPCs and messages in one proto file file. You can compile the .proto file into any of the supported languages and import the generated files into your application.

speech_service.proto

Generate Protobuf and gRPC Files

You will need the Protocol Buffer compiler to generate source files applicable for your language from the .proto file.

For Python langauge, install the following packages:

Terminal

python3 -m pip install grpcio
python3 -m pip install grpcio-tools

Then generate the source files as follows:

Terminal

mkdir soniox
cd soniox
wget https://raw.githubusercontent.com/soniox/soniox_python/master/soniox/speech_service.proto
python3 -m grpc_tools.protoc -I. --python_out=. --pyi_out=. --grpc_python_out=. ./speech_service.proto

This will generate the files service_pb2.py and service_pb2_grpc.py, which you will need to import into your Python application. It will also generate service_pb2.pyi containing type information.

Soniox API Endpoint

Soniox API endpoint is api.soniox.com:443. Secure channel (SSL/TLS) is required.

Python Example

The example demonstrates how to use Transcribe RPC to transcribe short audio files using gRPC and Soniox API.

transcribe_file_short.py

import grpc
from speech_service_pb2 import TranscribeRequest, TranscriptionConfig
from speech_service_pb2_grpc import SpeechServiceStub
 
# Use default SSL credentials.
# This should be sufficient with recent gRPC versions.
creds = grpc.ssl_channel_credentials()
 
# If you are having problems with the secure connection, you should instead
# manually supply the roots.pem file (see below) and load it here like this.
# with open('roots.pem', 'rb') as f:
#     creds = grpc.ssl_channel_credentials(f.read())
 
def main():
    # Create secure channel with the credentials.
    with grpc.secure_channel("api.soniox.com:443", creds) as channel:
        # Create client.
        client = SpeechServiceStub(channel)
        # Create TranscribeRequest object.
        request = TranscribeRequest(
            config=TranscriptionConfig(
                model="en_v2",
            ),
        )
        # Set the API key.
        request.api_key = "<YOUR-API-KEY>"
        # Read the entire audio file.
        with open("<YOUR-AUDIO-FILE>", "rb") as fh:
            request.audio = fh.read()
        # Call Transcribe method with created TranscribeRequest object.
        response = client.Transcribe(request)
        # Print recognized tokens with start and duration.
        for w in response.result.words:
            print(f"'{w.text}' {w.start_ms} {w.duration_ms}")
 
if __name__ == '__main__':
    main()

SSL and Root Certificates

Soniox gRPC API uses secure connection (SSL/TLS) to ensure security and safety of transmitted data. With recent gRPC versions, you should not need additional setup for this to work.

If it turns out that the secure connection cannot be established due to an authentication error, you should download the root certificates from gRPC GitHub and initialize the gRPC channel with these certificates (see the example above).