MKVTrack¶

MKVTrack classes are used to represent tracks within an MKV or to be used in an MKV. They can represent a video, audio, or subtitle track.

Examples

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

Create a new MKVTrack from a track file. This example takes a standalone track file and uses it in an MKVTrack.

>>> from pymkv import MKVTrack
>>> track1 = MKVTrack("path/to/track.h264")
>>> track1.track_name = "Some Name"
>>> track1.language = "eng"

Create a new MKVTrack from an MKV file. This example will take a specific track from an MKV and also prevent any global tags from being included if the MKVTrack is muxed into an MKVFile.

>>> track2 = MKVTrack("path/to/track.aac")
>>> track2.language = "eng"

Create a new MKVTrack from an MKV file. This example will take a specific track from an MKV and also prevent any global tags from being included if the MKVTrack is muxed into an MKVFile.

>>> track3 = MKVTrack("path/to/MKV.mkv", track_id=1)
>>> track3.no_global_tags = True

Now all these tracks can be added to an MKVFile object and muxed together.

>>> from pymkv import MKVFile
>>> file = MKVFile()
>>> file.add_track(track1)
>>> file.add_track(track2)
>>> file.add_track(track3)
>>> file.mux("path/to/output.mkv")

A class that represents a track for an MKVFile object. MKVTrack objects are video, audio, or subtitles. Tracks can be standalone files or a single track within an MKV file, both can be handled by pymkv. An MKVTrack object can be added to an MKVFile and will be included when the MKV is muxed. :param file_path: Path to the track file. This can also be an MKV where the track_id is the track represented in the MKV. :type file_path: str :param track_id: The id of the track to be used from the file. track_id only needs to be set when importing a track from

an MKV. In this case, you can specify track_id to indicate which track from the MKV should be used. If not set, it will import the first track. Track 0 is imported by default because mkvmerge sees standalone track files as having one track with track_id set as 0.

Parameters:

track_name (str, optional) – The name that will be given to the track when muxed into a file.
language (str, optional) – The language of the track. It must be an ISO639-2 language code.
language_ietf (str, optional) – The language of the track. It must be a BCP47 language code. Has priority over ‘language’.
default_track (bool, optional) – Determines if the track should be the default track of its type when muxed into an MKV file.
forced_track (bool, optional) – Determines if the track should be a forced track when muxed into an MKV file.
mkvmerge_path (str, list, os.PathLike, 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.
mkvextract_path (str, list, os.PathLike, optional) – The path where pymkv looks for the mkvextract executable. pymkv relies on the mkvextract executable to extract files. By default, it is assumed mkvextract is in your shell’s $PATH variable. If it is not, you need to set mkvextract_path to the executable location.

mkvmerge_path¶

The path of the mkvmerge executable.

Type:: list

mkvextract_path¶

The path of the mkvextract executable.

Type:: list

track_name¶

The name that will be given to the track when muxed into a file.

Type:: str

default_track¶

Determines if the track should be the default track of its type when muxed into an MKV file.

Type:: bool

forced_track¶

Determines if the track should be a forced track when muxed into an MKV file.

Type:: bool

no_chapters¶

If chapters exist in the track file, don’t include them when this MKVTrack object is a track in an MKVFile mux operation. This option has no effect on standalone track files, only tracks that are already part of an MKV file.

Type:: bool

no_global_tags¶

If global tags exist in the track file, don’t include them when this MKVTrack object is a track in an MKVFile mux operation. This option has no effect on standalone track files, only tracks that are already part of an MKV file.

Type:: bool

no_track_tags¶

If track tags exist in the specified track within the track file, don’t include them when this MKVTrack object is a track in an MKVFile mux operation. This option has no effect on standalone track files, only tracks that are already part of an MKV file.

Type:: bool

no_attachments¶

If attachments exist in the track file, don’t include them when this MKVTrack object is a track in an MKVFile mux operation. This option has no effect on standalone track files, only tracks that are already part of an MKV file.

Type:: bool

extract(output_path: str | PathLike | None = None, silent: bool | None = False) → str¶

Extract the track as a file.

Parameters:

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

Returns:

The path of the extracted file.

Return type:

str

property file_id: int¶

The ID of the file the track belongs to.

The file ID represents which file the current track is associated with. This is particularly useful when handling multiple files.

Raises:: IndexError – Raised if the passed in index is out of range of the file’s tracks.
Type:: int

property file_path: str¶

The path to the track or MKV file containing the desired track.

Setting this property will verify the passed in file is supported by mkvmerge and set the track_id to 0. It is recommended to recreate MKVTracks instead of setting their file path after instantiation.

Raises:: ValueError – Raised if file_path is not a supported file type.
Type:: str

property language: str¶

The language of the track.

Setting this property will verify that the passed in language is an ISO-639 language code and use it as the language for the track.

Raises:: ValueError – Raised if the passed in language is not an ISO 639-2 language code.
Type:: str

property language_ietf: str¶

The language of the track with BCP47 format. Setting this property will verify that the passed in language is a BCP47 language code and use it as the language for the track. :raises ValueError: Raised if the passed in language is not a BCP47 language code.

Type:: str

property pts: int¶

Returns the value of the pts property. The Presentation Timestamp (PTS) in multimedia files indicates the exact time when a frame or audio sample should be presented to the user, ensuring accurate synchronization between audio and video streams.

Parameters:: self – The instance of the class.
Returns:: The value of the pts property.

property sync: int¶

track delay.

Setting this property allows you to wiggle the track negatively/positively.

Type:: int

property tags: str¶

The tags file to include with the track.

Setting this property will check that the file path passed in exists and set it as the tags file.

Raises:

FileNotFoundError – Raised if the passed in file does not exist or is not a file.
TypeError – Raises if the passed in file is not of type str.

Type:

str

property track_codec: str¶

The codec of the track such as h264 or AAC.

Type:: str

property track_id: int¶

The ID of the track within the file.

Setting track_id will check that the ID passed in exists in the file. It will then look at the new track and set the codec and track type. Should be left at 0 unless extracting a specific track from an MKV.

Raises:: IndexError – Raised if the passed in index is out of range of the file’s tracks.
Type:: int

property track_type: str¶

The type of track such as video or audio.

Type:: str