Tools

ffpyplayer.tools

FFmpeg tools

Module for manipulating and finding information of FFmpeg formats, codecs, devices, pixel formats and more.

ffpyplayer.tools.initialize_sdl_aud()

Initializes sdl audio subsystem. Must be called before audio can be used. It is automatically called by the modules that use SDL audio.

ffpyplayer.tools.set_log_callback(callback=None, logger=None, int default_only=False)

Sets a callback to be used by ffmpeg when emitting logs. This function is thread safe.

See also set_loglevel().

Parameters
callback: callable or None

A function which will be called with strings to be printed. It takes two parameters: message and level. message is the string to be printed. level is the log level of the string and is one of the keys of the loglevels dict. If callback and logger are None, the default ffmpeg log callback will be set, which prints to stderr. Defaults to None.

logger: a python logger object or None

If callback is None and this is not None, this logger object’s critical, error, warning, info, debug, and trace methods will be called directly to forward ffmpeg’s log outputs.

Note

If the logger doesn’t have a trace method, the trace output will be redirected to debug. However, the trace level outputs a lot of logs.

default_only: bool

If True, when callback or logger are not None, they will only be set if a callback or logger has not already been set.

Returns

The previous callback set (None, if it has not been set).

>>> from ffpyplayer.tools import set_log_callback, loglevels
>>> loglevel_emit = 'error' # This and worse errors will be emitted.
>>> def log_callback(message, level):
...     message = message.strip()
...     if message and loglevels[level] <= loglevels[loglevel_emit]:
...         print '%s: %s' %(level, message.strip())
>>> set_log_callback(log_callback)
...
>>> set_log_callback(None)
ffpyplayer.tools.get_log_callback()

Returns the last log callback set, or None if it has not been set. See set_log_callback().

ffpyplayer.tools.set_loglevel(loglevel)

This sets the global FFmpeg log level. less important log levels are filtered and not passsed on to the logger or callback set by set_log_callback(). It also set the loglevel of FFmpeg if not callback or logger is set.

The global log level, if not set, defaults to 'warning'.

Parameters
loglevel: str

The log level. Can be one of the keys of loglevels.

ffpyplayer.tools.get_loglevel()

Returns the log level set with set_loglevel(), or the default level if not set. It is one of the keys of loglevels.

ffpyplayer.tools.get_codecs(int encode=False, int decode=False, int video=False, int audio=False, int data=False, int subtitle=False, int attachment=False, other=False)

Returns a list of codecs (e.g. h264) that is available by ffpyplayer for encoding or decoding and matches the media types, e.g. video or audio.

The parameters determine which codecs is included in the result. The parameters all default to False.

Parameters
encode: bool

If True, includes the encoding codecs in the result. Defaults to False.

decode: bool

If True, includes the decoding codecs in the result. Defaults to False.

video: bool

If True, includes the video codecs in the result. Defaults to False.

audio: bool

If True, includes the audio codecs in the result. Defaults to False.

data: bool

If True, includes the (continuous) side data codecs in the result. Defaults to False.

subtitle: bool

If True, includes the subtitle codecs in the result. Defaults to False.

attachment: bool

If True, includes the (sparse) data attachment codecs in the result. Defaults to False.

other: bool

If True, returns all the codec media types.

Returns

A sorted list of the matching codec names.

ffpyplayer.tools.get_fmts(int input=False, int output=False)

Returns the formats available in FFmpeg.

Parameters
input: bool

If True, also includes input formats in the result. Defaults to False

output: bool

If True, also includes output formats in the result. Defaults to False

Returns

A 3-tuple of 3 lists, formats, full_names, and extensions. Each of the three lists are of identical length.

formats: list

A list of the names of the formats.

full_names: list

A list of the corresponding human readable names for each of the formats. Can be the empty string if none is available.

extensions: list

A list of the extensions associated with the corresponding formats. Each item is a (possibly empty) list of extensions names.

ffpyplayer.tools.get_format_codec(filename=None, fmt=None)

Returns the best codec associated with the file format. The format can be provided using either filename or fmt.

Parameters
filename: str or None

The output filename. If provided, the extension of the filename is used to guess the format.

fmt: str or None.

The format to use. Can be one of ffpyplayer.tools.formats_out.

Returns

str:

