Media

Media validation and profiling exception family.

`MediaInputInvalidError(*, valid_input=None, debug_info=None)`

Bases: MediaError, ValueError

Report input that cannot be resolved as a supported media source.

Use this when the input itself cannot be accepted or parsed; use MediaInputUnsupportedError when its media type is known but disallowed by an operation's allowlist.

Example

A call expects bytes or a URL, but receives an unrelated object.

from gllm_multimodal.exceptions import MediaInputInvalidError

error = MediaInputInvalidError(valid_input="Provide media bytes or an HTTP URL.")
print(error.message)

Output:

No media could be loaded from the supplied input. Provide media bytes or an HTTP URL.

Initialize the error with the accepted input forms for this call.

Parameters:

Name	Type	Description	Default
`valid_input`	`str \| None`	Description of accepted input forms. Defaults to guidance for supplying bytes, base64 data, a local path, or a URL.	`None`
`debug_info`	`DebugInfo \| None`	Optional diagnostic context, sanitized before storage.	`None`

`MediaInputUnsupportedError(*, mime_type=None, supported_mime_types=(), input_kind=None, supported_input_kinds=(), debug_info=None)`

Bases: MediaError, ValueError

Report valid media or a valid source form an operation does not support.

When an allowlist is supplied, the safe message and serializer include its normalized MIME patterns or supported input forms so callers can choose an accepted input. A media type is represented by its MIME type, such as image/png.

Example

A frame extractor accepts video files, but receives a PNG image.

from textwrap import fill
from gllm_multimodal.exceptions import MediaInputUnsupportedError

error = MediaInputUnsupportedError(
    mime_type="image/png",
    supported_mime_types=("video/mp4",),
)
print(fill(error.message, width=100))

Output:

The input is valid, but this operation does not support media type (MIME type image/png). Use one of
these media types: video/mp4.

Initialize an unsupported media type or source form error.

Parameters:

Name	Type	Description	Default
`mime_type`	`str \| None`	Detected or declared media type, represented as a MIME type, that the operation rejected.	`None`
`supported_mime_types`	`tuple[str, ...] \| list[str]`	Accepted media types represented as MIME types or wildcard patterns, included in the error message.	`()`
`input_kind`	`str \| None`	Rejected input form, such as `"url"` or `"path"`.	`None`
`supported_input_kinds`	`tuple[str, ...] \| list[str]`	Input forms accepted by the operation, such as `("bytes",)`.	`()`
`debug_info`	`DebugInfo \| None`	Optional diagnostic fields to sanitize and retain.	`None`

Raises:

Type	Description
`ValueError`	If neither a MIME type nor an input kind is supplied, or if a supplied value is malformed or unsupported.

`to_safe_dict(*, include_debug_info=False)`

Return safe fields and accepted media types or input forms.

Parameters:

Name	Type	Description	Default
`include_debug_info`	`bool`	Include sanitized diagnostic context.	`False`

Returns:

Type	Description
`dict[str, Any]`	Public error fields, optional diagnostics, and optional accepted
`dict[str, Any]`	media types or input forms.

`MediaProfilingError(*, debug_info=None, _message=None, message_values=None)`

Bases: MediaError, ValueError

Report that non-empty bytes could not be identified as a media format.

Use this when inspecting nonempty bytes cannot determine the media format.

Example

Reject bytes that a media format detector cannot identify.

from textwrap import fill
from gllm_multimodal.exceptions import MediaProfilingError

error = MediaProfilingError()
print(fill(error.message, width=100))

Output:

We could not identify a media format from the supplied bytes. Provide the bytes of a supported media
file or try a different file.

`MediaTrackMissingError(*, track, debug_info=None)`

Bases: MediaError, ValueError

Report media that lacks a track required by the selected operation.

Use this only after the media has loaded and its audio or video tracks have been inspected. A failed inspection is an operation failure instead.

Example

Frame streaming needs a video track, but the supplied file has only audio.

from textwrap import fill
from gllm_multimodal.exceptions import MediaTrackMissingError

error = MediaTrackMissingError(track="video")
print(fill(error.message, width=100))

Output:

This media has no readable video track. Provide media with a readable video track or choose an
operation that does not require one.

Initialize the error for a required audio or video track.

Parameters:

Name	Type	Description	Default
`track`	`str`	Required track type, either `"audio"` or `"video"`.	required
`debug_info`	`DebugInfo \| None`	Optional diagnostic context, sanitized before storage.	`None`

Raises:

Type	Description
`ValueError`	If `track` is not audio or video.