API reference

This module is a wrapper for the MediaInfo library.

class pymediainfo.MediaInfo(xml, encoding_errors='strict')

An object containing information about a media file.

MediaInfo objects can be created by directly calling code from libmediainfo (in this case, the library must be present on the system):

>>> pymediainfo.MediaInfo.parse("/path/to/file.mp4")

Alternatively, objects may be created from MediaInfo’s XML output. Such output can be obtained using the XML output format on versions older than v17.10 and the OLDXML format on newer versions.

Using such an XML file, we can create a MediaInfo object:

>>> with open("output.xml") as f:
...     mi = pymediainfo.MediaInfo(f.read())
Parameters:

  • xml (str) – XML output obtained from MediaInfo.

  • encoding_errors (str) – option to pass to str.encode()’s errors parameter before parsing xml.

Raises:

xml.etree.ElementTree.ParseError – if passed invalid XML.

Variables:

tracks –

A list of Track objects which the media file contains. For instance:

>>> mi = pymediainfo.MediaInfo.parse("/path/to/file.mp4")
>>> for t in mi.tracks:
...     print(t)
<Track track_id='None', track_type='General'>
<Track track_id='1', track_type='Text'>

property audio_tracks
Returns:

All Tracks of type Audio.

Return type:

list of Tracks

classmethod can_parse(library_file=None)

Checks whether media files can be analyzed using libmediainfo.

Parameters:

library_file (str) – path to the libmediainfo library, this should only be used if the library cannot be auto-detected. See also Library autodetection which explains how the library file is detected when this parameter is unset.

Return type:

bool

property general_tracks
Returns:

All Tracks of type General.

Return type:

list of Tracks

property image_tracks
Returns:

All Tracks of type Image.

Return type:

list of Tracks

property menu_tracks
Returns:

All Tracks of type Menu.

Return type:

list of Tracks

property other_tracks
Returns:

All Tracks of type Other.

Return type:

list of Tracks

classmethod parse(filename, *, library_file=None, cover_data=False, encoding_errors='strict', parse_speed=0.5, full=True, legacy_stream_display=False, mediainfo_options=None, output=None, buffer_size=65536)

Analyze a media file using libmediainfo.

Note

Because of the way the underlying library works, this method should not be called simultaneously from multiple threads with different parameters. Doing so will cause inconsistencies or failures by changing library options that are shared across threads.

Parameters:

  • filename (str or pathlib.Path or os.PathLike or file-like object.) – path to the media file or file-like object which will be analyzed. A URL can also be used if libmediainfo was compiled with CURL support.

  • library_file (str) – path to the libmediainfo library, this should only be used if the library cannot be auto-detected. See also Library autodetection which explains how the library file is detected when this parameter is unset.

  • cover_data (bool) – whether to retrieve cover data as base64.

  • encoding_errors (str) – option to pass to str.encode()’s errors parameter before parsing MediaInfo’s XML output.

  • parse_speed (float) – passed to the library as ParseSpeed, this option takes values between 0 and 1. A higher value will yield more precise results in some cases but will also increase parsing time.

  • full (bool) – display additional tags, including computer-readable values for sizes and durations, corresponds to the CLI’s --Full/-f parameter.

  • legacy_stream_display (bool) – display additional information about streams.

  • mediainfo_options (dict) – additional options that will be passed to the MediaInfo_Option function, for example: {"Language": "raw"}. Do not use this parameter when running the method simultaneously from multiple threads, it will trigger a reset of all options which will cause inconsistencies or failures.

  • output (str) –

    custom output format for MediaInfo, corresponds to the CLI’s --Output parameter. Setting this causes the method to return a str instead of a MediaInfo object.

    Useful values include:

    • the empty str "" (corresponds to the default text output, obtained when running mediainfo with no additional parameters)

    • "XML"

    • "JSON"

    • %-delimited templates (see mediainfo --Info-Parameters)

  • buffer_size (int) – size of the buffer used to read the file, in bytes. This is only used when filename is a file-like object.

Return type:

str if output is set.

Return type:

MediaInfo otherwise.

Raises:

  • FileNotFoundError – if passed a non-existent file.

  • ValueError – if passed a file-like object opened in text mode.

  • OSError – if the library file could not be loaded.

  • RuntimeError – if parsing fails, this should not happen unless libmediainfo itself fails.

Examples:
>>> pymediainfo.MediaInfo.parse("tests/data/sample.mkv")
    <pymediainfo.MediaInfo object at 0x7fa83a3db240>

>>> import json
>>> mi = pymediainfo.MediaInfo.parse("tests/data/sample.mkv",
...     output="JSON")
>>> json.loads(mi)["media"]["track"][0]
    {'@type': 'General', 'TextCount': '1', 'FileExtension': 'mkv',
        'FileSize': '5904',  … }
property text_tracks
Returns:

All Tracks of type Text.

Return type:

list of Tracks

to_data()

Returns a dict representation of the object’s Tracks.

Return type:

dict

to_json()

Returns a JSON representation of the object’s Tracks.

Return type:

str

property video_tracks
Returns:

All Tracks of type Video.

Return type:

list of Tracks

class pymediainfo.Track(xml_dom_fragment)

An object associated with a media file track.

Each Track attribute corresponds to attributes parsed from MediaInfo’s output. All attributes are lower case. Attributes that are present several times such as Duration yield a second attribute starting with other_ which is a list of all alternative attribute values.

When a non-existing attribute is accessed, None is returned.

Example:

>>> t = mi.tracks[0]
>>> t
<Track track_id='None', track_type='General'>
>>> t.duration
3000
>>> t.other_duration
['3 s 0 ms', '3 s 0 ms', '3 s 0 ms',
    '00:00:03.000', '00:00:03.000']
>>> type(t.non_existing)
NoneType

All available attributes can be obtained by calling to_data().

to_data()

Returns a dict representation of the track attributes.

Example:

>>> sorted(track.to_data().keys())[:3]
['codec', 'codec_extensions_usually_used', 'codec_url']
>>> t.to_data()["file_size"]
5988
Return type:

dict

Library autodetection

Whenever a method is called with library_file=None (the default), the following logic is used.

Filename Determination

First, the library filename is automatically determined based on the operating system:

  • On Linux, libmediainfo.so.0 is used.

  • On macOS, the first available file among libmediainfo.0.dylib and libmediainfo.dylib is used, in that order.

  • On Windows, MediaInfo.dll is used.

Paths Searched

Next, the code checks if a matching library file exists in the same directory as pymediainfo’s __init__.py and attempts to load it. If pymediainfo was installed from a wheel, the bundled library is placed in this location.

Last, if no matching file could be loaded from the previous location, the code attempts to load the previously determined filename(s) from standard system paths, using ctypes.CDLL for Linux and macOS, or ctypes.WinDLL for Windows.