Skip to main content

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
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.