The name from ffpyplayer.tools.codecs_enc of the best codec that can be used with this format.

For example:

>>> get_format_codecs('test.png')
'mjpeg'
>>> get_format_codecs('test.jpg')
'mjpeg'
>>> get_format_codecs('test.mkv')
'libx264'
>>> get_format_codecs(fmt='h264')
'libx264'
ffpyplayer.tools.get_supported_framerates(codec_name, rate=())

Returns the supported frame rates for encoding codecs. If a desired rate is provided, it also returns the closest valid rate.

Parameters
codec_name: str

The name of a encoding codec.

rate: 2-tuple of ints, or empty tuple.

If provided, a 2-tuple where the first element is the numerator, and the second the denominator of the frame rate we wish to use. E.g. (2997, 100) means a frame rate of 29.97.

Returns

(list of 2-tuples, or empty list):

If there are no restrictions on the frame rate (i.e. all rates are valid) it returns a empty list, otherwise it returns a list with the valid frame rates. If rate is provided and there are restrictions on the frame rates, the closest frame rate is the zero’th element in the list.

For example:

>>> print get_supported_framerates('mpeg1video')
[(24000, 1001), (24, 1), (25, 1), (30000, 1001), (30, 1), (50, 1),
(60000, 1001), (60, 1), (15, 1), (5, 1), (10, 1), (12, 1), (15, 1)]

>>> print get_supported_framerates('mpeg1video', (2997, 100))
[(30000, 1001), (24000, 1001), (24, 1), (25, 1), (30, 1), (50, 1),
(60000, 1001), (60, 1), (15, 1), (5, 1), (10, 1), (12, 1), (15, 1)]
ffpyplayer.tools.get_supported_pixfmts(codec_name, pix_fmt=u'')

Returns the supported pixel formats for encoding codecs. If a desired format is provided, it also returns the closest format (i.e. the format with minimum conversion loss).

Parameters
codec_name: str

The name of a encoding codec.

pix_fmt: str

If not empty, the name of a pixel format we wish to use with this codec, e.g. ‘rgb24’.

Returns

(list of pixel formats, or empty list):

If there are no restrictions on the pixel formats (i.e. all the formats are valid) it returns a empty list, otherwise it returns a list with the valid formats. If pix_fmt is not empty and there are restrictions to the formats, the closest format which results in the minimum loss when converting will be returned as the zero’th element in the list.

For example:

>>> print get_supported_pixfmts('ffv1')
['yuv420p', 'yuva420p', 'yuva422p', 'yuv444p', 'yuva444p', 'yuv440p', ...
'gray16le', 'gray', 'gbrp9le', 'gbrp10le', 'gbrp12le', 'gbrp14le']

>>> print get_supported_pixfmts('ffv1', 'gray')
['gray', 'yuv420p', 'yuva420p', 'yuva422p', 'yuv444p', 'yuva444p', ...
'gray16le', 'gbrp9le', 'gbrp10le', 'gbrp12le', 'gbrp14le']
ffpyplayer.tools.get_best_pix_fmt(pix_fmt, pix_fmts)

Returns the best pixel format with the least conversion loss from the original pixel format, given a list of potential pixel formats.

Parameters
pix_fmt: str

The name of a original pixel format.

pix_fmts: list-type of strings

A list of possible pixel formats from which the best will be chosen.

Returns

The pixel format with the least conversion loss.

Note

The returned pixel format seems to be somewhat sensitive to the order of the input pixel formats. Higher quality pixel formats should therefore be at the beginning of the list.

For example:

>>> get_best_pix_fmt('yuv420p', ['rgb24', 'rgba', 'yuv444p', 'gray'])
'rgb24'
>>> get_best_pix_fmt('gray', ['rgb24', 'rgba', 'yuv444p', 'gray'])
'gray'
>>> get_best_pix_fmt('rgb8', ['rgb24', 'yuv420p', 'rgba', 'yuv444p', 'gray'])
'rgb24'
ffpyplayer.tools.emit_library_info()

Prints to the ffmpeg log all the ffmpeg library’s versions and configure options.

ffpyplayer.tools.list_dshow_devices()

Returns a list of the dshow devices available.

Returns

3-tuple: A 3-tuple, of (video, audio, names)

video: dict

