STT Control

These APIs pause and resume real-time Speech-to-Text (STT) inference for a specific stream at runtime, without restarting the server or recreating the stream.

For full STT configuration, see Realtime Speech-to-Text.

Enable STT

Resumes STT inference for the stream. Audio frames are passed to the Whisper model and subtitle cues are generated again.

Request

POST v1/vhosts/{vhost}/apps/{app}/streams/{stream}:enableStt

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{}

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "enabled": true
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response.enabled
    true if STT is now running

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm="OvenMediaEngine"

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost, app, or stream name could not be found, or no STT encoder exists for this stream.

Body

{
    "statusCode": 404,
    "message": "Could not find STT encoder for stream: [default/app/stream]"
}

503 Service Unavailable

The Transcoder module is not running.

Disable STT

Pauses STT inference. Audio frames are dropped without processing, and subtitle renditions remain in the stream but stop receiving new cues. The underlying STT model and GPU allocations remain loaded.

Request

POST v1/vhosts/{vhost}/apps/{app}/streams/{stream}:disableStt

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{}

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "enabled": false
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response.enabled
    false if STT is now paused

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm="OvenMediaEngine"

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost, app, or stream name could not be found, or no STT encoder exists for this stream.

Body

{
    "statusCode": 404,
    "message": "Could not find STT encoder for stream: [default/app/stream]"
}

503 Service Unavailable

The Transcoder module is not running.

Get STT Status

Returns the current enabled state and configuration of all active STT renditions for the stream.

Request

POST v1/vhosts/{vhost}/apps/{app}/streams/{stream}:sttStatus

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{}

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "enabled": true,
        "renditions": [
            {
                "codec": "WHISPER",
                "label": "Korean",
                "model": "whisper_model/ggml-small.bin",
                "language": "auto",
                "translation": "false"
            },
            {
                "codec": "WHISPER",
                "label": "English",
                "model": "whisper_model/ggml-small.bin",
                "language": "auto",
                "translation": "true"
            }
        ]
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response.enabled
    true if STT inference is currently running, false if paused
# response.renditions
    List of active STT encoder instances for this stream
    ## codec
        STT engine in use. Currently always "whisper".
    ## label
        Subtitle rendition label this instance writes to.
    ## model
        Model file path used by this instance.
    ## language
        Configured source language ("auto" or a language code).
    ## translation
        "true" if translation to English is enabled.

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm="OvenMediaEngine"

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

503 Service Unavailable

The Transcoder module is not running.