MKVFile¶

MKVFile is the core class of pymkv. It is used to import, create, modify, and mux MKV files.

Examples

Below are some basic examples of how the MKVFile objects can be used.

Create and mux a new MKV. This example takes an standalone video and audio track and combines them into an MKV file.

>>> from pymkv import MKVFile
>>> mkv = MKVFile()
>>> mkv.add_track('/path/to/track.h264')
>>> mkv.add_track(MKVTrack('/path/to/another/track.aac'))
>>> mkv.mux('/path/to/output.mkv')

Generate the mkvmerge command to mux an MKV. This is example is identical to the first example except the command is only generated, not executed.

>>> mkv = MKVFile()
>>> mkv.add_track('/path/to/track.h264')
>>> mkv.add_track(MKVTrack('/path/to/another/track.aac'))
>>> mkv.command('/path/to/output.mkv')

Import an existing MKV and remove a track. This example will import an MKV that already exists on your filesystem, remove a track and allow you to mux that change into a new file.

>>> mkv = MKVFile('/path/to/file.mkv')
>>> mkv.remove_track(0)
>>> mkv.mux('/path/to/output.mkv')

Combine two MKVs. This example takes two existing MKVs and combines their tracks into a single MKV file.

>>> mkv1 = MKVFile('/path/to/file1.mkv')
>>> mkv2 = MKVFile('/path/to/file2.mkv')
>>> mkv1.add_file(mkv2)
>>> mkv1.mux('/path/to/output.mkv')

A class that represents an MKV file.

The MKVFile class can either import a pre-existing MKV file or create a new one. After an MKVFile object has been instantiated, MKVTrack objects or other MKVFile objects can be added using add_track() and add_file() respectively.

Tracks are always added in the same order that they exist in a file or are added in. They can be reordered using move_track_front(), move_track_end(), move_track_forward(), move_track_backward(), or swap_tracks().

After an MKVFile has been created, an mkvmerge command can be generated using command() or the file can be muxed using mux().

Parameters:

file_path (str, optional) – Path to a pre-existing MKV file. The file will be imported into the new MKVFile object.
title (str, optional) – The internal title given to the MKVFile. If title is not specified, the title of the pre-existing file will be used if it exists.
mkvmerge_path (str, optional) – The path where pymkv looks for the mkvmerge executable. pymkv relies on the mkvmerge executable to parse files. By default, it is assumed mkvmerge is in your shell’s $PATH variable. If it is not, you need to set mkvmerge_path to the executable location.

Raises:

FileNotFoundError – Raised if the path to mkvmerge could not be verified.

add_attachment(attachment: str | MKVAttachment) → None¶

Add an attachment to the MKVFile.

Parameters:: attachment (str, MKVAttachment) – The attachment to be added to the MKVFile object.
Raises:: TypeError – Raised if if attachment is not a string-like path to an attachment file or an MKVAttachment.

add_file(file: MKVFile | str | PathLike) → None¶

Add an MKV file into the MKVFile object.

Parameters:: file (str, MKVFile, os.PathLike) – The file to be combined with the MKVFile object.
Raises:: TypeError – Raised if if file is not a string-like path to an MKV file or an MKVFile object.

add_track(track: str | MKVTrack, new_file: bool = True) → None¶

Add a track to the MKVFile.

Parameters:

track (str, MKVTrack) – The track to be added to the MKVFile object.
new_file (bool, optional) – If set to True, the file_id for the added track is not incremented. This can be used to preserve original track numbering from a source file.

Raises:

TypeError – Raised if track is not a string-like path to a track file or an MKVTrack.

property chapter_language: str¶

The language code of the chapters in the MKVFile object.

Raises:: ValueError – Raised if not a valid ISO 639-2 language code.
Type:: str

chapters(file_path: str, language: str | None = None) → None¶

Add a chapters file to the MKVFile object.

Parameters:

file_path (str) – The chapters file to be added to the MKVFile object.
language (str, optional) – Must be an ISO639-2 language code. Only applied if no existing language information exists in chapters.

Raises:

FileNotFoundError – Raised if the file at file_path does not exist.
TypeError – Raised if file_path is not of type str.

command(output_path: str, subprocess: bool = False) → str | list¶

Generates an mkvmerge command based on the configured MKVFile.

Parameters:

output_path (str) – The path to be used as the output file in the mkvmerge command.
subprocess (bool) – Will return the command as a list so it can be used easily with the subprocess module.

Returns:

The full command to mux the MKVFile as a string containing spaces. Will be returned as a list of strings with no spaces if subprocess is True.