A dict of all the direct show video devices. The keys of the dict are the unique names of the available direct show devices. The values are a list of the available configurations for that device. Each element in the list has the following format: (pix_fmt, codec_fmt, (frame_width, frame_height), (min_framerate, max_framerate))

audio: dict

A dict of all the direct show audio devices. The keys of the dict are the unique names of the available direct show devices. The values are a list of the available configurations for that device. Each element in the list has the following format: ((min_num_channels, min_num_channels), (min_bits, max_bits), (min_rate, max_rate)).

names: dict

A dict mapping the unique names of the video and audio devices to a more human friendly (possibly non-unique) name. Either of these names can be used when opening the device. However, if using the non-unique name, it’s not guarenteed which of the devices sharing the name will be opened.

For example:

>>> from ffpyplayer.player import MediaPlayer
>>> from ffpyplayer.tools import list_dshow_devices
>>> import time, weakref
>>> dev = list_dshow_devices()
>>> print dev
({'@device_pnp_...223196\global': [('bgr24', '', (160, 120), (5, 30)),
('bgr24', '', (176, 144), (5, 30)), ('bgr24', '', (320, 176), (5, 30)),
('bgr24', '', (320, 240), (5, 30)), ('bgr24', '', (352, 288), (5, 30)),
...
('yuv420p', '', (320, 240), (5, 30)), ('yuv420p', '', (352, 288), (5, 30))],
'@device_pnp_...223196\global': [('bgr24', '', (160, 120), (30, 30)),
...
('yuyv422', '', (352, 288), (30, 30)),
('yuyv422', '', (640, 480), (30, 30))]},
{'@device_cm_...2- HD Webcam C615)': [((1, 2), (8, 16), (11025, 44100))],
'@device_cm_...HD Webcam C615)': [((1, 2), (8, 16), (11025, 44100))]},
{'@device_cm_...- HD Webcam C615)': 'Microphone (2- HD Webcam C615)',
 '@device_cm_...2- HD Webcam C615)': 'Microphone (3- HD Webcam C615)',
...
 '@device_pnp...223196\global': 'HD Webcam C615',
 '@device_pnp...223196\global': 'Laptop Integrated Webcam'})

See Playing a webcam with DirectShow on windows for a full example.

ffpyplayer.tools.encode_to_bytes(item)

Takes the item and walks it recursively whether it’s a string, int, iterable, etc. and encodes all the strings to utf-8.

Parameters
item: anything

The object to be walked and encoded.

Returns

An object identical to the item, but with all strings encoded to utf-8.

ffpyplayer.tools.decode_to_unicode(item)

Takes the item and walks it recursively whether it’s a string, int, iterable, etc. and encodes all the strings to utf-8.

Parameters
item: anything

The object to be walked and encoded.

Returns

An object identical to the item, but with all strings encoded to utf-8.

ffpyplayer.tools.convert_to_str(item)

Takes the item and walks it recursively whether it’s a string, int, iterable, etc. and encodes all the strings to utf-8.

Parameters
item: anything

The object to be walked and encoded.

Returns

An object identical to the item, but with all strings encoded to utf-8.

tools.loglevels = {'debug': 48, 'error': 16, 'fatal': 8, 'info': 32, 'panic': 0, 'quiet': -8, 'trace': 56, 'verbose': 40, 'warning': 24}

A dictionary with all the available ffmpeg log levels. The keys are the loglevels and the values are their ffmpeg values. The lower the value, the more important the log. Note, this is ooposite python where the higher the level the more important the log.

tools.codecs_enc = []

A list of all the codecs available for encoding video.

tools.codecs_dec = []

A list of all the codecs available for decoding video and audio.

