Audio To Text Utils
Utility functions for the audio to text process.
convert_audio_to_mono_flac(input_audio_bytes)
Convert audio binary data to mono FLAC format.
This method standardizes the audio format to mono FLAC to simplify processing by having a consistent file extension and single audio channel, while preserving the audio information.
This method performs two operations: 1. Converts the input audio to mono (single channel) 2. Encodes the audio in FLAC format for optimal speech recognition
FLAC (Free Lossless Audio Codec) is chosen because: 1. Lossless compression preserves audio quality for accurate transcription 2. More bandwidth efficient compared to uncompressed formats like LINEAR16 3. supports variable bit depths (16/24-bit) automatically -> no need to specify sample rate
Mono channel is chosen because: 1. Speech recognition models are optimized for single-channel audio 2. Reduces bandwidth and processing overhead 3. Simplifies processing by avoiding multi-channel complexity 4. Ensures consistent results across different input formats
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_audio_bytes
|
bytes
|
Input audio data in binary format. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bytes |
bytes
|
Audio data converted to mono FLAC format. |
detect_audio_format(audio_binary_data)
Detect the audio format from binary data.
This function attempts to identify the audio format by reading the audio file metadata. The format detection is performed using the soundfile library, which can identify common audio formats like MP3, WAV, FLAC, OGG, etc.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_binary_data
|
bytes
|
The binary data of the audio. |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
str | None: The detected audio format in lowercase (e.g., 'mp3', 'wav', 'flac'), or None if detection fails. |
get_audio_duration(audio_binary_data)
Get the duration of the audio in seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_binary_data
|
bytes
|
The binary data of the audio. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
float |
float
|
The duration of the audio in seconds. |
get_audio_from_base64(audio_source)
Attempt to decode a base64 encoded audio string and verify if it's valid audio data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_source
|
str
|
The potential base64 encoded audio string to decode. |
required |
Returns:
| Type | Description |
|---|---|
bytes | None
|
bytes | None: The decoded audio data if successful and valid, None otherwise. |
get_audio_from_downloadable_url(audio_source, timeout=1 * 60)
Get the audio from a downloadable URL and return its binary data if valid.
This function attempts to download audio content from a downloadable URL (e.g. Google Drive, OneDrive) and validates that the downloaded content is audio data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_source
|
str
|
The downloadable URL of the audio file. |
required |
timeout
|
int
|
The timeout for the HTTP request in seconds. Defaults to 1 minute. |
1 * 60
|
Returns:
| Type | Description |
|---|---|
bytes | None
|
bytes | None: Binary data of the audio file if valid audio content is downloaded, None if the request fails or content is not valid audio. |
get_audio_from_file_path(audio_source)
Read audio file and return its binary data if valid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_source
|
str
|
Path to the audio file. |
required |
Returns:
| Type | Description |
|---|---|
bytes | None
|
bytes | None: Binary data of the audio file if valid, None otherwise. |
get_audio_from_youtube_url(audio_source, proxy=None)
Extract audio from a YouTube video URL and return it as binary data.
This function downloads a YouTube video and extracts its audio track in MP3 format. The audio is stored in memory and validated before being returned.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_source
|
str
|
The YouTube video URL to extract audio from. |
required |
proxy
|
str | None
|
The proxy URL to use for the YouTube request. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
bytes | None
|
bytes | None: Binary audio data if successfully downloaded and valid, None if download fails or audio is invalid. |
infer_audio_format_from_path(file_path)
Infer audio format from a local file path extension.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
str
|
Path to a local audio file. |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
str | None: Normalized format if the extension is present, otherwise None. |
is_binary_data_audio(audio_binary_data)
Check if the binary data is a valid audio file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_binary_data
|
bytes
|
The binary data to check. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the binary data is a valid audio file, False otherwise. |
is_youtube_url(source)
Check if the audio source is a YouTube URL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
str
|
The audio source to check. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the audio source is a YouTube URL, False otherwise. |
normalize_audio_format(audio_format)
Normalize a detected audio format label.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_format
|
str
|
Raw format label from detection or a file extension. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Normalized lowercase format label. |
resolve_audio_source(audio_source, youtube_proxy_url=None)
Resolve an audio source to raw bytes, trying all supported input types in order.
This function centralizes audio source resolution by attempting each supported input type in sequence:
bytes— returned as-is if already binary audio data.- File path — read from local disk.
- Base64 string — decoded and validated.
- Downloadable URL — fetched via HTTP (e.g. Google Drive, OneDrive).
- YouTube URL — audio extracted with yt-dlp.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audio_source
|
str | bytes
|
The audio source to resolve. Can be raw bytes, a local file path, a base64-encoded string, a downloadable URL, or a YouTube URL. |
required |
youtube_proxy_url
|
str | None
|
Proxy URL forwarded to
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
bytes |
bytes
|
The resolved audio binary data. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the audio source cannot be resolved by any of the supported strategies. |