`ffmpegio.analyze`: Frame Metadata Analysis Module

There are a number of FFmpeg filters which analyze video and audio streams and inject per-frame results into frame metadata to be used in a later stage of a filtergraph. ffmpegio.analyze.run retrieves the injected metadata by appending metadata and ametadata filters and logs the frame metadata outputs. You can use either the supplied Python classes or a custom class, which conforms to MetadataLogger interface to specify the FFmpeg filter and to log its output.

Simple examples

The following example detects intervals of pure black frames within the first 30 seconds of the video:

>>> from ffmpegio import analyze as ffa
>>> logger, *_ = ffa.run("input.mp4", ffa.BlackDetect(pix_th=0.0), t=30)
>>> print(logger.output)
Black(interval=[[0.0, 0.166667]])

Assign options (e.g., pix_th) of the underlying FFmpeg analysis filter (e.g., blackdetect) as keyword options of its logger object (e.g., BlackDetect)
FFmpeg input options (e.g., t) can be assigned as the keyword arguments of run().
The logger output is a namedtuple.

Next example analyzes the audio stream and plot its spectral entropy of the first channel:

>>> logger,*_ = ffa.run("input.mp4", ffa.ASpectralStats(measure='entropy'))
>>> plt.plot(logger.output.time, logger.output.entropy[0])

Finally, multiple loggers can run simultaneously:

>>> loggers = [
...   ffa.AStats(),       # time domain statistics of audio channels
...   ffa.BBox(),         # bounding box of video frames
...   ffa.BlackDetect()]  # detect black frame intervals
...
>>> ffa.run("input.mp4", *loggers, t=10)
>>> print(loggers[0].output)
>>> print(loggers[1].output)
>>> print(loggers[2].output)

Available filter loggers

Following loggers are currently available as a part of the analyze module

Type	Python class	FFmpeg filter	Description
audio	`APhaseMeter`	aphasemeter	Measures phase of input audio
	`ASpectralStats`	aspectralstats	Frequency domain statistical information
	`AStats`	astats	Time domain statistical information
	`SilenceDetect`	silencedetect	Detect silence
video	`BBox`	bbox	Compute the bounding box
	`BlackDetect`	blackdetect	Detect intervals of black frames
	`BlackFrame`	blackframe	Detect black frames
	`BlurDetect`	blurdetect	Detect blurriness of frames
	`FreezeDetect`	freezedetect	Detect frozen video
	`PSNR`	psnr	Compute peak signal to noise ratio
	`ScDet`	scdet	Detect video scene change

Analyze API Reference

`ffmpegio.analyze.run`	analyze media streams' frames with FFmpeg filters
`ffmpegio.video.detect`	detect video frame features
`ffmpegio.audio.detect`	detect audio stream features
`ffmpegio.analyze.MetadataLogger`	Abstract class for `analyze.run()` frame metadata loggers

ffmpegio.analyze.run(url, *loggers, references=None, time_units=None, start_at_zero=False, progress=None, show_log=None, **input_options)

analyze media streams’ frames with FFmpeg filters

Parameters:

url (str) – video file url
*loggers (tuple[MetadataLogger]) – class object with the metadata logging interface
references (seq of str or seq of (str, dict), optional) – reference input urls or pairs of url and input option dict, defaults to None
ss (int, float, str, optional) – start time to process, defaults to None
t (int, float, str, optional) – duration of data to process, defaults to None
to (int, float, str, optional) – stop processing at this time (ignored if t is also specified), defaults to None
time_units ('seconds', 'frames', 'pts', optional) – units of detected time stamps (not for ss, t, or to), defaults to None (‘seconds’)
start_at_zero (bool, optional) – ignore start time, defaults to False
progress (callable object, optional) – progress callback function, defaults to None
show_log (bool, optional) – True to show FFmpeg log messages on the console, defaults to None (no show/capture)
**options (dict, optional) – FFmpeg (primary) input options.

Returns:

logger objects passed in

Return type:

tuple[MetadataLogger]

