Language detection

This page explains how to configure language settings for your transcription requests. By default, automatic language detection is enabled and will identify the dominant language in your audio. You can also set the language manually if you know it in advance.

Automatic language detection

Automatic language detection is enabled by default. When enabled, the model identifies the dominant language in your audio and transcribes accordingly. Language detection requires at least 15 seconds of spoken audio to identify the language accurately.

1
import assemblyai as aai
2
3
aai.settings.api_key = "<YOUR_API_KEY>"
4
5
# audio_file = "./local_file.mp3"
6
audio_file = "https://assembly.ai/wildfires.mp3"
7
8
config = aai.TranscriptionConfig(
9
  speech_models=["universal-3-pro", "universal-2"],
10
  language_detection=True
11
)
12
13
transcript = aai.Transcriber(config=config).transcribe(audio_file)
14
15
print(transcript.text)
16
print(transcript.json_response["language_code"])

Set a list of expected languages

If you’re confident the audio is in one of a few languages, provide that list via language_detection_options.expected_languages. Detection is restricted to these candidates and the model will choose the language with the highest confidence from this list. This can eliminate scenarios where Automatic Language Detection selects an unexpected language for transcription.

• Use the supported language codes (e.g., "en", "es", "fr").
• If expected_languages is not specified, it is set to ["all"] by default.

1
import assemblyai as aai
2
3
aai.settings.api_key = "<YOUR_API_KEY>"
4
5
# audio_file = "./local_file.mp3"
6
audio_file = "https://assembly.ai/wildfires.mp3"
7
8
options = aai.LanguageDetectionOptions(
9
    expected_languages=["en", "es", "fr", "de"],
10
    fallback_language="auto"
11
)
12
13
config = aai.TranscriptionConfig(
14
  speech_models=["universal-3-pro", "universal-2"],
15
  language_detection=True,
16
  language_detection_options=options
17
)
18
19
transcript = aai.Transcriber(config=config).transcribe(audio_file)
20
21
print(transcript.text)
22
print(transcript.json_response["language_code"])

Choose a fallback language

Control what language transcription should fall back to when detection cannot confidently select a language from the expected_languages list.

• Set language_detection_options.fallback_language to a specific language code (e.g., "en").
• fallback_language must be one of the language codes in expected_languages or "auto".
• When fallback_language is unspecified, it is set to "auto" by default. This tells our model to choose the fallback language from expected_languages with the highest confidence score.

1
import assemblyai as aai
2
3
aai.settings.api_key = "<YOUR_API_KEY>"
4
5
# audio_file = "./local_file.mp3"
6
audio_file = "https://assembly.ai/wildfires.mp3"
7
8
options = aai.LanguageDetectionOptions(
9
    expected_languages=["en", "es", "fr", "de"],
10
    fallback_language="en"
11
)
12
13
config = aai.TranscriptionConfig(
14
  speech_models=["universal-3-pro", "universal-2"],
15
  language_detection=True,
16
  language_detection_options=options
17
)
18
19
transcript = aai.Transcriber(config=config).transcribe(audio_file)
20
21
print(transcript.text)
22
print(transcript.json_response["language_code"])

Confidence score

If language detection is enabled, the API returns a confidence score for the detected language. The score ranges from 0.0 (low confidence) to 1.0 (high confidence).

Set a language confidence threshold

You can set the confidence threshold that must be reached if language detection is enabled. An error will be returned if the language confidence is below this threshold. Valid values are in the range [0,1] inclusive.

1
import assemblyai as aai
2
3
aai.settings.api_key = "<YOUR_API_KEY>"
4
5
# audio_file = "./local_file.mp3"
6
audio_file = "https://assembly.ai/wildfires.mp3"
7
8
config = aai.TranscriptionConfig(
9
  speech_models=["universal-3-pro", "universal-2"],
10
  language_detection=True,
11
  language_confidence_threshold=0.8
12
)
13
14
transcript = aai.Transcriber(config=config).transcribe(audio_file)
15
16
if transcript.status == "error":
17
  raise RuntimeError(f"Transcription failed: {transcript.error}")
18
else:
19
  print(transcript.json_response["language_confidence"])
20
  print(transcript.text)

Set language manually

If you already know the dominant language, you can use the language_code parameter to specify the language of the speech in your audio file. If you don’t include a language_code parameter in your request, it defaults to en_us.

1
import assemblyai as aai
2
3
aai.settings.api_key = "<YOUR_API_KEY>"
4
5
# audio_file = "./local_file.mp3"
6
audio_file = "https://assembly.ai/wildfires.mp3"
7
8
config = aai.TranscriptionConfig(
9
  speech_models=["universal-3-pro", "universal-2"],
10
  language_code="es"
11
)
12
13
transcript = aai.Transcriber(config=config).transcribe(audio_file)
14
15
if transcript.status == "error":
16
  raise RuntimeError(f"Transcription failed: {transcript.error}")
17
18
print(transcript.text)

See the Supported languages section below for all supported languages and their codes.

Supported languages

AssemblyAI offers two different levels of speech-to-text models for pre-recorded audio: Universal-3-Pro and Universal-2. Check out the Models page of our documentation to learn more about our different models and how to choose the best one for your use case.

Universal-3-Pro

Universal-2

Breakdown of Universal-2 language support