Fast transcription containers with Docker (preview)

The fast transcription container transcribes audio files synchronously, returning results faster than real-time. It's suitable for scenarios where you need transcription results as quickly as possible, such as audio and video subtitles, meeting transcripts, and voicemail. It supports speaker diarization, multichannel processing, and word-level timestamps. This article describes how to download, install, and run a fast transcription container.

For more information about prerequisites, validating that a container is running, running multiple containers on the same host, and running disconnected containers, see Install and run Speech containers with Docker.

Container images

You can find the fast transcription container image for all supported versions and locales on the Microsoft Container Registry (MCR). It resides within the azure-cognitive-services/speechservices/ repository and is named fast-transcription.

The fully qualified container image name is mcr.microsoft.com/azure-cognitive-services/speechservices/fast-transcription. Either append a specific version or append :latest to get the most recent version.

Version	Path
Latest	mcr.microsoft.com/azure-cognitive-services/speechservices/fast-transcription:latest The latest tag pulls the latest image for the en-US locale.
1.0.0	mcr.microsoft.com/azure-cognitive-services/speechservices/fast-transcription:en-gpu-1.0.0-preview

All tags, except for latest, follow this format and are case sensitive:

<language>-gpu-<major>.<minor>.<patch>-preview

For your convenience, the tags are also available in JSON format. The body includes the container path and list of tags. The tags aren't sorted by version, but "latest" is always included at the end of the list as shown in this snippet:

{
  "name": "azure-cognitive-services/speechservices/fast-transcription",
  "tags": [
    <--redacted for brevity-->    
    "gpu-1.0.0-en-us",
    "gpu-1.0.0-en-gb",
    "gpu-1.0.0-en-au",
    "gpu-1.0.0-en-in",
    "gpu-1.0.0-de-de"
  ]
}

Locale support

The following model and locale groups map to supported transcription locales:

Model or locale group	Supported transcription locales
en	en-AU, en-CA, en-GB, en-GH, en-HK, en-IE, en-KE, en-NG, en-NZ, en-PH, en-SG, en-TZ, en-US, en-ZA
multilingual-15-locales	de-DE, en-AU, en-CA, en-GB, en-IN, en-US, es-ES, es-MX, fr-CA, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, zh-CN
t4-35-locales	af-ZA, am-ET, az-AZ, bn-IN, bs-BA, et-EE, eu-ES, fil-PH, ga-IE, gl-ES, hy-AM, is-IS, jv-ID, ka-GE, kk-KZ, km-KH, lo-LA, lt-LT, mk-MK, ml-IN, mn-MN, mt-MT, my-MM, ne-NP, ps-AF, si-LK, so-SO, sq-AL, sr-RS, sw-KE, ur-IN, uz-UZ, wuu-CN, zh-CN-SICHUAN, zu-ZA
ar	ar-AE, ar-BH, ar-EG, ar-IL, ar-IQ, ar-JO, ar-KW, ar-LB, ar-LY, ar-OM, ar-PS, ar-QA, ar-SA, ar-SY, ar-YE
t3-16-locales	bg-BG, ca-ES, cy-GB, fa-IR, hr-HR, hu-HU, lv-LV, mr-IN, ms-MY, nb-NO, ro-RO, sk-SK, sl-SI, uk-UA, vi-VN, zh-HK
es	es-AR, es-BO, es-CL, es-CR, es-CU, es-DO, es-EC, es-GQ, es-GT, es-HN, es-MX, es-NI, es-PA, es-PE, es-PR, es-PY, es-SV, es-US, es-UY, es-VE
fr	fr-BE, fr-CH, fr-FR
it	it-CH, it-IT
india-13-locales	ta-IN, hi-IN, te-IN, gu-IN, mr-IN, kn-IN, bn-IN, ml-IN, pa-IN, ur-IN, or-IN, as-IN, bho-IN
Single-locale entries	de-DE, en-IN, en-Latn-IN, es-CO, es-ES, fr-CA, ja-JP, ko-KR, pt-BR, pt-PT, zh-CN

Get the container image with docker pull

You need the prerequisites including required hardware. Also see the recommended allocation of resources for each Speech container.