ffmpegio.video.detect(url, *features, ss=None, t=None, to=None, start_at_zero=False, time_units=None, progress=None, show_log=None, scene_all_scores=False, **options)

detect video frame features

Parameters:

url (str) – video file url

*features (tuple, a subset of ('scene', 'black', 'blackframe', 'freeze'), optional) –

specify frame features to detect:

feature	FFmpeg filter	description
’scene’	scdet	Detect video scene change
’black’	blackdetect	Detect video intervals that are (almost) completely black
’blackframe’	blackframe	Detect frames that are (almost) completely black
’freeze’	freezedetect	Detect frozen video

defaults to include all the features

ss (int, float, str, optional) – start time to process, defaults to None
t (int, float, str, optional) – duration of data to process, defaults to None
to (int, float, str, optional) – stop processing at this time (ignored if t is also specified), defaults to None
start_at_zero (bool, optional) – ignore start time, defaults to False
time_units ('seconds', 'frames', 'pts', optional) – units of detected time stamps (not for ss, t, or to), defaults to None (‘seconds’)
progress (callable object, optional) – progress callback function, defaults to None
show_log (bool, optional) – True to show FFmpeg log messages on the console, defaults to None (no show/capture)
scene_all_scores (bool, optional) – (only for ‘scene’ feature) True to return scores for all frames, defaults to False
**options (dict, optional) – FFmpeg detector filter options. For a single-feature call, the FFmpeg filter options of the specified feature can be specified directly as keyword arguments. For a multiple-feature call, options for each individual FFmpeg filter can be specified with <feature>_options dict keyword argument. Any other arguments are treated as a common option to all FFmpeg filters. For the available options for each filter, follow the link on the feature table above to the FFmpeg documentation.

Returns:

detection outcomes. A namedtuple is returned for each feature in the order specified. All namedtuple fields contain a list with the element specified as below:

feature	named tuple field	element type	description
’scene’	’time’	numeric	Timestamp of the frame
	’change’	bool	True if scene change detected (only present if `scene_all_scores=True`)
	’score’	’float’	Absolute difference of MAFD of current and previous frame
	’mafd’	float	Mean absolute frame difference. See this commentary for detailed discussion of the MAFD.
’black’	’interval’	(numeric, numeric)	Interval of black frames
’blackframe’	’time’	numeric	Timestamp of a black frame
	’pblack’	int	Percentage of black pixels
’freeze’	’interval’	(numeric, numeric)	Interval of frozen frames

Return type:

tuple of namedtuples

Examples

ffmpegio.audio.detect(url, *features, ss=None, t=None, to=None, start_at_zero=False, time_units=None, progress=None, show_log=None, **options)

detect audio stream features

Parameters:

url (str) – audio file url
*features (tuple, a subset of ('silence',), optional) –
specify features to detect:

feature

FFmpeg filter

description

’silence’

silencedetect

Detect silence in an audio stream

defaults to include all the features
ss (int, float, str, optional) – start time to process, defaults to None
t (int, float, str, optional) – duration of data to process, defaults to None
to (int, float, str, optional) – stop processing at this time (ignored if t is also specified), defaults to None
start_at_zero (bool, optional) – ignore start time, defaults to False
time_units ('seconds', 'frames', 'pts', optional) – units of detected time stamps (not for ss, t, or to), defaults to None (‘seconds’)
progress (callable object, optional) – progress callback function, defaults to None
show_log (bool, optional) – True to show FFmpeg log messages on the console, defaults to None (no show/capture)
**options (dict, optional) – FFmpeg detector filter options. For a single-feature call, the FFmpeg filter options of the specified feature can be specified directly as keyword arguments. For a multiple-feature call, options for each individual FFmpeg filter can be specified with <feature>_options dict keyword argument. Any other arguments are treated as a common option to all FFmpeg filters. For the available options for each filter, follow the link on the feature table above to the FFmpeg documentation.

Returns:

detection outcomes. A namedtuple is returned for each feature in the order specified. All namedtuple fields contain a list with the element specified as below:

feature	named tuple field	element type	description
’silence’	’interval’	(numeric, numeric)	(only if mono=False) Silent interval
	’chX’	(numeric, numeric)	(only if mono=True) Silent interval of channel X (multiple)

