gRPC Introduction

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 the entire Soniox Speech Service. Please refer to the gRPC Documentation for instructions on using the gRPC in your programming language.

For demonstration purposes we provide example commands and code for Python. However, our recommendation is to use Soniox Python Package direclty if you are using Python language.

Soniox Proto File

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

Generate Protobuf and gRPC Files

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

For Python langauge, install the following packages:

pip3 install grpcio
pip3 install grpcio-tools

Then generate the source files as follows:

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=. --grpc_python_out=. ./speech_service.proto

This will generate two files service_pb2.py and service_pb2_grpc.py, which you will need to import into your Python client.

Root Certificate

Soniox Speech Service uses SSL/TLS authentication to ensure security and safety of transmitted data. To access the API, you will need the root certificate. You can download it from gRPC GitHub or with the following command:

wget https://raw.githubusercontent.com/grpc/grpc/master/etc/roots.pem

Soniox API Endpoint

Soniox API endpoint is api.soniox.com:443. Secure channel is required using the root certificate above.

Python Example

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

import grpc
from speech_service_pb2 import TranscribeRequest
from speech_service_pb2_grpc import SpeechServiceStub

# Read root certificate for secure client-server connection.
with open('roots.pem', 'rb') as f:
    creds = grpc.ssl_channel_credentials(f.read())

def run():
    # 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()
        # Set the API key.
        request.api_key = '<YOUR-API-KEY>'
        # Read the entire audio file.
        with open('audio_file.flac', 'rb') as f:
            request.audio = f.read()
        # Call Transcribe method with created TranscribeRequest object.
        response = client.Transcribe(request)
        # Print recognized words with start and duration.
        for w in response.result.words:
            print(f'{w.text} , {w.start_ms} , {w.duration_ms}')

if __name__ == '__main__':
    run()