Media Utils

Utility functions for media-to-text operations in Gen AI applications.

This module provides utility functions for handling media data in various formats and sources. It includes functionality for: 1. Media validation and format checking 2. Media loading from various sources (file, URL, base64, S3, Google Drive) 3. Generic string-processing helpers used by captioning flows

combine_strings(texts)

Combine multiple strings into a single string with newline separators.

Parameters:

Name	Type	Description	Default
texts	list[str]	A list of strings to combine.	required

Returns:

Name	Type	Description
str	str	A single string containing all valid strings, where each string is on a new line.

get_media_binary(media_source, allowed_mime_types=None) async

Retrieve media binary data from various sources.

Parameters:

Name	Type	Description	Default
media_source	Any	The source of the media.	required
allowed_mime_types	list[str] | None	List of allowed MIME types or prefixes forwarded to is_valid_binary_data. When None, the default allowlist ("image/", "video/") is used. Defaults to None.	None

Returns:

Type	Description
tuple[bytes | None, str | None]	tuple[bytes | None, str | None]: The media binary data and filename. Filename is None when the source is raw bytes or base64 and no filename is available.

Raises:

Type	Description
ValueError	If the media source format is not supported or the MIME type is not allowed.

get_media_from_base64(media_source, allowed_mime_types=None)

Decode and validate a base64 encoded media string.

Parameters:

Name	Type	Description	Default
media_source	str	The base64 encoded media string to decode.	required
allowed_mime_types	list[str] | None	List of allowed MIME types or prefixes forwarded to is_valid_binary_data. When None, the default allowlist ("image/", "video/") is used. Defaults to None.	None

Returns:

Type	Description
bytes | None	bytes | None: The decoded media binary data if successful and valid, otherwise None.

get_unique_non_empty_strings(texts)

Get unique non-empty strings from a list of strings and remove whitespace.

Parameters:

Name	Type	Description	Default
texts	list[str]	A list of strings to combine.	required

Returns:

Type	Description
list[str]	list[str]: A list of strings where each string is not empty or whitespace-only.

is_valid_binary_data(media_binary_data, allowed_mime_types=None)

Validate if the provided binary data represents a valid file based on MIME type.

Parameters:

Name	Type	Description	Default
media_binary_data	bytes	The binary data to validate.	required
allowed_mime_types	list[str] | None	List of allowed MIME types or prefixes. Each entry is matched as a prefix or exact value. When None, the default allowlist of ("image/", "video/") is used. Defaults to None.	None

Returns:

Name	Type	Description
bool	bool	True if the binary data represents a valid file based on criteria, False otherwise.