Transcribe Files#

In this example, we will transcribe a long audio file (> 60 seconds) using the asynchronous API. For shorter audio files (<60 seconds), please refer to the Transcribe Short Audio guide which uses the synchronous API for simplicity.

transcribe_file_async.py

1. Upload File

First we upload the file with the transcribe_file_async() function. Once the request succeeds, the auto-assigned file_id is returned.

from soniox.speech_service import SpeechClient
from soniox.transcribe_file import transcribe_file_async


# Do not forget to set your API key in the SONIOX_API_KEY environment variable.
with SpeechClient() as client:
    file_id = transcribe_file_async(
        "../test_data/test_audio_long.flac",
        client,
        model="en_v2", # Do not forget to specify the model!
        reference_name="test",
    )

You can use the reference_name to associate your internal file id with the uploaded file. It can be any string not longer than 256 characters, including the empty string, and duplicates are allowed. The service does not use this field, it is only for your reference.

2. Get Status

After the file has been uploaded, it will be in one of 4 states: QUEUED, TRANSCRIBING, COMPLETED or FAILED. We call the GetTranscribeAsyncStatus() function to check the status of the file.

status = client.GetTranscribeAsyncStatus(file_id)

If the file status is FAILED, the error message can be obtained from error_message field.

print(f"Transcription failed with error: {status.error_message}")

3. Get Result

Once the file status is COMPLETED, we call the GetTranscribeAsyncResult() function to retrieve transcription result.

result = client.GetTranscribeAsyncResult(file_id)
print(f"Text: " + "".join(word.text for word in result.words))

Note, when transcribing with separate recognition per channel, the GetTranscribeAsyncResult() function returns a list of results, one for each channel.

4. Delete File

Once the transcription result has been obtained, the file should be deleted using DeleteTranscribeAsyncFile function.

client.DeleteTranscribeAsyncFile(file_id)

Run

Run the complete example transcribe_file_async.py.

python3 transcribe_file_async.py

Output

Uploading file.
File ID: 3457
Calling GetTranscribeAsyncStatus.
Status: QUEUED
Calling GetTranscribeAsyncStatus.
Status: TRANSCRIBING
Calling GetTranscribeAsyncStatus.
Status: TRANSCRIBING
Calling GetTranscribeAsyncStatus.
Status: COMPLETED
Calling GetTranscribeAsyncResult
Text: But there is always a stronger sense of life when the sun is ...
Calling DeleteTranscribeAsyncFile.

transcribe_file_async.js

1. Upload File

First we upload the file with the transcribeFileAsync() function. Once the request succeeds, the auto-assigned file_id is returned.

// Do not forget to set your API key in the SONIOX_API_KEY environment variable.
const speechClient = new SpeechClient();

const file_id = await speechClient.transcribeFileAsync(
    "../test_data/test_audio_long.flac",
    "test", // reference_name
    {
        model: "en_v2", // Do not forget to specify the model!
    }
);

2. Get Status

After the file has been uploaded, it will be in one of 4 states: QUEUED, TRANSCRIBING, COMPLETED or FAILED. We call the getTranscribeAsyncStatus() function to check the status of the file.

const response = await speechClient.getTranscribeAsyncStatus(file_id);

If the file status is FAILED, the error message can be obtained from error_message field.

console.log(`Transcription failed with error: ${response.error_message}`);

3. Get Result

Once the file status is COMPLETED, we call the GetTranscribeAsyncResult() function to retrieve transcription result.

const result = await speechClient.getTranscribeAsyncResult(file_id);
console.log("Text: " + result.words.map((word) => word.text).join(""));

Note, when transcribing with separate recognition per channel, the GetTranscribeAsyncResult() function returns a list of results, one for each channel.

4. Delete File

Once the transcription result has been obtained, the file should be deleted using DeleteTranscribeAsyncFile function.

await speechClient.deleteTranscribeAsyncFile(file_id);

Run

Run the complete example transcribe_file_async.js.

node transcribe_file_async.js

Output

Uploading file.
File ID: 3456
Calling getTranscribeAsyncStatus.
Status: QUEUED
Calling getTranscribeAsyncStatus.
Status: QUEUED
Calling getTranscribeAsyncStatus.
Status: TRANSCRIBING
Calling getTranscribeAsyncStatus.
Status: TRANSCRIBING
Calling getTranscribeAsyncStatus.
Status: COMPLETED
Calling getTranscribeAsyncResult
Text: But there is always a stronger sense of life when the sun is ...
Calling deleteTranscribeAsyncFile.

TranscribeFileAsync.cs

1. Upload File

First we upload the file with the transcribeFileAsync() function. Once the request succeeds, the auto-assigned file_id is returned.

// Do not forget to set your API key in the SONIOX_API_KEY environment variable.
using var client = new SpeechClient();

var fileId = await client.TranscribeFileAsync(
    "../../test_data/test_audio_long.flac",
    new TranscriptionConfig
    {
        Model = "en_v2", // Do not forget to specify the model!
        ClientRequestReference = "test",
    });

You can use the TranscriptionConfig.ClientRequestReference to associate your internal file id with the uploaded file. It can be any string not longer than 32 characters, including the empty string, and duplicates are allowed. The service does not use this field, it is only for your reference.

2. Get Status

After the file has been uploaded, it will be in one of 4 states: QUEUED, TRANSCRIBING, COMPLETED or FAILED. We call the GetTranscribeAsyncFileStatus() function to check the status of the file.

TranscribeAsyncFileStatus status;
status = await client.GetTranscribeAsyncFileStatus(fileId);

If the file status is FAILED, the error message can be obtained from status.ErrorMessage field.

Console.WriteLine($"Transcription failed with error: {status.ErrorMessage}");

3. Get Result

Once the file status is COMPLETED, we call the GetTranscribeAsyncResult() function to retrieve transcription result.

var completeResult = await client.GetTranscribeAsyncResult(fileId);
Result result = (completeResult as SingleResult)!.Result;
var text = string.Join("", result.Words.Select(word => word.Text).ToArray());
Console.WriteLine("Text: " + text);

When transcribing without separate recognition per channel, the GetTranscribeAsyncResult() function returns a SingleResult object, which has a single Result in the Result field. When transcribing with separate recognition per channel, it returns a SeparateRecognitionResult object, which has a list of Result objects in the ChannelResults field, one for each channel.

4. Delete File

Once the transcription result has been obtained, the file should be deleted using DeleteTranscribeAsyncFile function.

Run

Run the complete example TranscribeFileAsync.cs.

cd TranscribeFileAsync
dotnet run

Output

File ID: 3456
Calling GetTranscribeAsyncFileStatus.
Calling GetTranscribeAsyncFileStatus.
Calling GetTranscribeAsyncFileStatus.
Calling GetTranscribeAsyncFileStatus.
Calling GetTranscribeAsyncResult.
Text: But there is always a stronger sense of life when the sun is ...
Calling DeleteTranscribeAsyncFile.

Limits#

The maximum file size is 500MB. The maximum total duration of audio is 5 hours.

The maximum number of uploaded files pending transcription (in QUEUED or TRANSCRIBING status) is 100. The maximum number of uploaded non-deleted files (in any status) is 2000.

For more information on transcribing files asynchronously, please refer to the Asynchronous Transcription section in gRPC references.