Basic I/O Function References

Basic Functions

`ffmpegio.ffmpeg_info`	Get FFmpeg version and configuration information
`ffmpegio.set_path`	Set FFmpeg and FFprobe executables
`ffmpegio.get_path`	Get the path to FFmpeg/FFprobe executable
`ffmpegio.is_ready`	True if ffmpeg and ffprobe binaries are located
`ffmpegio.video.create`	Create a video using a source video filter
`ffmpegio.video.read`	Read video frames
`ffmpegio.video.write`	Write Numpy array to a video file
`ffmpegio.video.filter`	Filter video frames.
`ffmpegio.image.create`	Create an image using a source video filter
`ffmpegio.image.read`	Read an image file or a snapshot of a video frame
`ffmpegio.image.filter`	Filter image pixels.
`ffmpegio.image.write`	Write a NumPy array to an image file.
`ffmpegio.audio.create`	Create audio data using an audio source filter
`ffmpegio.audio.read`	Read audio samples.
`ffmpegio.audio.write`	Write a NumPy array to an audio file.
`ffmpegio.audio.filter`	Filter audio samples.
`ffmpegio.open`	Open a multimedia file/stream for read/write
`ffmpegio.transcode`	Transcode media files to another format/encoding

ffmpegio.ffmpeg_info()

Get FFmpeg version and configuration information

Returns:: versions of ffmpeg and its av libraries as well as build configuration
Return type:: dict

key	type	description
‘version’	str	FFmpeg version
‘configuration’	list	list of build configuration options
‘library_versions’	dict	version numbers of dependent av libraries

ffmpegio.get_path(probe=False)

Get the path to FFmpeg/FFprobe executable

Parameters:: probe (bool, optional) – True to return FFprobe path instead, defaults to False
Returns:: Path to FFmpeg/FFprobe exectutable
Return type:: str or None

ffmpegio.set_path(ffmpeg_path=None, ffprobe_path=None)

Set FFmpeg and FFprobe executables

Parameters:

ffmpeg_path (str, optional) – Full path to either the ffmpeg executable file or to the folder housing both ffmpeg and ffprobe, defaults to None
ffprobe_path (str, optional) – Full path to the ffprobe executable file, defaults to None

Returns:

ffmpeg path, ffprobe path, and ffmpeg version

Return type:

Tuple[str,str,str]

If ffmpeg_path specifies a directory, the names of the executables are auto-set to ffmpeg and ffprobe.

If the file locations are specified, the presence of the files will be tested and an exception will be raised if both ffmpeg and ffprobe are not valid executables.

If no argument is specified, the executables are auto-detected in the following orders.

ffmpeg and ffprobe commands, i.e., the path to the parent directory is included in the system PATH environmental variable.
Run the finder plugin functions in the LIFO order and use the first valid paths. There are two plugins currently offered: ffmpegio-plugin-downloader and ffmpegio-plugin-static-ffmpeg.
In Windows, additional locations are searched (e.g., C:Program Filesffmpeg). See the documentation for the full list.

ffmpegio.is_ready()

True if ffmpeg and ffprobe binaries are located

Returns:: True if both ffmpeg and ffprobe are found
Return type:: bool

ffmpegio.video.create(expr, *args, progress=None, show_log=None, sp_kwargs=None, **options)

Create a video using a source video filter

Parameters:

name (str) – name of the source filter
*args (seq, optional) – sequential filter option arguments. Only valid for a single-filter expr, and they will overwrite the options set by expr.
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) Ignored if stream format must be retrieved automatically.
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) – Named filter options or FFmpeg options. Items are only considered as the filter options if expr is a single-filter graph, and take the precedents over general FFmpeg options. Append ‘_in’ for input option names (see FFmpeg Option References), and ‘_out’ for output option names if they conflict with the filter options.

Returns:

frame rate and video data, created by bytes_to_video plugin hook

Return type:

tuple[Fraction,object]

…seealso::: https://ffmpeg.org/ffmpeg-filters.html#Video-Sources for available video source filters

ffmpegio.video.read(url, progress=None, show_log=None, sp_kwargs=None, **options)

Read video frames

Parameters:

