speechmatics.batch_client

Wrapper library to interface with Speechmatics ASR batch v2 API.

class speechmatics.batch_client.BatchClient(connection_settings: speechmatics.models.ConnectionSettings)[source]

Client class for Speechmatics Batch ASR REST API.

This client may be used directly but must be closed afterwards, e.g.:

settings = ConnectionSettings(url="https://{api}/v2",
auth_token="{token}")
client = BatchClient(settings)
client.connect()
list_of_jobs = client.list_jobs()
client.close()

It may also be used as a context manager, which handles opening and closing the connection for you, e.g.:

with BatchClient(settings) as client:
    list_of_jobs = client.list_jobs()
check_job_status(job_id: str) Dict[str, Any][source]

Check the status of a job.

Parameters

job_id (str) – ID of previously submitted job.

Returns

Job status

Return type

Dict[str, Any]

Raises
  • JobNotFoundException – When a job_id is not found.

  • httpx.HTTPError – For any request other than 404, httpx exceptions are raised.

close() None[source]

Clean up/close client connection pool.

This is required when using the client directly, but not required when using the client as a context manager.

Return type

None

connect()[source]

Create a connection to a Speechmatics Transcription REST endpoint

delete_job(job_id: str, force: bool = False) str[source]

Delete a job. Must pass force=True to cancel a running job.

Parameters
  • job_id (str) – ID of previously submitted job.

  • force – When set, a running job will be force terminated. When unset (default), a running job will not be terminated and we will return False.

Returns

Deletion status

Return type

str

get_job_result(job_id: str, transcription_format: str = 'json-v2') Union[bool, str, Dict[str, Any]][source]

Request results of a transcription job.

Parameters
  • job_id (str) – ID of previously submitted job.

  • transcription_format – Format of transcript. Defaults to json. Valid options are json-v2, txt, srt. json is accepted as an alias for json-v2.

Returns

False if job is still running or does not exist, or transcription in requested format

Return type

bool | str | Dict[str, Any]

:raises JobNotFoundException : When a job_id is not found. :raises httpx.HTTPError: For any request other than 404, httpx exceptions are raised. :raises TranscriptionError: When the transcription format is invalid.

list_jobs() List[Dict[str, Any]][source]

Lists last 100 jobs within 7 days associated with auth_token for the SaaS or all of the jobs for the batch appliance.

Returns

List of jobs

Return type

List[Dict[str, Any]]

send_request(method: str, path: str, **kwargs) httpx.Response[source]

Send a request using httpx.Client()

Parameters
  • method (str) – HTTP request method

  • path (str) – Configuration for the transcription.

  • **kwargs

    Any valid kwarg of httpx.Client

Returns

httpx Response object

Return type

httpx.Response

Raises

httpx.HTTPError – When a request fails, raises an HTTPError

submit_job(audio: Union[Tuple[str, bytes], str, os.PathLike], transcription_config: Union[Dict[str, Any], speechmatics.models.BatchTranscriptionConfig, str, os.PathLike]) str[source]

Submits audio and config for transcription.

Parameters
  • audio (os.Pathlike | str | Tuple[str, bytes]) – Audio file path or tuple of filename and bytes

  • transcription_config (Dict[str, Any] | speechmatics.models.BatchTranscriptionConfig | str) – Configuration for the transcription.

Returns

Job ID

Return type

str

Raises

httpx.HTTPError – For any request errors, httpx exceptions are raised.

wait_for_completion(job_id: str, transcription_format: str = 'txt') Union[str, Dict[str, Any]][source]

Blocks until job is complete, returning a transcript in the requested format.

Parameters
  • job_id (str) – ID of previously submitted job.

  • transcription_format – Format of transcript. Defaults to txt. Valid options are json-v2, txt, srt. json is accepted as an alias for json-v2.

Returns

Transcription in requested format

Return type

Union[str, Dict[str, Any]]

:raises JobNotFoundException : When a job_id is not found. :raises httpx.HTTPError: For any request other than 404, httpx exceptions are raised.