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 ¶

probe(
    filename: str | Path,
    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 (default: "ffprobe")	`'ffprobe'`
`timeout`	`int \| None`	Maximum time in seconds to wait for ffprobe to complete (default: None, wait indefinitely)	`None`
`**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'])}")