probe ¶

Module for analyzing media files with ffprobe.

This module provides functionality to extract detailed metadata from media files using FFmpeg's ffprobe utility. It returns a structured representation of the file's format, streams, and other relevant information.

Functions:

Name	Description
`probe`	Analyze a media file using ffprobe and return its metadata as a dictionary.
`probe_obj`	Analyze a media file using ffprobe and return its metadata as a dataclass.

probe ¶

probe(
    filename: str | Path,
    *,
    show_program_version: bool = False,
    show_library_versions: bool = False,
    show_pixel_formats: bool = False,
    show_packets: bool = False,
    show_frames: bool = False,
    show_programs: bool = False,
    show_streams: bool = True,
    show_chapters: bool = False,
    show_format: bool = True,
    show_error: bool = False,
    cmd: str = "ffprobe",
    timeout: int | None = None,
    **kwargs: Any
) -> dict[str, Any]

Analyze a media file using ffprobe and return its metadata as a dictionary.

This function executes ffprobe to extract detailed information about a media file, including format metadata (container format, duration, bitrate) and stream information (codecs, resolution, sample rate, etc). The result is returned as a Python dictionary parsed from ffprobe's JSON output.

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	Path to the media file to analyze	required
`cmd`	`str`	Path or name of the ffprobe executable	`'ffprobe'`
`timeout`	`int \| None`	Maximum time in seconds to wait for ffprobe to complete (default: None, wait indefinitely)	`None`
`show_program_version`	`bool`	Show the program version	`False`
`show_library_versions`	`bool`	Show the library versions	`False`
`show_pixel_formats`	`bool`	Show the pixel formats	`False`
`show_packets`	`bool`	Show the packets. Note: When both show_packets and show_frames are True, ffprobe will output a combined "packets_and_frames" section instead of separate sections.	`False`
`show_frames`	`bool`	Show the frames. Note: When both show_packets and show_frames are True, ffprobe will output a combined "packets_and_frames" section instead of separate sections.	`False`
`show_programs`	`bool`	Show the programs	`False`
`show_streams`	`bool`	Show the streams	`True`
`show_chapters`	`bool`	Show the chapters	`False`
`show_format`	`bool`	Show the format	`True`
`show_error`	`bool`	Show the error	`False`
`**kwargs`	`Any`	Additional arguments to pass to ffprobe as command line parameters (e.g., loglevel="quiet", skip_frame="nokey")	`{}`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the parsed JSON output from ffprobe with format and stream information

Raises:

Type	Description
`FFMpegExecuteError`	If ffprobe returns a non-zero exit code
`TimeoutExpired`	If the timeout is reached before ffprobe completes

Example

info = probe("video.mp4")
print(f"Duration: {float(info['format']['duration']):.2f} seconds")
print(f"Streams: {len(info['streams'])}")

probe_obj ¶

probe_obj(
    filename: str | Path,
    *,
    show_program_version: bool = False,
    show_library_versions: bool = False,
    show_pixel_formats: bool = False,
    show_packets: bool = False,
    show_frames: bool = False,
    show_programs: bool = False,
    show_streams: bool = True,
    show_chapters: bool = False,
    show_format: bool = True,
    show_error: bool = False,
    cmd: str = "ffprobe",
    timeout: int | None = None,
    **kwargs: Any
) -> ffprobeType | None

Analyze a media file using ffprobe and return its metadata as a dataclass.

This function executes ffprobe to extract detailed information about a media file, including format metadata (container format, duration, bitrate) and stream information (codecs, resolution, sample rate, etc). The result is returned as a Python dataclass parsed from ffprobe's output.

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	Path to the media file to analyze	required
`cmd`	`str`	Path or name of the ffprobe executable	`'ffprobe'`
`timeout`	`int \| None`	Maximum time in seconds to wait for ffprobe to complete (default: None, wait indefinitely)	`None`
`show_program_version`	`bool`	Show the program version	`False`
`show_library_versions`	`bool`	Show the library versions	`False`
`show_pixel_formats`	`bool`	Show the pixel formats	`False`
`show_packets`	`bool`	Show the packets. Note: When both show_packets and show_frames are True, ffprobe will output a combined "packets_and_frames" section instead of separate sections.	`False`
`show_frames`	`bool`	Show the frames. Note: When both show_packets and show_frames are True, ffprobe will output a combined "packets_and_frames" section instead of separate sections.	`False`
`show_programs`	`bool`	Show the programs	`False`
`show_streams`	`bool`	Show the streams	`True`
`show_chapters`	`bool`	Show the chapters	`False`
`show_format`	`bool`	Show the format	`True`
`show_error`	`bool`	Show the error	`False`
`**kwargs`	`Any`	Additional arguments to pass to ffprobe as command line parameters (e.g., loglevel="quiet", skip_frame="nokey")	`{}`

Returns:

Type	Description
`ffprobeType \| None`	A dataclass containing the parsed ffprobe output

Raises:

Type	Description
`FFMpegExecuteError`	If ffprobe returns a non-zero exit code
`TimeoutExpired`	If the timeout is reached before ffprobe completes

Example

info = probe_obj("video.mp4")
print(f"Duration: {float(info.format.duration):.2f} seconds")
print(f"Streams: {len(info.streams)}")