Media Probe Function References

ffmpegio.probe module contains a full-featured ffprobe wrapper function ffmpegio.probe.full_details() and its derivative functions, which are tailored to retrieve specific type of information from a media file or stream.

List of Functions

`ffmpegio.probe.format_basic`	Retrieve basic media format info
`ffmpegio.probe.streams_basic`	Retrieve basic info of media streams
`ffmpegio.probe.video_streams_basic`	Retrieve basic info of video streams
`ffmpegio.probe.audio_streams_basic`	Retrieve basic info of audio streams
`ffmpegio.probe.full_details`	Retrieve full details of a media file or stream
`ffmpegio.probe.query`	Query specific fields of media format or stream
`ffmpegio.probe.frames`	get frame information

Argument Type References

ffmpegio.probe.IntervalSpec

Union type to specify the FFprobe read_intervals option

FFprobe will seek to the interval starting point and will continue reading from that. An IntervalSpec argument can be specified in multiple ways to form the FFprobe read_intervals option:

str - pass through the argument as-is to ffprobe
int - read this numbers of packets to read from the beginning of the file
float - read packets over this duration in seconds from the beginning of the file
tuple[str|float, str|int|float] - sets (start, end) points
- start: str = as-is, float = starting time in seconds
- end: str = as-is, int = offset in # of packets, float = offset in seconds
dict - specifies start and end points with the following keys:
- 'start' - (str|float) start time
- 'start_offset' - (str|float) start time offset from the previous read. Ignored if 'start' is present.
- 'end' - (str|float) end time
- 'end_offset' - (str|float|int) end time offset from the start time. Ignored if 'end' is present.

Function References

ffmpegio.probe.format_basic(url, entries=None, keep_optional_fields=None, keep_str_values=False, cache_output=False, sp_kwargs=None)

Retrieve basic media format info

Parameters:

url (str or seekable file-like object or bytes-like object) – URL of the media file/stream
entries (seq of str) – specify to narrow which information entries to retrieve. Default to None, to return all entries
keep_optional_fields (bool, optional) – True to return a missing optional field in the returned dict with None or “N/A” (if keep_str_values is True) as its value
keep_str_values (bool, optional) – True to keep all field values as str, defaults to False to convert numeric values
cache_output (bool, optional) – True to cache FFprobe output, defaults to False
sp_kwargs (dict[str, Any], optional) – Additional keyword arguments for subprocess.run(), default to None

Returns:

set of media format information.

Return type:

dict

Media Format Information Entries

name	type
filename	int
nb_streams	str
format_name	str
start_time	float
duration	float

ffmpegio.probe.streams_basic(url, entries=None, keep_optional_fields=None, keep_str_values=False, cache_output=False, sp_kwargs=None)

Retrieve basic info of media streams

Parameters:

url (str or seekable file-like object or bytes-like object) – URL of the media file/stream
entries (seq of str, optional) – specify to narrow which stream entries to retrieve. Default to None, returning all entries
keep_optional_fields (bool, optional) – True to return a missing optional field in the returned dict with None or “N/A” (if keep_str_values is True) as its value
keep_str_values (bool, optional) – True to keep all field values as str, defaults to False to convert numeric values
cache_output (bool, optional) – True to cache FFprobe output, defaults to False
sp_kwargs (dict[str, Any], optional) – Additional keyword arguments for subprocess.run(), default to None

Returns:

List of media stream information.

Return type:

list of dict

Media Stream Information dict Entries

name	type
index	int
codec_name	str
codec_type	str

ffmpegio.probe.video_streams_basic(url, index=None, entries=None, keep_optional_fields=None, keep_str_values=False, cache_output=False, sp_kwargs=None)

Retrieve basic info of video streams

Parameters:

url (str or seekable file-like object or bytes-like object) – URL of the media file/stream
index (int, optional) – video stream index. 0=first video stream. Defaults to None, which returns info of all video streams
entries (seq of str) – specify to narrow which information entries to retrieve. Default to None, to return all entries
keep_optional_fields (bool, optional) – True to return a missing optional field in the returned dict with None or “N/A” (if keep_str_values is True) as its value
keep_str_values (bool, optional) – True to keep all field values as str, defaults to False to convert numeric values
cache_output (bool, optional) – True to cache FFprobe output, defaults to False
sp_kwargs (dict[str, Any], optional) – Additional keyword arguments for subprocess.run(), default to None

Returns:

List of video stream information.

Return type:

list of dict

Video Stream Information Entries