url (str) – URL of the video file to read.
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) Ignored if stream format must be retrieved automatically.
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) – FFmpeg options, append ‘_in’ for input option names (see FFmpeg Option References)

Returns:

frame rate and video frame data, created by bytes_to_video plugin hook

Return type:

(fractions.Fraction, object)

ffmpegio.video.write(url, rate_in, data, progress=None, overwrite=None, show_log=None, two_pass=False, pass1_omits=None, pass1_extras=None, extra_inputs=None, sp_kwargs=None, **options)

Write Numpy array to a video file

Parameters:

url (str) – URL of the video file to write.
rate_in (float, int, or fractions.Fraction) – frame rate in frames/second
data (object) – video frame data object, accessed by video_info and video_bytes plugin hooks
progress (callable object, optional) – progress callback function, defaults to None
overwrite (bool, optional) – True to overwrite if output url exists, defaults to None (auto-select)
show_log (bool, optional) – True to show FFmpeg log messages on the console, defaults to None (no show/capture)
two_pass – True to encode in 2-pass
pass1_omits (seq(str), optional) – list of output arguments to ignore in pass 1, defaults to None
pass1_extras (dict(int:dict(str)), optional) – list of additional output arguments to include in pass 1, defaults to None
extra_inputs (seq(str|(str,dict))) – list of additional input sources, defaults to None. Each source may be url string or a pair of a url string and an option dict.
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) – FFmpeg options, append ‘_in’ for input option names (see FFmpeg Option References)

ffmpegio.video.filter(expr, rate, input, progress=None, show_log=None, sp_kwargs=None, **options)

Filter video frames.

Parameters:

expr (str, None) – SISO filter graph or None if implicit filtering via output options.
rate (float, int, or fractions.Fraction) – input frame rate in frames/second
input (object) – input video frame data object, accessed by video_info and video_bytes plugin hooks
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)
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) – FFmpeg options, append ‘_in’ for input option names (see FFmpeg Option References)

Returns:

output frame rate and video frame data, created by bytes_to_video plugin hook

Return type:

object

ffmpegio.image.create(expr, *args, show_log=None, sp_kwargs=None, **options)

Create an image using a source video filter

Parameters:

name (str) – name of the source filter
*args (seq, optional) – sequential filter option arguments. Only valid for a single-filter expr, and they will overwrite the options set by expr.
show_log (bool, optional) – True to show FFmpeg log messages on the console, defaults to None (no show/capture) Ignored if stream format must be retrieved automatically.
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) – Named filter options or FFmpeg options. Items are only considered as the filter options if expr is a single-filter graph, and take the precedents over general FFmpeg options. Append ‘_in’ for input option names (see FFmpeg Option References), and ‘_out’ for output option names if they conflict with the filter options.

Returns:

image data, created by bytes_to_video plugin hook

Return type:

object

See also

https://ffmpeg.org/ffmpeg-filters.html#Audio-Sources for available audio source filters

Warning

Nearly all the source filters by default continue outputting indefinitely. Set its duration option or FFmpeg’s t (duration) or to (end time) input/output options to make sure the function returns properly.

Note

output data object is determined by the selected hook

ffmpegio.audio.read(url, progress=None, show_log=None, sp_kwargs=None, **options)

Read audio samples.

Parameters:

url (str) – URL of the audio file to read.
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) Ignored if stream format must be retrieved automatically.
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) – FFmpeg options, append ‘_in’ for input option names (see FFmpeg Option References)

Returns:

sample rate in samples/second and audio data object specified by bytes_to_audio plugin hook

Return type:

tuple(float, object)

Note

Even if start_time option is set, all the prior samples will be read. The retrieved data will be truncated before returning it to the caller. This is to ensure the timing accuracy. As such, do not use this function to perform block-wise processing. Instead use the streaming solution, see open().

ffmpegio.audio.write(url, rate_in, data, progress=None, overwrite=None, show_log=None, extra_inputs=None, sp_kwargs=None, **options)

Write a NumPy array to an audio file.

Parameters:

url (str) – URL of the audio file to write.
rate_in (int) – The sample rate in samples/second.
data (object) – input audio data object, converted to bytes by audio_bytes plugin hook .
progress (callable object, optional) – progress callback function, defaults to None
overwrite (bool, optional) – True to overwrite if output url exists, defaults to None (auto-select)
show_log (bool, optional) – True to show FFmpeg log messages on the console, defaults to None (no show/capture)
extra_inputs (seq(str|(str,dict))) – list of additional input sources, defaults to None. Each source may be url string or a pair of a url string and an option dict.
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) – FFmpeg options, append ‘_in’ for input option names (see FFmpeg Option References)

ffmpegio.audio.filter(expr, input_rate, input, sample_fmt=None, progress=None, show_log=None, sp_kwargs=None, **options)

Filter audio samples.

Parameters:

expr (str, None) – SISO filter graph or None if implicit filtering via output options.
input_rate (int) – Input sample rate in samples/second
input (object) – input audio data, accessed by audio_info() and audio_bytes() plugin hooks.
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)
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) – FFmpeg options, append ‘_in’ for input option names (see FFmpeg Option References)

Returns:

output sampling rate and audio data object, created by bytes_to_audio plugin hook

Return type:

tuple(int, object)

ffmpegio.open(url_fg, mode, rate_in=None, shape_in=None, dtype_in=None, rate=None, shape=None, **kwds)

Open a multimedia file/stream for read/write

Parameters:

url_fg (str or seq(str)) – URL of the media source/destination for file read/write or filtergraph definition for filter operation.
mode (str) – specifies the mode in which the FFmpeg is used, see below
rate_in (Fraction, float, int, optional) – (write and filter only, required) input frame rate (video) or sampling rate (audio), defaults to None
shape_in (seq of int, optional) – (write and filter only) input video frame size (height x width [x ncomponents]), or audio sample size (channels,), defaults to None
dtype_in (str, optional) – (write and filter only) input data type, defaults to None
rate (Fraction, float, int, optional) – (filter only, required) output frame rate (video write) or sample rate (audio write), defaults to None
dtype (str, optional) – (read and filter specific) output data type, defaults to None
shape (seq of int, optional) – (read and filter specific) output video frame size (height x width [x ncomponents]), or audio sample size (channels,), defaults to None
show_log (bool, optional) – True to echo the ffmpeg log to stdout, default to False
progress (Callable, optional) – progress callback function (see Progress Callback)
blocksize (int, optional) – (read and filter only) Number of frames to read by read() method, default to None (auto)
extra_inputs (List[Tuple[str,dict]], optional) – (write only) List of additional (non-pipe) inputs to pass onto FFmpeg. Each input is defined by a tuple of its url or a dict of input options, default to None
default_timeout (float, optional) – (filter only) default filter timeout in seconds, defaults to None (10 ms)
sp_kwargs (dict, optional) – Keyword arguments for FFmpeg process (see ffmpegio.ffmpegprocess.Popen), default to None
**options (dict, optional) – FFmpeg options, append ‘_in’ for input option names (see FFmpeg Option References)

Returns:

ffmpegio stream object

Start FFmpeg and open I/O link to it to perform read/write/filter operation and return a corresponding stream object. If the file cannot be opened, an error is raised. See Stream Read/Write for more examples of how to use this function.

Just like built-in open(), it is good practice to use the with keyword when dealing with ffmpegio stream objects. The advantage is that the ffmpeg process and associated threads are properly closed after ffmpeg terminates, even if an exception is raised at some point. Using with is also much shorter than writing equivalent try-finally blocks.

Examples:

Parameters:

url_fg (str)
mode (str)
rate_in (float | None)
shape_in (Tuple[int, ...] | None)
dtype_in (str | None)
rate (float | None)
shape (Tuple[int, ...] | None)

Open an MP4 file and process all the frames:

with ffmpegio.open('video_source.mp4', 'rv') as f:
    frame = f.read()
    while frame:
        # process the captured frame data
        frame = f.read()

Read an audio stream of MP4 file and write it to a FLAC file as samples are decoded:

with ffmpegio.open('video_source.mp4','ra') as rd:
    fs = rd.sample_rate
    with ffmpegio.open('video_dst.flac','wa',rate_in=fs) as wr:
        frame = rd.read()
        while frame:
            wr.write(frame)
            frame = rd.read()