Return type:

str, list of str

static flatten(item: list | tuple) → list¶

Flatten a list or a tuple.

Takes a list or a tuple that contains other lists or tuples and flattens into a non-nested list.

Examples

>>> tup = ((1, 2), (3, (4, 5)))
>>> print(MKVFile.flatten(tup))
[1, 2, 3, 4, 5]

Parameters:: item (list, tuple) – A list or a tuple object with nested lists or tuples to be flattened.
Returns:: A flattened version of item.
Return type:: list

get_track(track_num: int | None = None) → MKVTrack | list[MKVTrack]¶

Get a MKVTrack from the MKVFile object.

Parameters:: track_num (int, optional) – Index of track to retrieve. Will return list of MKVTrack objects if argument is not provided.
Returns:: A list of all MKVTrack objects in an MKVFile. Returns a specific MKVTrack if track_num is specified.
Return type:: MKVTrack, list of MKVTrack

global_tags(file_path: str) → None¶

Add global tags to the MKVFile object.

Parameters:

file_path (str) – The tags file to be added to the MKVFile object.

Raises:

FileNotFoundError – Raised if the file at file_path does not exist.
TypeError – Raised if file_path is not of type str.

link_to_next(file_path: str) → None¶

Link the output file as the successor of the file_path file.

Parameters:

file_path (str) – Path of the file to be linked to.

Raises:

TypeError – Raised if file_path is not of type str.
ValueError – Raised if file at file_path cannot be verified as an MKV.

link_to_none() → None¶: Remove all linking to previous and next options.

link_to_previous(file_path: str) → None¶

Link the output file as the predecessor of the file_path file.

Parameters:

file_path (str) – Path of the file to be linked to.

Raises:

TypeError – Raised if file_path is not of type str.
ValueError – Raised if file at file_path cannot be verified as an MKV.

move_track_backward(track_num: int) → None¶

Move a track backward in the MKVFile object.

Parameters:: track_num (int) – The track number of the track to move backward.
Raises:: IndexError – Raised if track_num is is out of range of the track list.

move_track_end(track_num: int) → None¶

Set as track as the last in the MKVFile object.

Parameters:: track_num (int) – The track number of the track to move to the back.
Raises:: IndexError – Raised if track_num is is out of range of the track list.

move_track_forward(track_num: int) → None¶

Move a track forward in the MKVFile object.

Parameters:: track_num (int) – The track number of the track to move forward.
Raises:: IndexError – Raised if track_num is is out of range of the track list.

move_track_front(track_num: int) → None¶

Set a track as the first in the MKVFile object.

Parameters:: track_num (int) – The track number of the track to move to the front.
Raises:: IndexError – Raised if track_num is is out of range of the track list.

mux(output_path: str | PathLike, silent: bool = False) → int¶

Mixes the specified MKVFile.

Parameters:

output_path (str) – The path to be used as the output file in the mkvmerge command.
silent (bool, optional) – By default the mkvmerge output will be shown unless silent is True.

Returns:

return code

Return type:

int of Any

Raises:

ValueError – Raised if the external mkvmerge command fails with a non-zero exit status. This includes scenarios such as invalid command arguments, errors in processing the MKVFile, or issues with output file writing. The error message provides details about the failure based on the output of the command.

no_attachments() → None¶: Ignore the existing attachments of the MKVFile object.

no_chapters() → None¶: Ignore the existing chapters of the MKVFile object.

no_global_tags() → None¶: Ignore the existing global tags of the MKVFile object.

no_track_tags() → None¶: Ignore the existing track tags of the MKVFile object.

order_tracks_by_file_id() → None¶

Orders tracks based on their file ID. Tracks from the same file will have the same file ID.

This method first generates a list of unique file paths from the existing tracks. Then, it assigns each track a file ID, which is the index of its file path in the unique list. As a result, tracks from the same file will have the same file ID.

remove_track(track_num: int) → None¶

Remove a track from the MKVFile object.

Parameters:: track_num (int) – The track number of the track to remove.
Raises:: IndexError – Raised if track_num is is out of range of the track list.

replace_track(track_num: int, track: MKVTrack) → None¶

Replace a track with another track in the MKVFile object.

Parameters:

track_num (int) – The track number of the track to replace.
track (MKVTrack) – The MKVTrack to be replaced into the file.

Raises:

IndexError – Raised if track_num is is out of range of the track list.

split_chapters(*chapters: int | list | tuple, link: bool | None = False) → None¶