Use the docker pull command to download a container image from Microsoft Container Registry:

docker pull mcr.microsoft.com/azure-cognitive-services/speechservices/fast-transcription:latest

Important

The latest tag pulls the latest image for the en-US locale. For additional versions and locales, see fast transcription container images.

Hardware requirements

The fast transcription container requires a GPU to run.

Configuration	GPU	vCPU	Memory
Minimum	NVIDIA T4 or higher	8 cores	16 GB
Recommended	NVIDIA T4	16 cores	110 GB

Important

GPU required. The fast transcription container doesn't support CPU.

Run the container with docker run

Use the docker run command to run the container.

Fast transcription

The following table lists the docker run parameters and their descriptions:

Parameter	Description
{ENDPOINT_URI}	The endpoint is required for metering and billing. For more information, see billing arguments.
{API_KEY}	The API key is required. For more information, see billing arguments.

When you run the fast transcription container, configure the port, memory, and GPU according to the fast transcription container requirements and recommendations.

Here's an example docker run command with placeholder values. You must specify the ENDPOINT_URI and API_KEY values:

docker run --gpus all -p 5000:5000 \
-e ASPNETCORE_URLS=http://+:5000 \
mcr.microsoft.com/azure-cognitive-services/speechservices/fast-transcription \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

This command:

• Runs a fast-transcription container from the container image.
• Exposes all available GPUs to the container.
• Exposes TCP port 5000.
• Sets ASP.NET Core to listen on port 5000.

Disconnected fast transcription

To run disconnected containers (not connected to the internet), you must submit this request form and wait for approval. For more information about applying and purchasing a commitment plan to use containers in disconnected environments, see Use containers in disconnected environments in the Foundry Tools documentation.

If you're approved to run the container disconnected from the internet, the following example shows the formatting of the docker run command to use, with placeholder values. Replace these placeholder values with your own values.

The DownloadLicense=True parameter in your docker run command downloads a license file to enable your Docker container to run when it isn't connected to the internet. It also contains an expiration date, after which the license file is invalid to run the container. You can only use a license file with the appropriate container that you're approved for. For example, you can't use a license file for a fast-transcription container with a speech-to-text container.

Placeholder	Description
{IMAGE}	The container image you want to use. For example: mcr.microsoft.com/azure-cognitive-services/speechservices/fast-transcription:latest
{LICENSE_MOUNT}	The path where the license is downloaded and mounted. For example: /host/license:/path/to/license/directory
{ENDPOINT_URI}	The endpoint for authenticating your service request. You can find it on your resource's Key and endpoint page, on the Azure portal. For example: https://<your-resource-name>.cognitiveservices.azure.com
{API_KEY}	The key for your Speech resource. You can find it on your resource's Key and endpoint page, on the Azure portal.
{CONTAINER_LICENSE_DIRECTORY}	Location of the license folder on the container's local filesystem. For example: /path/to/license/directory

docker run --gpus all -p 5000:5000 \
-e ASPNETCORE_URLS=http://+:5000 \
-v {LICENSE_MOUNT} \
{IMAGE} \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY} 

Once the license file is downloaded, you can run the container in a disconnected environment. The following example shows the formatting of the docker run command you use, with placeholder values. Replace these placeholder values with your own values.

Wherever you run the container, you must mount the license file to the container and specify the location of the license folder on the container's local filesystem with Mounts:License=. You must also specify an output mount so that billing usage records can be written.

Placeholder	Value	Format or example
{IMAGE}	The container image you want to use	mcr.microsoft.com/azure-cognitive-services/speechservices/fast-transcription:latest
{LICENSE_MOUNT}	The path where the license is located and mounted	/host/license:/path/to/license/directory
{OUTPUT_PATH}	The output path for logging. For more information, see usage records in the Foundry Tools documentation.	/host/output:/path/to/output/directory
{CONTAINER_LICENSE_DIRECTORY}	Location of the license folder on the container's local filesystem	/path/to/license/directory
{CONTAINER_OUTPUT_DIRECTORY}	Location of the output folder on the container's local filesystem	/path/to/output/directory