name	type
index	int
codec_name	str
width	int
height	int
sample_aspect_ratio	Fractions
display_aspect_ratio	Fractions
pix_fmt	str
start_time	float
duration	float
frame_rate	Fractions
nb_frames	int

ffmpegio.probe.audio_streams_basic(url, index=None, entries=None, keep_optional_fields=None, keep_str_values=False, cache_output=False, sp_kwargs=None)

Retrieve basic info of audio streams

Parameters:

url (str or seekable file-like object or bytes-like object) – URL of the media file/stream
index (int, optional) – audio stream index. 0=first audio stream. Defaults to None, which returns info of all audio streams
entries (seq of str) – specify to narrow which information entries to retrieve. Default to None, to return all entries
keep_optional_fields (bool, optional) – True to return a missing optional field in the returned dict with None or “N/A” (if keep_str_values is True) as its value
keep_str_values (bool, optional) – True to keep all field values as str, defaults to False to convert numeric values
cache_output (bool, optional) – True to cache FFprobe output, defaults to False
sp_kwargs (dict[str, Any], optional) – Additional keyword arguments for subprocess.run(), default to None

Returns:

List of audio stream information.

Return type:

list of dict

Audio Stream Information Entries

name

type

index

int

codec_name

str

sample_fmt

str

sample_rate

int

channels

int

channel_layout

str

start_time

float

duration

float

nb_samples

int

ffmpegio.probe.full_details(url, show_format=True, show_streams=True, show_programs=False, show_chapters=False, select_streams=None, keep_str_values=False, cache_output=False, sp_kwargs=None)

Retrieve full details of a media file or stream

Parameters:

url (str or seekable file-like object or bytes-like object) – URL of the media file/stream
show_format (bool, optional) – True to return format info, defaults to True
show_streams (bool, optional) – True to return stream info, defaults to True
show_programs (bool, optional) – True to return program info, defaults to False
show_chapters (bool, optional) – True to return chapter info, defaults to False
select_streams (str, int, optional) – Stream specifier of the streams to get info of, defaults to None to retrieve all
keep_str_values (bool, optional) – True to keep all field values as str, defaults to False to convert numeric values
cache_output (bool, optional) – True to cache FFprobe output, defaults to False
sp_kwargs (dict[str, Any], optional) – Additional keyword arguments for subprocess.run(), default to None

Returns:

media file information

Return type:

dict[str, str|Number|Fraction]

ffmpegio.probe.query(url, streams=None, fields=None, keep_optional_fields=None, keep_str_values=False, cache_output=False, sp_kwargs=None)

Query specific fields of media format or stream

Parameters:

url (str or seekable file-like object or bytes-like object) – URL of the media file/stream
streams (str, int, bool, optional) – stream specifier, defaults to None to get format
fields (sequence of str, optional) – list of format/stream fields to retrieve, defaults to None (all fields)
keep_optional_fields (bool, optional) – True to return a missing optional field in the returned dict with None or “N/A” (if keep_str_values is True) as its value
keep_str_values (bool, optional) – True to keep all field values as str, defaults to False to convert numeric values
cache_output (bool, optional) – True to cache FFprobe output, defaults to False
sp_kwargs (dict[str, Any], optional) – Additional keyword arguments for subprocess.run(), default to None

Returns:

field name-value dict. If streams argument is given but does not specify index, a list of dict is returned instead

Return type:

dict or list or dict

Note: Unlike video_stream_basic() and audio_stream_basic(),: query() does not process ffprobe output except for the conversion from str to float/int.

ffmpegio.probe.frames(url, entries=None, streams=None, intervals=None, accurate_time=False, sp_kwargs=None)

get frame information

Parameters:

url (str or seekable file-like object or bytes-like object) – URL of the media file/stream
entries (str or seq[str], optional) – names of frame attributes, defaults to None (get all attributes)
stream (str or int, optional) – stream specifier of the stream to retrieve the data of, defaults to None to get all streams
intervals (IntervalSpec or Sequence[IntervalSpec], optional) – time intervals to retrieve the data, see below for the details, defaults to None (get all)
accurate_time (bool | None) – True to return all ‘*_time’ attributes to be computed from associated timestamps and stream timebase, defaults to False (= us accuracy)
accurate_time – bool, optional
sp_kwargs (dict[str, Any], optional) – Additional keyword arguments for subprocess.run(), default to None
streams (str | int | None)

Returns:

frame information. list of dictionary if entries is None or a sequence; list of the selected entry if entries is str (i.e., a single entry)

Return type:

list[dict] or list[str|int|float]