Media Profiler

Identify basic, content-derived properties of media bytes.

AudioMediaProfile(mime_type, modality, size_bytes, duration_seconds=None, sample_rate_hz=None, channels=None) dataclass

Bases: MediaProfile

Audio profile with optional duration and audio stream rates.

Attributes:

Name	Type	Description
duration_seconds	float | None	Container duration, when available.
sample_rate_hz	int | None	Audio sampling rate, when available.
channels	int | None	Number of audio channels, when available.

ImageMediaProfile(mime_type, modality, size_bytes, width=None, height=None) dataclass

Bases: MediaProfile

Image profile with optional pixel dimensions.

Attributes:

Name	Type	Description
width	int | None	Image width in pixels, when available.
height	int | None	Image height in pixels, when available.

MediaProfile(mime_type, modality, size_bytes) dataclass

Shared, bounded properties reported for a media byte buffer.

Attributes:

Name	Type	Description
mime_type	str	Normalized MIME value detected from content bytes.
modality	str	Top-level MIME family, such as image or video; unknown when the detector reports only generic binary data.
size_bytes	int	Number of bytes inspected.

to_debug_info(*, include_rich_metadata=False)

Return scalar profile facts for normalized error diagnostics.

Parameters:

Name	Type	Description	Default
include_rich_metadata	bool	Include optional modality-specific probe fields. Defaults to False for the compact profile.	False

Returns:

Type	Description
dict[str, str | int | float]	MIME type, broad modality, and byte length, plus available rich
dict[str, str | int | float]	fields when requested.

VideoMediaProfile(mime_type, modality, size_bytes, duration_seconds=None, fps=None, width=None, height=None) dataclass

Bases: MediaProfile

Video profile with optional visual and timing metadata.

Attributes:

Name	Type	Description
duration_seconds	float | None	Container duration, when available.
fps	float | None	Video frame rate, when available.
width	int | None	Video frame width in pixels, when available.
height	int | None	Video frame height in pixels, when available.

profile_media(media, *, include_rich_metadata=False)

Detect MIME type and broad modality for bytes or an existing attachment.

The returned MIME type always comes from the content bytes. An attachment's MIME type is used only as diagnostic context if inspection fails.

Parameters:

Name	Type	Description	Default
media	bytes | Attachment	Media bytes or an Attachment. The profile MIME type is detected from the content bytes.	required
include_rich_metadata	bool	Probe optional dimensions, duration, frame rate, sample rate, and channel count. Defaults to False to keep ordinary profiling limited to inexpensive MIME identification.	False

Returns:

Type	Description
MediaProfile | ImageMediaProfile | VideoMediaProfile | AudioMediaProfile	A base or modality-specific profile containing MIME type, broad MIME
MediaProfile | ImageMediaProfile | VideoMediaProfile | AudioMediaProfile	family, and byte length; optional rich media fields are included when
MediaProfile | ImageMediaProfile | VideoMediaProfile | AudioMediaProfile	available.

Raises:

Type	Description
MediaInputInvalidError	If the input is not bytes or contains no bytes.
MediaProfilingError	If MIME detection fails or returns no valid MIME value. Generic binary MIME values are retained with an unknown modality for the consumer to handle.