Additional Notes:

Parameters:

url_fg (str)
mode (str)
rate_in (float | None)
shape_in (Tuple[int, ...] | None)
dtype_in (str | None)
rate (float | None)
shape (Tuple[int, ...] | None)

url_fg can be a string specifying either the pathname (absolute or relative to the current working directory) of the media target (file or streaming media) to be opened or a string describing the filtergraph to be implemented. Its interpretation depends on the mode argument.

mode is an optional string that specifies the mode in which the FFmpeg is opened.

Mode	Description
‘r’	read from url
‘w’	write to url
‘f’	filter data defined by fg
‘v’	operate on video stream, ‘vv’ if multi-video reader
‘a’	operate on audio stream, ‘aa’ if multi-audio reader

rate and rate_in: Video frame rates shall be given in frames/second and may be given as a number, string, or fractions.Fraction. Audio sample rate in samples/second (per channel) and shall be given as an integer or string.

Optional shape or shape_in for video defines the video frame size and number of components with a 2 or 3 element sequence: (width, height[, ncomp]). The number of components and other optional dtype (or dtype_in) implicitly define the pixel format (FFmpeg pix_fmt option):

ncomp	dtype	pix_fmt	Description
1	\|u8	gray	grayscale
1	<u2	gray10le	10-bit grayscale
1	<u2	gray12le	12-bit grayscale
1	<u2	gray14le	14-bit grayscale
1	<u2	gray16le	16-bit grayscale (default <u2 choice)
1	<f4	grayf32le	floating-point grayscale
2	\|u1	ya8	grayscale with alpha channel
2	<u2	ya16le	16-bit grayscale with alpha channel
3	\|u1	rgb24	RGB
3	<u2	rgb48le	16-bit RGB
4	\|u1	rgba	RGB with alpha transparency channel
4	<u2	rgba64le	16-bit RGB with alpha channel

For audio stream, single-element seq argument, shape or shape_in, specifies the number of channels while dtype and dtype_in determines the sample format (FFmpeg sample_fmt option):

dtype	sample_fmt
\|u1	u8
<i2	s16
<i4	s32
<f4	flt
<f8	dbl

If dtypes and shapes are not specified at the time of opening, they will be set during the first write/filter operation using the input data.

In addition, open() accepts the standard FFmpeg option keyword arguments.

ffmpegio.transcode(inputs, outputs, progress=None, overwrite=None, show_log=None, two_pass=False, pass1_omits=None, pass1_extras=None, sp_kwargs=None, **options)

Transcode media files to another format/encoding

Parameters:

inputs (str or a list of str or a sequence of (str,dict)) – url/path of the input media file or a sequence of tuples, each containing an input url and its options dict
outputs (str or sequence of (str, dict)) – url/path of the output media file or a sequence of tuples, each containing an output url and its options dict
progress (callable object, optional) – progress callback function, defaults to None
overwrite (bool, optional) – True to overwrite if output url exists, defaults to None (auto-select)
show_log (bool, optional) – True to show FFmpeg log messages on the console, defaults to None (no show/capture) Ignored if stream format must be retrieved automatically.
two_pass – True to encode in 2-pass
pass1_omits (seq(str), or seq(seq(str)) optional) – list of output arguments to ignore in pass 1, defaults to None (removes ‘c:a’ or ‘acodec’). For multiple outputs, specify use list of the list of arguments, matching the length of outputs, for per-output omission.
pass1_extras (dict(int:dict(str)), optional) – list of additional output arguments to include in pass 1, defaults to None (add ‘an’ if pass1_omits also None)
sp_kwargs (dict, optional) – dictionary with keywords passed to subprocess.run() or subprocess.Popen() call used to run the FFmpeg, defaults to None
**options (dict, optional) –
FFmpeg options. For output and global options, use FFmpeg option names as is. For input options, append “_in” to the option name. For example, r_in=2000 to force the input frame rate to 2000 frames/s (see FFmpeg Option References).

If multiple inputs or outputs are specified, these input or output options specified here are treated as common options, and the url-specific duplicate options in the inputs or outputs sequence will overwrite those specified here.

Returns:

if any of the outputs is stdout, returns output bytes

Return type:

bytes | None