docker run --gpus all -p 5000:5000 \
-e ASPNETCORE_URLS=http://+:5000 \
-v {LICENSE_MOUNT} \
-v {OUTPUT_PATH} \
{IMAGE} \
Eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY} \
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

Speech containers provide a default directory for writing the license file and billing log at runtime. The default directories are /license and /output respectively.

When you mount these directories to the container by using the docker run -v command, make sure the local machine directory ownership is set to user:group nonroot:nonroot before running the container.

Here's a sample command to set file and directory ownership.

sudo chown -R nonroot:nonroot <YOUR_LOCAL_MACHINE_PATH_1> <YOUR_LOCAL_MACHINE_PATH_2> ...

For more information about docker run with Speech containers, see Install and run Speech containers with Docker.

Use the container

The fast transcription container exposes an HTTP REST API for transcription requests. Unlike the speech-to-text container which supports WebSocket streaming, fast transcription processes complete audio files synchronously.

API endpoints

Send transcription requests to:

POST http://localhost:5000/stt/transcriptions:transcribe

Health check endpoint:

GET http://localhost:5000/stt/health

Audio input limits

Limit	Value
Maximum file size	300 MB
Supported formats	WAV (mono PCM 16-bit 48 kHz, recommended), MP3, OPUS/OGG, FLAC, WMA, AAC, ALAW (in WAV container), MULAW (in WAV container), AMR, WebM, SPEEX

Tip

For best results and fastest processing, use mono PCM WAV format at 16-bit depth and 48 kHz sample rate. Other formats are supported but might require extra processing. For examples, see Convert audio to recommended format.

Request format

The API accepts multipart/form-data requests with the following structure:

