Skip to content

Types

Note

You'll notice right away that there are absolutely no docstrings within these classes. The main reason for that was me being lazy. An additional, compounding factor is that many of these attributes actually lack any description even in the source material – the mkvmerge identification output schema v20, which this library's structure is based on.

Because of the direct mapping to that schema (and, well, the laziness), I haven't attempted to document them here. The attributes represent exactly what's defined (or not defined) in the mkvmerge documentation and that schema. Please refer to those resources for details.

MKVInfo

Bases: Base

Represents information about a matroska file as per the mkvmerge-identification-output-schema-v20.json.

The attributes represent exactly what's defined (or not defined) in the mkvmerge documentation and that schema. Please refer to those resources for details.

file_name instance-attribute 

file_name: str

container class-attribute instance-attribute 

container: Container = Container()

attachments class-attribute instance-attribute 

attachments: tuple[Attachment, ...] = ()

tracks class-attribute instance-attribute 

tracks: tuple[Track, ...] = ()

identification_format_version class-attribute instance-attribute 

identification_format_version: int | None = None

from_file classmethod 

from_file(
    file: StrPath, /, *, mkvmerge: StrPath | None = None
) -> Self

Create an instance of this class from a file.

This method uses mkvmerge in a subprocess to extract the information.

Parameters:

Name Type Description Default
file StrPath

Path to the file.

 required
mkvmerge StrPath | None

Optional path to the mkvmerge executable. If provided, this path will be used instead of searching the system's $PATH.

 None

Returns:

Type Description
Self

An instance of this class.

Raises:

Type Description
FileNotFoundError

If the provided file path does not exist or is not a valid file.
ExecutableNotFoundError

If the mkvmerge executable is not found.
MKVInfoError

For other errors that occur during the execution of the mkvmerge.
Source code in src/mkvinfo/_types.py 
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
@classmethod
def from_file(
    cls,
    file: StrPath,
    /,
    *,
    mkvmerge: StrPath | None = None,
) -> Self:  # pragma: no cover
    """
    Create an instance of this class from a file.

    This method uses [`mkvmerge`][0] in a subprocess
    to extract the information.

    [0]: https://mkvtoolnix.download/doc/mkvmerge.html

    Parameters
    ----------
    file : StrPath
        Path to the file.
    mkvmerge : StrPath | None, optional
        Optional path to the `mkvmerge` executable. If provided,
        this path will be used instead of searching the system's `$PATH`.

    Returns
    -------
    Self
        An instance of this class.

    Raises
    ------
    FileNotFoundError
        If the provided file path does not exist or is not a valid file.
    ExecutableNotFoundError
        If the `mkvmerge` executable is not found.
    MKVInfoError
        For other errors that occur during the execution of the `mkvmerge`.

    """
    file = Path(file)
    if not file.is_file():
        raise FileNotFoundError(file)

    if mkvmerge is not None:
        mkvmerge = Path(mkvmerge)
        if not mkvmerge.is_file():
            msg = (
                f"Provided mkvmerge path '{mkvmerge}' "
                "does not exist or is not a valid file."
            )
            raise ExecutableNotFoundError(msg)

    data = mkvmerge_run(file, exe=mkvmerge)
    return cls.from_json(data)

Attachment

Bases: Base

Represents an attachment in a matroska file.

file_name instance-attribute 

file_name: str

id instance-attribute 

id: int

size instance-attribute 

size: int

content_type class-attribute instance-attribute 

content_type: str | None = None

description class-attribute instance-attribute 

description: str | None = None

Container

Bases: Base

Represents the container.

recognized class-attribute instance-attribute 

recognized: bool = False

supported class-attribute instance-attribute 

supported: bool = False

properties class-attribute instance-attribute 

properties: ContainerProperties = ContainerProperties()

type class-attribute instance-attribute 

type: str | None = None

ContainerProperties

Bases: Base

Represents the properties of the container.

container_type class-attribute instance-attribute 

container_type: int | None = None

date_local class-attribute instance-attribute 

date_local: datetime | None = None

date_utc class-attribute instance-attribute 

date_utc: datetime | None = None

duration class-attribute instance-attribute 

duration: int | None = None