tools.pix_fmts = ['0bgr', '0rgb', 'abgr', 'argb', 'ayuv64be', 'ayuv64le', 'bayer_bggr16be', 'bayer_bggr16le', 'bayer_bggr8', 'bayer_gbrg16be', 'bayer_gbrg16le', 'bayer_gbrg8', 'bayer_grbg16be', 'bayer_grbg16le', 'bayer_grbg8', 'bayer_rggb16be', 'bayer_rggb16le', 'bayer_rggb8', 'bgr0', 'bgr24', 'bgr4', 'bgr444be', 'bgr444le', 'bgr48be', 'bgr48le', 'bgr4_byte', 'bgr555be', 'bgr555le', 'bgr565be', 'bgr565le', 'bgr8', 'bgra', 'bgra64be', 'bgra64le', 'cuda', 'd3d11', 'd3d11va_vld', 'drm_prime', 'dxva2_vld', 'gbrap', 'gbrap10be', 'gbrap10le', 'gbrap12be', 'gbrap12le', 'gbrap16be', 'gbrap16le', 'gbrapf32be', 'gbrapf32le', 'gbrp', 'gbrp10be', 'gbrp10le', 'gbrp12be', 'gbrp12le', 'gbrp14be', 'gbrp14le', 'gbrp16be', 'gbrp16le', 'gbrp9be', 'gbrp9le', 'gbrpf32be', 'gbrpf32le', 'gray', 'gray10be', 'gray10le', 'gray12be', 'gray12le', 'gray16be', 'gray16le', 'gray9be', 'gray9le', 'mediacodec', 'mmal', 'monob', 'monow', 'nv12', 'nv16', 'nv20be', 'nv20le', 'nv21', 'p010be', 'p010le', 'p016be', 'p016le', 'pal8', 'qsv', 'rgb0', 'rgb24', 'rgb4', 'rgb444be', 'rgb444le', 'rgb48be', 'rgb48le', 'rgb4_byte', 'rgb555be', 'rgb555le', 'rgb565be', 'rgb565le', 'rgb8', 'rgba', 'rgba64be', 'rgba64le', 'uyvy422', 'uyyvyy411', 'vaapi_idct', 'vaapi_moco', 'vaapi_vld', 'vda', 'vda_vld', 'vdpau', 'vdpau_h264', 'vdpau_mpeg1', 'vdpau_mpeg2', 'vdpau_mpeg4', 'vdpau_vc1', 'vdpau_wmv3', 'videotoolbox_vld', 'xvmcidct', 'xvmcmc', 'xyz12be', 'xyz12le', 'ya16be', 'ya16le', 'ya8', 'yuv410p', 'yuv411p', 'yuv420p', 'yuv420p10be', 'yuv420p10le', 'yuv420p12be', 'yuv420p12le', 'yuv420p14be', 'yuv420p14le', 'yuv420p16be', 'yuv420p16le', 'yuv420p9be', 'yuv420p9le', 'yuv422p', 'yuv422p10be', 'yuv422p10le', 'yuv422p12be', 'yuv422p12le', 'yuv422p14be', 'yuv422p14le', 'yuv422p16be', 'yuv422p16le', 'yuv422p9be', 'yuv422p9le', 'yuv440p', 'yuv440p10be', 'yuv440p10le', 'yuv440p12be', 'yuv440p12le', 'yuv444p', 'yuv444p10be', 'yuv444p10le', 'yuv444p12be', 'yuv444p12le', 'yuv444p14be', 'yuv444p14le', 'yuv444p16be', 'yuv444p16le', 'yuv444p9be', 'yuv444p9le', 'yuva420p', 'yuva420p10be', 'yuva420p10le', 'yuva420p16be', 'yuva420p16le', 'yuva420p9be', 'yuva420p9le', 'yuva422p', 'yuva422p10be', 'yuva422p10le', 'yuva422p16be', 'yuva422p16le', 'yuva422p9be', 'yuva422p9le', 'yuva444p', 'yuva444p10be', 'yuva444p10le', 'yuva444p16be', 'yuva444p16le', 'yuva444p9be', 'yuva444p9le', 'yuvj411p', 'yuvj420p', 'yuvj422p', 'yuvj440p', 'yuvj444p', 'yuyv422', 'yvyu422']

A list of all the pixel formats available to ffmpeg.

tools.formats_in = ['alsa', 'fbdev', 'iec61883', 'jack', 'kmsgrab', 'lavfi', 'libcdio', 'libdc1394', 'openal', 'oss', 'pulse', 'sndio', 'v4l2', 'video4linux2', 'x11grab']

A list of all the formats (e.g. file formats) available for reading.

tools.formats_out = ['alsa', 'caca', 'fbdev', 'opengl', 'oss', 'pulse', 'sdl', 'sdl2', 'sndio', 'v4l2', 'xv']

A list of all the formats (e.g. file formats) available for writing.