Return type:

tuple of namedtuples

Examples

class ffmpegio.analyze.MetadataLogger

Abstract class for analyze.run() frame metadata loggers

property filter: Filter: filter specification expression to be used in FilterGraph

filter_name: str: (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['video', 'audio']: (static) target stream media type

meta_names: Tuple[str]: (static) metadata names to be logged

options: dict[str, Any]: FFmpeg filter options (value must be stringifiable)

property output: NamedTuple: log output as a namedtuple

property ref_in: str | None

None)

Type:: stream specifier for reference input url only if applicable (default

class ffmpegio.analyze.APhaseMeter(**options)

Logger for FFmpeg aphasemeter filter to measure stereo audio phase differences

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `aphasemeter` filter options

name	type	description
phasing	bool	mono and out-of-phase detection output (default false)
tolerance	float	phase tolerance for mono detection (from 0 to 1) (default 0). Alias param name: t
angle	float	angle threshold for out-of-phase detection (from 90 to 180) (default 170). Alias param name: a
duration	duration	minimum mono or out-of-phase duration in seconds (default 2). Alias param name: d

class Phase(time, value, mono_interval, out_phase_interval)

output log namedtuple subclass

Parameters:

time (List[float | int])
value (List[float])
mono_interval (List[float | int | None, float | int | None])
out_phase_interval (List[float | int | None, float | int | None])

mono_interval: List[float | int | None, float | int | None]: intervals in which stereo stream is in-phase

out_phase_interval: List[float | int | None, float | int | None]: intervals in which stereo stream is out-of-phase

time: List[float | int]: timestamps in seconds, frames, or pts

value: List[float]: detected phases

property filter: filter specification expression to be used in FilterGraph

filter_name: Literal['aphasemeter'] = 'aphasemeter': (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['audio'] = 'audio': (static) target stream media type

meta_names: Tuple[Literal['aphasemeter']] = ('aphasemeter',): (static) metadata names to be logged

property output: Phase: log output

class ffmpegio.analyze.ASpectralStats(**options)

Logger for FFmpeg aspectralstats filter to measure frequency domain statistics about audio frames

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `aspectralstats` filter options

name	type	description
win_size	int	set the window size (from 32 to 65536) (default 2048)
win_func	str\|int	set window function (see below for the accepted values) (default hann)
overlap	float	set window overlap (from 0 to 1) (default 0.5)

Supported `win_func` option values

The win_func option can be set to any of the following window function by its name or id:

name	id	desc
bartlett	4	Bartlett
bhann	11	Bartlett-Hann
bharris	7	Blackman-Harris
blackman	3	Blackman
bnuttall	8	Blackman-Nuttall
bohman	19	Bohman
cauchy	16	Cauchy
dolph	15	Dolph-Chebyshev
flattop	6	Flat-top
gauss	13	Gauss
hamming	2	Hamming
hann	1	Hann
hanning	1	Hanning
lanczos	12	Lanczos
nuttall	10	Nuttall
parzen	17	Parzen
poisson	18	Poisson
rect	0	Rectangular
sine	9	Sine
tukey	14	Tukey
welch	5	Welch

filter_name: Literal['aspectralstats'] = 'aspectralstats': (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['audio'] = 'audio': (static) target stream media type

meta_names: Tuple[Literal['aspectralstats']] = ('aspectralstats',): (static) metadata names to be logged

property output

log output

ASpectalStats’ log output is a dynamically composed namedtuple. Each statistic is stored in its own named field as a dict of per-channel list of measurements. The dict is keyed by the audio channel ids (positive int). One exception is the time field, which is a plain list of the starting timestamps of analysis windows.

Here is the full list of possible fields for FFmpeg v5:

time
mean
variance
centroid
spread
skewness
kurtosis
entropy
flatness
crest
flux
slope
decrease
rolloff

All the stats are computed in the linear scale (not in dB).

class ffmpegio.analyze.AStats(**options)

Logger for FFmpeg astats filter to measure time domain statistics per audio frames

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `astats` filter options

name	type	description
length	float	window length (from 0 to 10) (default 0.05)
metadata	bool	true to inject metadata in the filtergraph (default false)
reset	int	number of frames over which cumulative stats are calculated before being reset (from 0 to INT_MAX) (default 0)
measure_perchannel	str	parameters to measure per channel (default “all”) “none” to disable
measure_overall	str	parameters to measure overall (default “all”) “none” to disable

Measurement parameters

Following parameters can be used for measure_perchannel and measure_overall. To specify multiple parameters, combine them with + (plus) signs. E.g., “DC_offset+Min_level”.

DC_offset
Min_level
Max_level
Min_difference
Max_difference
Mean_difference
RMS_differenc
Peak_level
RMS_level
RMS_peak
RMS_trough
Crest_factor
Flat_factor
Peak_count
Bit_depth
Dynamic_range
Zero_crossings
Zero_crossings_rate
Noise_floor
Noise_floor_count
Entropy
Number_of_samples
Number_of_NaNs
Number_of_Infs
Number_of_denormals

property filter: filter specification expression to be used in FilterGraph

filter_name: Literal['astats'] = 'astats': (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

lavfi.astats.1.Number of Infs=0.000000 lavfi.astats.2.Number of denormals=0.000000 lavfi.astats.Overall.DC_offset=-0.000003 lavfi.astats.Overall.Min_level=-0.092316 lavfi.astats.Overall.Max_level=0.100442

media_type: Literal['audio'] = 'audio': (static) target stream media type

meta_names: Tuple[Literal['astats']] = ('astats',): (static) metadata names to be logged

property output: NamedTuple

log output

AStats’ log output is a dynamically composed namedtuple. Every field contains lists of statistics. Except for the time field, which is a plain list, the fields are a dict, each of which item keyed by the channel number in int (1, 2, …) or literal "overall" and contains a list of the statistics computed at each analysis window. The full list of possible fields for FFmpeg v5 and its individual stat datatype is shown below:

field name	datatype	description
time	float\|int	timestamps in seconds, frames, or pts
dc_offset	float	DC offset
min_level	float	Min level
max_level	float	Max level
min_difference	float	Min difference
max_difference	float	Max difference
mean_difference	float	Mean difference
rms_difference	float	RMS difference
peak_level	float	Peak level dB
rms_level	float	RMS level dB
rms_peak	float	RMS peak dB
rms_trough	float	RMS trough dB
crest_factor	float	Crest factor
flat_factor	float	Flat factor
peak_count	int	Peak count
noise_floor	float	Noise floor dB
noise_floor_count	int	Noise floor count
entropy	float	Entropy
bit_depth	int	Bit depth (available)
bit_depth2	int	Bit depth (used)
dynamic_range	float	Dynamic range
zero_crossings	float	Zero crossings
zero_crossings_rate	float	Zero crossings rate
number_of_nans	int	Number of NaNs
number_of_infs	int	Number of Infs
number_of_denormals	int	Number of denormals

class ffmpegio.analyze.SilenceDetect(**options)

Logger for FFmpeg silencedetect filter to detect silent audio intervals

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `silencedetect` filter options

name	type	description
noise	double	noise tolerance (from 0 to DBL_MAX) (default 0.001). Alias param name: n
duration	duration	minimum duration in seconds (default 2). Alias param name: d
mono	bool	check each channel separately (default false). Alias param name: m

class Silent(interval)

output log namedtuple subclass for mono=False (default)

Parameters:: interval (List[float | int | None, float | int | None])

interval: List[float | int | None, float | int | None]: pairs of start and end timestamps of frozen frame intervals

filter_name: Literal['silencedetect'] = 'silencedetect': (static) name of the FFmpeg filter to use

log(t, name, ch, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
ch (str | None) – audio channel key
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['audio'] = 'audio': (static) target stream media type

meta_names: Tuple[Literal['silence_start', 'silence_end']] = ('silence_start', 'silence_end'): (static) metadata names to be logged

property output: Silent | NamedTuple

log output

If the silentdetect filter is configured with mono=False (default), the returned log is a SilenceDetect.Silent object.

If mono=True, the returned log is a dynamically formed namedtuple of the name SilentPerCh, each of which field is named ch# (where # is an integer) and contains a list of the silent intevals of the specified audio channel.

class ffmpegio.analyze.BBox(**options)

Logger for FFmpeg bbox filter to compute bounding box for each frame

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `bbox` filter options

name	type	description
min_val	int	minimum luminance value for bounding box (from 0 to 65535) (default 16)
enable	str	support for timeline. See FFmpeg documentation.

class BBox(time, position)

output log namedtuple subclass

Parameters:

time (List[float | int])
position (List[List[int, int, int, int]])

position: List[List[int, int, int, int]]: bbox positions [x0,x1,w,h]

time: List[float | int]: timestamps in seconds, frames, or pts

filter_name: Literal['bbox'] = 'bbox': (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['video'] = 'video': (static) target stream media type

meta_names: Tuple[Literal['bbox']] = ('bbox',): (static) metadata names to be logged

property output: BBox: log output

class ffmpegio.analyze.BlackDetect(**options)

Logger for FFmpeg blackdetect filter to detect video intervals that are (almost) black

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `blackdetect` filter options

name	type	description
black_min_duration	float	set minimum detected black duration in seconds (from 0 to DBL_MAX) (default 2)
picture_black_ratio_th	float	set the picture black ratio threshold (from 0 to 1) (default 0.98). Alias param name: pic_th
pixel_black_th	float	set the pixel black threshold (from 0 to 1) (default 0.1). Alias param name: pix_th

class Black(interval)

output log namedtuple subclass

Parameters:: interval (List[float | int | None, float | int | None])

interval: List[float | int | None, float | int | None]: pairs of start and end timestamps of black intervals

filter_name: str = 'blackdetect': (static) name of the FFmpeg filter to use

log(t, name, *_)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – metadata key

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['video', 'audio'] = 'video': (static) target stream media type

meta_names: Tuple[str] = ('black_start', 'black_end'): (static) metadata names to be logged

property output: Black: log output

class ffmpegio.analyze.BlackFrame(**options)

Logger for FFmpeg blackframe filter to detect frames that are (almost) black

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `blackframe` filter options

name	type	description
amount	int	percentage of the pixels that have to be below the threshold for the frame to be considered black (from 0 to 100) (default 98)
threshold	int	threshold below which a pixel value is considered black (from 0 to 255) (default 32). Alias param name: thresh

class BlackFrames(time, pblack)

output log namedtuple subclass

Parameters:

time (List[float | int])
pblack (List[int])

pblack: List[int]: percentage of black pixels

time: List[float | int]: timestamps in seconds, frames, or pts

filter_name: str = 'blackframe': (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['video', 'audio'] = 'video': (static) target stream media type

meta_names: Tuple[str] = 'blackframe': (static) metadata names to be logged

property output: BlackFrames: log output

class ffmpegio.analyze.BlurDetect(**options)

Logger for FFmpeg blurdetect filter to detect video frames that are blurry

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `blurdetect` filter options

name	type	description
high	float	high threshold (from 0 to 1) (default 0.117647)
low	float	low threshold (from 0 to 1) (default 0.0588235)
radius	int	search radius for maxima detection (from 1 to 100) (default 50)
block_pct	int	block pooling threshold when calculating blurriness (from 1 to 100) (default 80)
block_width	int	block width for block-based abbreviation of blurriness (from -1 to INT_MAX) (default -1)
block_height	int	block height for block-based abbreviation of blurriness (from -1 to INT_MAX) (default -1)
planes	int	set planes to filter (from 0 to 15) (default 1)

class Blur(time, blur)

output log namedtuple subclass

Parameters:

time (List[float | int])
blur (List[float])

blur: List[float]: blurness score

time: List[float | int]: timestamps in seconds, frames, or pts

filter_name: Literal['blurdetect'] = 'blurdetect': (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['video'] = 'video': (static) target stream media type

meta_names: Tuple[Literal['blur']] = ('blur',): (static) metadata names to be logged

property output: Blur: log output

class ffmpegio.analyze.FreezeDetect(**options)

Logger for FFmpeg freezedetect filter to detect frozen video input

Parameters:: **options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `freezedetect` filter options

name	type	description
noise	float	noise tolerance (from 0 to 1) (default 0.001). Alias param name: n
duration	duration	minimum duration in seconds (default 2). Alias param name: d

class Frozen(interval)

output log namedtuple subclass

Parameters:: interval (List[float | int | None, float | int | None])

interval: List[float | int | None, float | int | None]: pairs of start and end timestamps of frozen frame intervals

filter_name: Literal['freezedetect'] = 'freezedetect': (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['video'] = 'video': (static) target stream media type

meta_names: Tuple[Literal['freeze']] = ('freeze',): (static) metadata names to be logged

property output: Frozen: log output

class ffmpegio.analyze.ScDet(all_scores=False, **options)

Logger for FFmpeg scdet filter to detect video scene change

Parameters:

all_scores (bool, optional) – True to return scene scores on all the frames, defaults to False
**options (dict[str, any]) – FFmpeg filter options (see below)

FFmpeg `scdet` filter options

name	type	description
threshold	float	Set the scene change detection threshold as a percentage of maximum change. Good values are in the [8.0, 14.0] range. The range for threshold is [0., 100.]. Defaults to 10. Alias param name: t
sc_pass	int	Set the flag to pass scene change frames to the next filter. Default value is 0 You can enable it if you want to get snapshot of scene change frames only. Alias param name: s

class AllScenes(time, changed, score, mafd)

Output namedtuple subclass for all_scores=True

Parameters:

time (Tuple[float | int])
changed (Tuple[bool])
score (Tuple[float])
mafd (Tuple[float])

changed: Tuple[bool]: scene change flags

mafd: Tuple[float]: mafd scores

score: Tuple[float]: scene change scores

time: Tuple[float | int]: log times

class Scenes(time, score, mafd)

Default output namedtuple subclass

Parameters:

time (Tuple[float | int])
score (Tuple[float])
mafd (Tuple[float])

mafd: Tuple[float]: mafd scores

score: Tuple[float]: scene change scores

time: Tuple[float | int]: log times

filter_name: str = 'scdet': (static) name of the FFmpeg filter to use

log(t, name, key, value)

log the metadata

Parameters:

t (float|int) – timestamps in seconds, frames, or pts
name (str) – one of the class’ meta_names
key (str | None) – secondary metadata key if found
value (str) – metadata value

This method is called by analyze.run() if a metadata line begins with one of the class’ meta_names entry. The log method shall store the metadata info in a private storage property of the class so they can be returned later by the output property.

media_type: Literal['video', 'audio'] = 'video': (static) target stream media type

meta_names: Tuple[str] = ('scd',): (static) metadata names to be logged

options: dict[str, Any]: FFmpeg filter options (value must be stringifiable)

property output: Scenes | AllScenes: log output. Scenes if all_scores==True else AllScenes

ffmpegio.analyze: Frame Metadata Analysis Module

Simple examples

Available filter loggers

Analyze API Reference

FFmpeg aphasemeter filter options

FFmpeg aspectralstats filter options

Supported win_func option values

FFmpeg astats filter options

Measurement parameters

FFmpeg silencedetect filter options

FFmpeg bbox filter options

FFmpeg blackdetect filter options

FFmpeg blackframe filter options

FFmpeg blurdetect filter options

FFmpeg freezedetect filter options

FFmpeg scdet filter options

`ffmpegio.analyze`: Frame Metadata Analysis Module

FFmpeg `aphasemeter` filter options

FFmpeg `aspectralstats` filter options

Supported `win_func` option values

FFmpeg `astats` filter options

FFmpeg `silencedetect` filter options

FFmpeg `bbox` filter options

FFmpeg `blackdetect` filter options

FFmpeg `blackframe` filter options

FFmpeg `blurdetect` filter options

FFmpeg `freezedetect` filter options

FFmpeg `scdet` filter options