is_providing_timestamps class-attribute instance-attribute 

is_providing_timestamps: bool | None = None

muxing_application class-attribute instance-attribute 

muxing_application: str | None = None

timestamp_scale class-attribute instance-attribute 

timestamp_scale: int | None = None

title class-attribute instance-attribute 

title: str | None = None

writing_application class-attribute instance-attribute 

writing_application: str | None = None

Track

Bases: Base

Represents a track in a matroska file.

codec instance-attribute 

codec: str

id instance-attribute 

id: int

type instance-attribute 

type: TrackType

properties class-attribute instance-attribute 

properties: TrackProperties = TrackProperties()

TrackProperties

Bases: Base

Represents the properties of a track.

alpha_mode class-attribute instance-attribute 

alpha_mode: int | None = None

audio_bits_per_sample class-attribute instance-attribute 

audio_bits_per_sample: int | None = None

audio_channels class-attribute instance-attribute 

audio_channels: int | None = None

audio_emphasis class-attribute instance-attribute 

audio_emphasis: int | None = None

audio_sampling_frequency class-attribute instance-attribute 

audio_sampling_frequency: int | None = None

cb_subsample class-attribute instance-attribute 

cb_subsample: str | None = None

chroma_siting class-attribute instance-attribute 

chroma_siting: str | None = None

chroma_subsample class-attribute instance-attribute 

chroma_subsample: str | None = None

chromaticity_coordinates class-attribute instance-attribute 

chromaticity_coordinates: str | None = None

codec_delay class-attribute instance-attribute 

codec_delay: int | None = None

codec_id class-attribute instance-attribute 

codec_id: str | None = None

codec_name class-attribute instance-attribute 

codec_name: str | None = None

content_encoding_algorithms class-attribute instance-attribute 

content_encoding_algorithms: str | None = None

color_bits_per_channel class-attribute instance-attribute 

color_bits_per_channel: int | None = None

color_matrix_coefficients class-attribute instance-attribute 

color_matrix_coefficients: int | None = None

color_primaries class-attribute instance-attribute 

color_primaries: int | None = None

color_range class-attribute instance-attribute 

color_range: int | None = None

color_transfer_characteristics class-attribute instance-attribute 

color_transfer_characteristics: int | None = None

default_duration class-attribute instance-attribute 

default_duration: int | None = None

default_track class-attribute instance-attribute 

default_track: bool | None = None

display_dimensions class-attribute instance-attribute 

display_dimensions: str | None = None

display_unit class-attribute instance-attribute 

display_unit: int | None = None

enabled_track class-attribute instance-attribute 

enabled_track: bool | None = None

encoding class-attribute instance-attribute 

encoding: str | None = None

forced_track class-attribute instance-attribute 

forced_track: bool | None = None

flag_hearing_impaired class-attribute instance-attribute 

flag_hearing_impaired: bool | None = None

flag_visual_impaired class-attribute instance-attribute 

flag_visual_impaired: bool | None = None

flag_text_descriptions class-attribute instance-attribute 

flag_text_descriptions: bool | None = None

flag_original class-attribute instance-attribute 

flag_original: bool | None = None

flag_commentary class-attribute instance-attribute 

flag_commentary: bool | None = None

language class-attribute instance-attribute 

language: str | None = None

language_ietf class-attribute instance-attribute 

language_ietf: str | None = None

max_content_light class-attribute instance-attribute 

max_content_light: int | None = None

max_frame_light class-attribute instance-attribute 

max_frame_light: int | None = None

max_luminance class-attribute instance-attribute 

max_luminance: float | None = None

min_luminance class-attribute instance-attribute 

min_luminance: float | None = None

minimum_timestamp class-attribute instance-attribute 

minimum_timestamp: int | None = None

multiplexed_tracks class-attribute instance-attribute 

multiplexed_tracks: tuple[int, ...] | None = None

number class-attribute instance-attribute 

number: int | None = None

num_index_entries class-attribute instance-attribute 

num_index_entries: int | None = None

packetizer class-attribute instance-attribute 

packetizer: str | None = None

pixel_dimensions class-attribute instance-attribute 

pixel_dimensions: str | None = None

