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 dataclass 

MKVInfo(
    *,
    file_name: str,
    container: Container = Container(),
    attachments: tuple[Attachment, ...] = (),
    tracks: tuple[Track, ...] = (),
    identification_format_version: int | None = None,
)

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 = field(default_factory=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_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 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
@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.

    """
    validator = TypeAdapter(cls)
    return validator.validate_json(data)

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 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
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
@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 dataclass 

Attachment(
    *,
    file_name: str,
    id: int,
    size: int,
    content_type: str | None = None,
    description: str | None = None,
)

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 dataclass 

Container(
    *,
    recognized: bool = False,
    supported: bool = False,
    properties: ContainerProperties = ContainerProperties(),
    type: str | None = None,
)

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 = field(
    default_factory=ContainerProperties
)

type class-attribute instance-attribute 

type: str | None = None

ContainerProperties dataclass 

ContainerProperties(
    *,
    container_type: int | None = None,
    date_local: datetime | None = None,
    date_utc: datetime | None = None,
    duration: int | None = None,
    is_providing_timestamps: bool | None = None,
    muxing_application: str | None = None,
    timestamp_scale: int | None = None,
    title: str | None = None,
    writing_application: str | None = None,
)

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 dataclass 

Track(
    *,
    codec: str,
    id: int,
    type: TrackType,
    properties: TrackProperties = TrackProperties(),
)

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 = field(
    default_factory=TrackProperties
)

TrackProperties dataclass 

TrackProperties(
    *,
    alpha_mode: int | None = None,
    audio_bits_per_sample: int | None = None,
    audio_channels: int | None = None,
    audio_emphasis: int | None = None,
    audio_sampling_frequency: int | None = None,
    cb_subsample: str | None = None,
    chroma_siting: str | None = None,
    chroma_subsample: str | None = None,
    chromaticity_coordinates: str | None = None,
    codec_delay: int | None = None,
    codec_id: str | None = None,
    codec_name: str | None = None,
    content_encoding_algorithms: str | None = None,
    color_bits_per_channel: int | None = None,
    color_matrix_coefficients: int | None = None,
    color_primaries: int | None = None,
    color_range: int | None = None,
    color_transfer_characteristics: int | None = None,
    default_duration: int | None = None,
    default_track: bool | None = None,
    display_dimensions: str | None = None,
    display_unit: int | None = None,
    enabled_track: bool | None = None,
    encoding: str | None = None,
    forced_track: bool | None = None,
    flag_hearing_impaired: bool | None = None,
    flag_visual_impaired: bool | None = None,
    flag_text_descriptions: bool | None = None,
    flag_original: bool | None = None,
    flag_commentary: bool | None = None,
    language: str | None = None,
    language_ietf: str | None = None,
    max_content_light: int | None = None,
    max_frame_light: int | None = None,
    max_luminance: float | None = None,
    min_luminance: float | None = None,
    minimum_timestamp: int | None = None,
    multiplexed_tracks: tuple[int, ...] | None = None,
    number: int | None = None,
    num_index_entries: int | None = None,
    packetizer: str | None = None,
    pixel_dimensions: str | None = None,
    program_number: int | None = None,
    projection_pose_pitch: float | None = None,
    projection_pose_roll: float | None = None,
    projection_pose_yaw: float | None = None,
    projection_private: str | None = None,
    projection_type: int | None = None,
    stereo_mode: int | None = None,
    stream_id: int | None = None,
    sub_stream_id: int | None = None,
    teletext_page: int | None = None,
    text_subtitles: bool | None = None,
    track_name: str | None = None,
    uid: int | None = None,
    white_color_coordinates: str | None = None,
)

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'

is_video 

is_video() -> bool

Check if this instance is a video track.

Source code in src/mkvinfo/_types.py 
151
152
153
def is_video(self) -> bool:
    """Check if this instance is a video track."""
    return self is TrackType.VIDEO

is_audio 

is_audio() -> bool

Check if this instance is an audio track.

Source code in src/mkvinfo/_types.py 
155
156
157
def is_audio(self) -> bool:
    """Check if this instance is an audio track."""
    return self is TrackType.AUDIO

is_subtitles 

is_subtitles() -> bool

Check if this instance is a subtitles track.

Source code in src/mkvinfo/_types.py 
159
160
161
def is_subtitles(self) -> bool:
    """Check if this instance is a subtitles track."""
    return self is TrackType.SUBTITLES