Part	Content-Type	Description
definition	application/json	JSON object containing transcription options
audio	audio/*	The audio file to transcribe (mutually exclusive with audioUrl)

Convert audio to recommended format

If your audio is in a format other than WAV, use ffmpeg to convert it to mono PCM WAV 16-bit 48 kHz:

Convert MP3 to WAV:

ffmpeg -i input.mp3 -ac 1 -ar 48000 -f s16le output.wav

Convert M4A or AAC to WAV:

ffmpeg -i input.m4a -ac 1 -ar 48000 -f s16le output.wav

Convert OPUS to WAV:

ffmpeg -i input.opus -ac 1 -ar 48000 -f s16le output.wav

The flags mean:

• -ac 1: Convert to mono (1 audio channel)
• -ar 48000: Set sample rate to 48 kHz
• -f s16le: Output as 16-bit signed PCM (little-endian)

Request examples

Basic transcription:

curl -X POST "http://localhost:5000/stt/transcriptions:transcribe?api-version=2024-11-15" \
  -F "audio=@audio.wav" \
  -F 'definition={"locales":["en-US"]}'

Dual-channel separation:

curl -X POST "http://localhost:5000/stt/transcriptions:transcribe?api-version=2024-11-15" \
  -F "audio=@stereo.wav" \
  -F 'definition={"locales":["en-US"],"channels":[0,1]}'

Speaker diarization:

curl -X POST "http://localhost:5000/stt/transcriptions:transcribe?api-version=2024-11-15" \
  -F "audio=@meeting.wav" \
  -F 'definition={"locales":["en-US"],"diarization":{"enabled":true}}'

Profanity filter (masked):

curl -X POST "http://localhost:5000/stt/transcriptions:transcribe?api-version=2024-11-15" \
  -F "audio=@audio.wav" \
  -F 'definition={"locales":["en-US"],"profanityFilterMode":"Masked"}'

Health check:

curl http://localhost:5000/stt/health

Transcription options

Option	Type	Description
locales	string[]	Locales for transcription, such as ["en-US"].
audioUrl	string	HTTP or HTTPS URL of the audio file. This option is mutually exclusive with file upload.
profanityFilterMode	string	How to handle profanity: None, Masked, Removed, Tags.
punctuationMode	string	Punctuation handling: None, Dictated, Automatic, DictatedAndAutomatic.
channels	int[]	Audio channels to process, such as [0, 1] for stereo.
diarization	object	Speaker diarization settings.
diarization.enabled	boolean	Enable speaker diarization.
diarization.maxSpeakers	int	Maximum number of speakers to identify (2-35).
wordLevelTimestampsEnabled	boolean	Include word-level timing information.
disfluencyTaggingEnabled	boolean	Enable disfluency tagging.
prompt	string	Prompt text to improve recognition accuracy.
phraseList	string	Phrase list (semicolon-separated) to improve recognition accuracy.
localeHint	string	Language hint.

Response example

{
  "durationMilliseconds": 2029,
  "combinedPhrases": [
    {
      "text": "What's the weather like?"
    }
  ],
  "phrases": [
    {
      "offsetMilliseconds": 40,
      "durationMilliseconds": 1240,
      "text": "What's the weather like?",
      "words": [
        { "text": "What's", "offsetMilliseconds": 40, "durationMilliseconds": 360 },
        { "text": "the", "offsetMilliseconds": 400, "durationMilliseconds": 160 },
        { "text": "weather", "offsetMilliseconds": 560, "durationMilliseconds": 320 },
        { "text": "like?", "offsetMilliseconds": 880, "durationMilliseconds": 400 }
      ],
      "locale": "en-US",
      "confidence": 0.9874588
    }
  ]
}

Response fields

Field	Type	Description
durationMilliseconds	int	Total audio duration in milliseconds
combinedPhrases	array	Complete transcription text
combinedPhrases[].text	string	Complete transcription text
combinedPhrases[].channel	int	Channel index (shown for multichannel audio)
phrases	array	List of segmented phrases
phrases[].offsetMilliseconds	int	Phrase start time in milliseconds
phrases[].durationMilliseconds	int	Phrase duration in milliseconds
phrases[].text	string	Phrase text
phrases[].words	array	Word-level information (returned by default)
phrases[].locale	string	Recognized locale
phrases[].confidence	float	Confidence score (0-1)
phrases[].channel	int	Channel index (shown for multichannel audio)
phrases[].speaker	int	Speaker ID (shown when diarization is enabled)

Configuration options

Use the following environment variables to configure the fast transcription container:

Variable	Default	Description
EULA	(required)	Set to accept
BILLING	(required)	Azure endpoint URL for billing
APIKEY	(required)	API key for authentication
DECODER_COUNT	2	Number of parallel decoder instances; at least 2 required for dual-channel audio

Troubleshooting

Recognition delays at end of speech

If you experience latency after you stop speaking, the issue is likely related to silence timeout configuration.

1. Verify you're using the correct timeout properties. The EndSilenceTimeoutMs property controls when the service stops listening after detecting silence. For faster results, reduce this value (the default is typically 500 ms).
2. Ensure your audio format is correctly specified. Audio format mismatches can cause processing delays. Use mono PCM WAV 16-bit 48 kHz for fastest processing.
3. Check that SegmentationSilenceTimeoutMs (used for batch segmentation) isn't being confused with EndSilenceTimeoutMs (used for session termination).

Fragmented or incomplete transcription results

If you receive partial transcription results or fragmented output:

1. Validate audio format first. Confirm your input audio is actually mono PCM 16-bit 48 kHz by checking with ffmpeg info:

   ffmpeg -i input.wav
   

   Look for: Audio: pcm_s16le, 48000 Hz, mono

2. Check audio quality. Ensure the audio file isn't corrupted or doesn't contain long silences between words. Use a tool like Audacity to inspect the waveform.

3. Verify the audio encoding. If you're uploading audio via a URL (audioUrl), ensure the remote endpoint serves the correct Content-Type header (for example, audio/wav).

Unsupported media format error

If you receive an "unsupported media format" error:

Cause: The container detected a mismatch between the file extension, the actual audio codec, or the declared format in your request.

Solutions:

1. Convert the audio to WAV format using ffmpeg (see Convert audio to recommended format).
2. Ensure the file extension matches the actual format (for example, don't name an MP3 file audio.wav).
3. If you're posting audio from a URL, verify the Content-Type header is correct.

Related content

• See the Speech containers overview.
• Review configure containers for configuration settings.
• Use more Azure AI containers.