muxtools.helpers.extract

def video_track(self, track: int = 0, output: PathLike = None, quiet: bool = True, **kwargs: Any) -> VideoTrack:
    """
    Extract a video track from the file.

    The track name, language, default/forced flags and custom tags are inherited unless overridden.\n
    Timestamps are extracted automatically to preserve variable frame rate and container timing.

    :param track:               Relative video track number, starting at 0.
    :param output:              Custom output. Can be an existing directory or a file.\n
                                `None` uses the default output directory of the helper.\n
                                The file extension will be set automatically.

    :param quiet:               Suppresses the output.\n
                                The stdout will still be printed on failure regardless of this setting.

    :param kwargs:              Any other parameters to pass to `VideoTrack`. These override inherited metadata.\n
                                Pass `timecode_file` to use existing timestamps instead of extracting them.\n
                                `delay` adds a shift in ms to the timestamped video.

    :return:                    The extracted video as a `VideoTrack`.
    """
    return self._extract_track(VideoTrack, TrackType.VIDEO, track, output, quiet, **kwargs)

def audio_track(self, track: int = 0, output: PathLike = None, quiet: bool = True, **kwargs: Any) -> AudioTrack:
    """
    Extract an audio track from the file without conversion.

    The track name, language, default/forced flags and custom tags are inherited unless overridden.\n
    The format has to be supported by `AudioFormat`. Existing container timing is preserved.

    :param track:               Relative audio track number, starting at 0.
    :param output:              Custom output. Can be an existing directory or a file.\n
                                `None` uses the default output directory of the helper.\n
                                The file extension will be set automatically.

    :param quiet:               Suppresses the output.\n
                                The stdout will still be printed on failure regardless of this setting.

    :param kwargs:              Any other parameters to pass to `AudioTrack`. These override inherited metadata.\n
                                `delay` replaces the preserved source offset in ms.

    :return:                    The extracted audio as an `AudioTrack`.
    """
    return self._extract_track(AudioTrack, TrackType.AUDIO, track, output, quiet, **kwargs)

def sub_track(self, track: int = 0, output: PathLike = None, quiet: bool = True, **kwargs: Any) -> SubTrack:
    """
    Extract a subtitle track from the file without conversion. SRT will stay SRT.

    The track name, language, default/forced flags and custom tags are inherited unless overridden.\n
    Existing subtitle timing is preserved. VobSub returns an `.idx` file with its `.sub` companion.

    :param track:               Relative subtitle track number, starting at 0.
    :param output:              Custom output. Can be an existing directory or a file.\n
                                `None` uses the default output directory of the helper.\n
                                The file extension will be set automatically.

    :param quiet:               Suppresses the output.\n
                                The stdout will still be printed on failure regardless of this setting.

    :param kwargs:              Any other parameters to pass to `SubTrack`. These override inherited metadata.\n
                                `delay` adds a shift in ms to the extracted subtitles.

    :return:                    The extracted subtitle as a `SubTrack`.
    """
    return self._extract_track(SubTrack, TrackType.SUB, track, output, quiet, **kwargs)

def attachment(
    self, track: int = 0, output: PathLike = None, quiet: bool = True, *, name: str | None = None, mimetype: str | None = None
) -> Attachment:
    """
    Extract an attachment from the file.

    The original attachment name and MIME type are inherited unless overridden.

    :param track:               Relative attachment number, starting at 0.
    :param output:              Custom output. Can be an existing directory or a file.\n
                                `None` uses the default output directory of the helper.\n
                                Generated filenames are based on the original attachment name.

    :param quiet:               Suppresses the output.\n
                                The stdout will still be printed on failure regardless of this setting.

    :param name:                Name of the attachment when muxing. `None` keeps the original name.
    :param mimetype:            MIME type of the returned attachment. `None` keeps the original MIME type.
    :return:                    The extracted attachment as an `Attachment`.
    """
    if track < 0 or track >= len(self._info.attachments):
        raise ValueError(f"Could not find attachment {track} in '{self._fileIn.name}'.")
    item = self._info.attachments[track]
    path = self._attachment_output(item, output)
    with self._extract(["attachments", f"{item.id}:{path}"], [path], quiet):
        return Attachment(
            path, mimetype=(item.content_type or "") if mimetype is None else mimetype, name=item.file_name if name is None else name
        )

def attachments(self, output: PathLike = None, quiet: bool = True) -> list[Attachment]:
    """
    Extract all attachments from the file in one pass.

    Original attachment names and MIME types are preserved.

    :param output:              Output directory. `None` uses the default output directory of the helper.\n
                                The directory will be created if it does not exist.

    :param quiet:               Suppresses the output.\n
                                The stdout will still be printed on failure regardless of this setting.

    :return:                    A list of `Attachment` objects in source order.\n
                                An empty list is returned if the file has no attachments.
    """
    target = ensure_path(self.output if output is None else output, self)
    if target.exists() and not target.is_dir():
        raise ValueError("The output for attachments must be a directory.")
    target.mkdir(parents=True, exist_ok=True)
    paths: list[Path] = []
    for item in self._info.attachments:
        paths.append(self._attachment_output(item, target, reserved=paths))
    if not paths:
        return []
    args = ["attachments", *[f"{item.id}:{path}" for item, path in zip(self._info.attachments, paths)]]
    with self._extract(args, paths, quiet):
        return [Attachment(path, mimetype=item.content_type or "", name=item.file_name) for item, path in zip(self._info.attachments, paths)]