Convenience shortcut functions

The module avtk.backends.ffmpeg.shortcuts contains convenience helpers for often-used functionality of the ffmpeg backend.

These functions are just wrappers around the lower-level FFmpeg and Probe modules.

THUMBNAIL_FORMATS = ['png', 'jpg', 'gif', 'tiff', 'bmp']

Supported thumbnail formats

inspect(source)

Inspects a media file and returns information about it.

See the MediaInfo documentation for a detailed description of the returned information.

Parameters

source (str) – Local file path or stream URL to inspect

Returns

Information about the inspected file or stream

Return type

MediaInfo

Raises

NoMediaError – if source doesn’t exist or is of unknown format

Example:

>>> from avtk.backends.ffmpeg.shortcuts import inspect

>>> info = inspect('test-media/video/sintel.mkv')
>>> info.format.duration
datetime.timedelta(seconds=5, microseconds=24000)
>>> info.format.bit_rate
2657539
>>> info.has_video
True
>>> info.video_streams[0].codec
<Codec(name=h264, type=video)>
>>> info.has_audio
True
>>> info.audio_streams[0].codec
<Codec(name=ac3, type=audio)>
>>> info.has_subtitles
True
get_thumbnail(source, seek, fmt='png')

Extracts a thumbnail from a video file.

Parameters

  • source (str) – file path

  • seek (timedelta, int or float) – position (in seconds) from which to get the thumbnail

  • fmt (str) – output image format (one of THUMBNAIL_FORMATS)

Returns

thumbnail data as a binary string in the specified format

Return type

bytes

Raises

  • ValueError – if image format is not supported

  • NoMediaError – if source doesn’t exist or is of unknown format

Example:

from avtk.backends.ffmpeg.shortcuts import get_thumbnail

png_data = get_thumbnail('test-media/video/sintel.mkv', timedelta(seconds=2))
with open('/tmp/thumb.png', 'wb') as fp:
    fp.write(png_data)
extract_audio(source, output, fmt=None, codec=None, channels=None)

Extracts audio from the source media file and saves it to a separate output file.

If codec is not specified, audio data will be copied directly from the input file, preserving quality. If the codec is specified, audio will be re-encoded. The transcode process is slower than pure copy and some quality loss is unavoidable.

Note that the codec parameter is actually an encoder name, and should be one of the supported encoders from get_available_encoders(). The somewhat-confusing codec name for the parameter is kept to be consistent with ffmpeg naming.

Parameters

  • source (str) – input file path or stream URL

  • output (str) – output file path

  • fmt (str) – output file format (optional, default: guess from output file name)

  • codec (str) – output file codec (optional, default: copy from input)

  • channels (int) – downmix to specified number of channels (optional)

Raises

NoMediaError – if source doesn’t exist or is of unknown format

Example:

from avtk.backends.ffmpeg.shortcuts import extract_audio

extract_audio('test-media/video/sintel.mkv', '/tmp/output.ogg', codec='libopus', channels=2)
remove_audio(source, output, fmt=None, remove_subtitles=True)

Creates an output video file from the source with all audio streams removed.

Parameters

  • source (str) – input file path or stream URL

  • output (str) – output file path

  • fmt (str) – output file format (optional, default: guess from output file name)

  • remove_subtitles (bool) – whether to remove subtitle streams as well (optional, default: True)

Raises

NoMediaError – if source doesn’t exist or is of unknown format

Example:

from avtk.backends.ffmpeg.shortcuts import remove_audio

remove_audio('test-media/video/sintel.mkv', '/tmp/silent.mkv')
convert_to_h264(source, output, preset=None, crf=None, video_bitrate=None, audio_bitrate=None, **kwargs)

Converts a video file to MP4 format using H264 for video and AAC for audio.

See https://trac.ffmpeg.org/wiki/Encode/H.264 for tips on H.264 encoding with ffmpeg, and for description of CRF and preset parameters.

Parameters

  • source (str) – input file path or stream URL

  • output (str) – output file path

  • preset (str) – encoder preset (quality / encoding speed tradeoff) - optional

  • crf (str) – constant rate factor (determines target quality) - optional

  • video_bitrate (int or str) – target video bitrate - optional

  • audio_bitrate (int or str) – target audio bitrate - optional

  • scale (tuple) – resize output to specified size (width, height) - optional

  • extra (list(str)) – additional ffmpeg command line arguments - optional

Raises

NoMediaError – if source doesn’t exist or is of unknown format