Split the output file into parts by chapters.

Parameters:

*chapters (int, list, tuple) – The chapters to split the file by. Can be passed as any combination of ints, inside or outside an Iterable object. Any lists will be flattened. Chapters must be ints.
link (bool, optional) – Determines if the split files should be linked together after splitting.

Raises:

TypeError – Raised if any chapters in *chapters are not of type int.
ValueError – Raised if *chapters contains improperly formatted chapters.

split_duration(duration: str | int, link: bool | None = False) → None¶

Split the output file into parts by duration.

Parameters:

duration (str, int) – The duration of each split file. Takes either a str formatted to HH:MM:SS.nnnnnnnnn or an integer representing the number of seconds. The duration string requires formatting of at least M:S.
link (bool, optional) – Determines if the split files should be linked together after splitting.

split_frames(*frames: int | list | tuple, link: bool | None = False) → None¶

Split the output file into parts by frames.

Parameters:

*frames (int, list, tuple) – The frames to split the file by. Can be passed as any combination of ints, inside or outside an Iterable object. Any lists will be flattened. Frames must be ints.
link (bool, optional) – Determines if the split files should be linked together after splitting.

Raises:

TypeError – Raised if non-int frames are passed in for *frames or within the *frames iterable.
ValueError – Raised if improperly formatted frames are passed in for *frames.

split_none() → None¶: Remove all splitting options.

split_parts_frames(frame_parts: list | tuple, link: bool | None = False) → None¶

Split the output in parts by frames.

Parameters:

frame_parts (list, tuple) – An Iterable of frame sets. Each frame set should be an Iterable object of an even number of frames or any number of frame pairs. The very first and last frames are permitted to be None. Frame sets containing four or more frames will output as one file containing the parts specified.
link (bool, optional) – Determines if the split files should be linked together after splitting.

Raises:

TypeError – Raised if any of the frame sets are not a list or tuple.
ValueError – Raised if frame_parts contains improperly formatted parts.

split_size(size: Bitmath | int, link: bool | None = False) → None¶

Split the output file into parts by size.

Parameters:

size (bitmath, int) – The size of each split file. Takes either a bitmath size object or an integer representing the number of bytes.
link (bool, optional) – Determines if the split files should be linked together after splitting.

Raises:

TypeError – Raised if if size is not a bitmath object or an integer.

split_timestamp_parts(timestamp_parts: list | tuple, link: bool | None = False) → None¶

Split the output in parts by time parts.

Parameters:

timestamp_parts (list, tuple) – An Iterable of timestamp sets. Each timestamp set should be an Iterable of an even number of timestamps or any number of timestamp pairs. The very first and last timestamps are permitted to be None. Timestamp sets containing 4 or more timestamps will output as one file containing the parts specified.
link (bool, optional) – Determines if the split files should be linked together after splitting.

Raises:

TypeError – Raised if any of the timestamp sets are not a list or tuple.
ValueError – Raised if timestamp_parts contains improperly formatted parts.

split_timestamps(*timestamps: str | int | list | tuple, link: bool | None = False) → None¶

Split the output file into parts by timestamps.

Parameters:

*timestamps (str, int, list, tuple) – The timestamps to split the file by. Can be passed as any combination of strs and ints, inside or outside an Iterable object. Any lists will be flattened. Timestamps must be ints, representing seconds, or strs in the form HH:MM:SS.nnnnnnnnn. The timestamp string requires formatting of at least M:S.
link (bool, optional) – Determines if the split files should be linked together after splitting.

Raises:

ValueError – Raised if invalid or improperly formatted timestamps are passed in for *timestamps.

swap_tracks(track_num_1: int, track_num_2: int) → None¶

Swap the position of two tracks in the MKVFile object.

Parameters:

track_num_1 (int) – The track number of one track to swap.
track_num_2 (int) – The track number of the other track to swap

Raises:

IndexError – Raised if track_num_1 or track_num_2 are out of range of the track list.

track_tags(*track_ids: int | list | tuple, exclusive: bool | None = False) → None¶

Include or exclude tags from specific tracks.

Parameters:

*track_ids (int, list, tuple) – Track ids to have tags included or excluded from.
exclusive (bool, optional) – Determines if the track_ids should have their tags kept or removed. exclusive is False by default and will remove tags from unspecified tracks.

Raises:

IndexError – Raised if any ids from *track_ids is is out of range of the track list.
TypeError – Raised if an ids from *track_ids are not of type int.
ValueError – Raised if *track_ids are improperly formatted.