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")

class pymkv.MKVTrack(file_path: str, track_id: int = 0, track_name: str | None = None, language: str | None = None, language_ietf: str | None = None, default_track: bool | None = False, forced_track: bool | None = False, flag_commentary: bool | None = False, flag_hearing_impaired: bool | None = False, flag_visual_impaired: bool | None = False, flag_original: bool | None = False, mkvmerge_path: str | os.PathLike | Iterable[str] = 'mkvmerge', mkvextract_path: str | os.PathLike | Iterable[str] = 'mkvextract', sync: int | None = None, existing_info: dict[str, Any] | None = None, tag_entries: int = 0, compression: bool | None = None)¶

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.

Parameters:¶

file_path : str¶

Path to the track file. This can also be an MKV where the track_id is the track represented in the MKV.

track_id : int, optional¶

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.

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.

tag_entries : int, optional¶

The number of tag entries.

compression : bool, optional¶

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

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

compression¶

Determines if the track should be compressed 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 | None, optional¶

The path to be used as the output file

command. : in the mkvextract

silent : bool | None, 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¶

Get 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.

Returns:¶

The file ID.

Return type:¶

int

Raises:¶

IndexError – If the passed in index is out of range of the file’s tracks.

property file_path : str¶

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

Returns:¶

The file path.

Return type:¶

str

Raises:¶

ValueError – If file_path is not a supported file type.

property language : str | None¶

Get the language of the track.

Returns:¶

The language of the track.

Return type:¶

str

Raises:¶

ValueError – If the passed in language is not an ISO 639-2 language code.

property language_ietf : str | None¶

Get the language of the track with BCP47 format.

Returns:¶

The language of the track in BCP47 format.

Return type:¶

str

Raises:¶

ValueError – If the passed in language is not a BCP47 language code.

property pts : int¶

Get the Presentation Timestamp (PTS) of the track.

The 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.

Returns:¶

The PTS value.

Return type:¶

int

property sync : int | None¶

Get the synchronization offset for the track.

This property represents the synchronization offset for the track. Positive values delay the track, while negative values advance it.

Returns:¶

The current synchronization offset in milliseconds.

Return type:¶

int

Note

Setting this property allows you to adjust the track timing: - Positive values delay the track (shift it later in time) - Negative values advance the track (shift it earlier in time)

Example

track.sync = 1000 # Delay the track by 1 second track.sync = -500 # Advance the track by 0.5 seconds

property tag_entries : int¶

Gets the number of existing tag entries in the track.

Returns:¶

The number of entries.

Return type:¶

int

property tags : str | None¶

Get the tags file to include with the track.

Returns:¶

The path to the tags file.

Return type:¶

str

Raises:¶

• FileNotFoundError – If the passed in file does not exist or is not a file.

• TypeError – If the passed in file is not of type str.

property track_codec : str | None¶

Get the codec of the track.

Returns:¶

The codec of the track, such as h264 or AAC.

Return type:¶

str

property track_id : int¶

Get the ID of the track within the file.

Returns:¶

The track ID.

Return type:¶

int

Raises:¶

IndexError – If the passed in index is out of range of the file’s tracks.

property track_type : str | None¶

Get the type of the track.

Returns:¶

The type of track, such as video or audio.

Return type:¶

str