If scale is set, either width or height may be -1 to use the optimal size for preserving aspect ratio, or 0 to keep the original size.

Bitrates should be specified as integers or as strings in ‘NUMk’ or ‘NUMm’ format.

Example:

from avtk.backends.ffmpeg.shortcuts import convert_to_h264

convert_to_h264(
    'test-media/video/sintel.mkv',
    '/tmp/out.mkv',
    preset='fast',
    crf=23,
    video_bitrate='2m',
    audio_bitrate='128k'
)
convert_to_webm(source, output, crf=None, audio_bitrate=None, **kwrags)

Converts a video file to WebM format using VP9 for video and Opus for audio.

Uses a single-pass constant quality encode process for VP9. See https://trac.ffmpeg.org/wiki/Encode/VP9 for tips on VP9 encoding with ffmpeg, and for description of the CRF parameter.

Parameters

  • source (str) – input file path or stream URL

  • output (str) – output file path

  • crf (str) – constant rate factor (determines target quality) - optional, default is 31

  • audio_bitrate (int or str) – target audio bitrate - optional

  • scale (tuple) – resize output to specified size (width, height) - optional

  • extra (list(str)) – additional ffmpeg command line arguments - optional

Raises

NoMediaError – if source doesn’t exist or is of unknown format

If scale is set, either width or height may be -1 to use the optimal size for preserving aspect ratio, or 0 to keep the original size.

Audio bitrate should be specified as integer or as string in ‘NUMk’ format.

Example:

from avtk.backends.ffmpeg.shortcuts import convert_to_webm

convert_to_webm(
    'test-media/video/sintel.mkv',
    '/tmp/out.webm',
    crf=31,
    audio_bitrate='128k'
)
convert_to_hevc(source, output, preset=None, crf=None, video_bitrate=None, audio_bitrate=None, **kwargs)

Converts a video file to MP4 format using H.265 (HEVC) for video and AAC for audio.

Uses a single-pass constant quality encode process for HEVC. See https://trac.ffmpeg.org/wiki/Encode/H.265 for tips on HEVC encoding with ffmpeg, and for description of the CRF and preset parameters.

Parameters

  • source (str) – input file path or stream URL

  • output (str) – output file path

  • preset (str) – encoder preset (quality / encoding speed tradeoff) - optional

  • crf (str) – constant rate factor (determines target quality) - optional

  • audio_bitrate (int or str) – target audio bitrate - optional

  • scale (tuple) – resize output to specified size (width, height) - optional

  • extra (list(str)) – additional ffmpeg command line arguments - optional

Raises

NoMediaError – if source doesn’t exist or is of unknown format

If scale is set, either width or height may be -1 to use the optimal size for preserving aspect ratio, or 0 to keep the original size.

Bitrates should be specified as integers or as strings in ‘NUMk’ or ‘NUMm’ format.

Example:

from avtk.backends.ffmpeg.shortcuts import convert_to_hevc

convert_to_hevc(
    'test-media/video/sintel.mkv',
    '/tmp/out.mp4'
)
convert_to_aac(source, output, bit_rate=None, **kwargs)

Converts a media file to audio MP4 using AAC codec.

Parameters

  • source (str) – input file path or stream URL

  • output (str) – output file path

  • bit_rate (int or str) – target audio bitrate - optional

  • channels (int) – number of channels to downmix to - optional

Raises

NoMediaError – if source doesn’t exist or is of unknown format

Bit rate should be specified as integers or as strings in ‘NUMk’ or ‘NUMm’ format.

Example:

from avtk.backends.ffmpeg.shortcuts import convert_to_aac

convert_to_aac(
    'test-media/audio/stereo.mp3',
    '/tmp/out.aac',
    bit_rate='96k'
)
convert_to_opus(source, output, bit_rate=None, **kwargs)

Converts a media file to Opus-encoded Ogg file.

Parameters

  • source (str) – input file path or stream URL

  • output (str) – output file path

  • bit_rate (int or str) – target audio bitrate - optional

  • channels (int) – number of channels to downmix to - optional

Raises

NoMediaError – if source doesn’t exist or is of unknown format

Bit rate should be specified as integers or as strings in ‘NUMk’ or ‘NUMm’ format.

Example:

from avtk.backends.ffmpeg.shortcuts import convert_to_opus

convert_to_opus(
    'test-media/audio/stereo.mp3',
    '/tmp/out.ogg',
    bit_rate='96k'
)