program_number class-attribute instance-attribute 

program_number: int | None = None

projection_pose_pitch class-attribute instance-attribute 

projection_pose_pitch: float | None = None

projection_pose_roll class-attribute instance-attribute 

projection_pose_roll: float | None = None

projection_pose_yaw class-attribute instance-attribute 

projection_pose_yaw: float | None = None

projection_private class-attribute instance-attribute 

projection_private: str | None = None

projection_type class-attribute instance-attribute 

projection_type: int | None = None

stereo_mode class-attribute instance-attribute 

stereo_mode: int | None = None

stream_id class-attribute instance-attribute 

stream_id: int | None = None

sub_stream_id class-attribute instance-attribute 

sub_stream_id: int | None = None

teletext_page class-attribute instance-attribute 

teletext_page: int | None = None

text_subtitles class-attribute instance-attribute 

text_subtitles: bool | None = None

track_name class-attribute instance-attribute 

track_name: str | None = None

uid class-attribute instance-attribute 

uid: int | None = None

white_color_coordinates class-attribute instance-attribute 

white_color_coordinates: str | None = None

TrackType

Bases: StrEnum

Represents the type of a track.

VIDEO class-attribute instance-attribute 

VIDEO = 'video'

AUDIO class-attribute instance-attribute 

AUDIO = 'audio'

SUBTITLES class-attribute instance-attribute 

SUBTITLES = 'subtitles'

Base

Bases: Struct

Base class for mkvmerge data structures.

from_dict classmethod 

from_dict(data: dict[str, Any]) -> Self

Create an instance of this class from a dictionary.

Parameters:

Name Type Description Default
data dict[str, Any]

Dictionary representing the instance of this class.

 required

Returns:

Type Description
Self

An instance of this class.
Source code in src/mkvinfo/_types.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
@classmethod
def from_dict(cls, data: dict[str, Any], /) -> Self:
    """
    Create an instance of this class from a dictionary.

    Parameters
    ----------
    data : dict[str, Any]
        Dictionary representing the instance of this class.

    Returns
    -------
    Self
        An instance of this class.

    """
    return msgspec.convert(data, type=cls)

to_dict 

to_dict() -> dict[str, Any]

Serialize the instance of this class into a dictionary.

Returns:

Type Description
dict[str, Any]

Dictionary representing the instance of this class.
Source code in src/mkvinfo/_types.py 
57
58
59
60
61
62
63
64
65
66
67
def to_dict(self) -> dict[str, Any]:
    """
    Serialize the instance of this class into a dictionary.

    Returns
    -------
    dict[str, Any]
        Dictionary representing the instance of this class.

    """
    return msgspec.to_builtins(self)  # type: ignore[no-any-return]

from_json classmethod 

from_json(data: str | bytes) -> Self

Create an instance of this class from JSON data.

Parameters:

Name Type Description Default
data str | bytes

JSON data representing the instance of this class.

 required

Returns:

Type Description
Self

An instance of this class.
Source code in src/mkvinfo/_types.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
@classmethod
def from_json(cls, data: str | bytes, /) -> Self:
    """
    Create an instance of this class from JSON data.

    Parameters
    ----------
    data : str | bytes
        JSON data representing the instance of this class.

    Returns
    -------
    Self
        An instance of this class.

    """
    return msgspec.json.decode(data, type=cls)

to_json 

to_json(*, indent: int = 2) -> str

Serialize the instance of this class into a JSON string.

Parameters:

Name Type Description Default
indent int

Number of spaces for indentation. Set to 0 for a single line with spacing, or negative to minimize size by removing extra whitespace.

 2

Returns:

Type Description
str

JSON string representing this class.
Source code in src/mkvinfo/_types.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def to_json(self, *, indent: int = 2) -> str:
    """
    Serialize the instance of this class into a JSON string.

    Parameters
    ----------
    indent : int, optional
        Number of spaces for indentation.
        Set to 0 for a single line with spacing,
        or negative to minimize size by removing extra whitespace.

    Returns
    -------
    str
        JSON string representing this class.

    """
    jsonified = msgspec.json.encode(self)
    return msgspec.json.format(jsonified, indent=indent).decode()