bitstream-filters

Enums

BSF_ChromaLocation

Bases: IntEnum

Collection of known chroma sample location values.

For more documentation on these, check out the H265 Specification (Figure E.1) or JET Documentation.

Source code in muxtools/helpers/bsf/bsf_generic.py

class BSF_ChromaLocation(IntEnum):
    """
    Collection of known chroma sample location values.

    For more documentation on these, check out the [H265 Specification](https://www.itu.int/rec/t-rec-h.265) (Figure E.1) or [JET Documentation](https://jaded-encoding-thaumaturgy.github.io/vs-jetpack/api/vstools/enums/generic/#vstools.enums.generic.ChromaLocation).
    """

    LEFT = 0
    CENTER = 1
    TOP_LEFT = 2
    TOP = 3
    BOTTOM_LEFT = 4
    BOTTOM = 5

BSF_Matrix

Bases: IntEnum

Collection of known bitstream matrix values.

For more documentation on these, check out the H265 Specification (Table E.5) or JET Documentation.

Source code in muxtools/helpers/bsf/bsf_generic.py

class BSF_Matrix(IntEnum):
    """
    Collection of known bitstream matrix values.

    For more documentation on these, check out the [H265 Specification](https://www.itu.int/rec/t-rec-h.265) (Table E.5) or [JET Documentation](https://jaded-encoding-thaumaturgy.github.io/vs-jetpack/api/vstools/enums/color/#vstools.enums.color.Matrix).
    """

    RGB = 0
    GBR = RGB
    IDENTITY = RGB
    BT709 = 1
    UNKNOWN = 2
    FCC = 3
    BT470BG = 5
    BT601_625 = BT470BG
    SMPTE170M = 6
    BT601_525 = SMPTE170M
    SMPTE240M = 7
    YCGCO = 8
    BT2020NCL = 9
    BT2020CL = 10
    CHROMANCL = 12
    CHROMACL = 13
    ICTCP = 14

BSF_Transfer

Bases: IntEnum

Collection of known bitstream transfer values.

For more documentation on these, check out the H265 Specification (Table E.4) or JET Documentation.

Source code in muxtools/helpers/bsf/bsf_generic.py

class BSF_Transfer(IntEnum):
    """
    Collection of known bitstream transfer values.

    For more documentation on these, check out the [H265 Specification](https://www.itu.int/rec/t-rec-h.265) (Table E.4) or [JET Documentation](https://jaded-encoding-thaumaturgy.github.io/vs-jetpack/api/vstools/enums/color/#vstools.enums.color.Transfer).
    """

    BT709 = 1
    BT1886 = BT709
    UNKNOWN = 2
    BT470M = 4
    BT470BG = 5
    SMPTE170M = 6
    BT601 = SMPTE170M
    SMPTE240M = 7
    LINEAR = 8
    LOG100 = 9
    LOG316 = 10
    XVYCC = 11
    SRGB = 13
    BT2020_10 = 14
    BT2020_12 = 15
    ST2084 = 16
    PQ = ST2084
    STD_B67 = 18
    HLG = STD_B67

BSF_Primaries

Bases: IntEnum

Collection of known bitstream color primaries values.

For more documentation on these, check out the H265 Specification (Table E.3) or JET Documentation.

Source code in muxtools/helpers/bsf/bsf_generic.py

class BSF_Primaries(IntEnum):
    """
    Collection of known bitstream color primaries values.

    For more documentation on these, check out the [H265 Specification](https://www.itu.int/rec/t-rec-h.265) (Table E.3) or [JET Documentation](https://jaded-encoding-thaumaturgy.github.io/vs-jetpack/api/vstools/enums/color/#vstools.enums.color.Primaries).
    """

    BT709 = 1
    UNKNOWN = 2
    BT470M = 4
    BT470BG = 5
    BT601_625 = BT470BG
    SMPTE170M = 6
    BT601_525 = SMPTE170M
    SMPTE240M = 7
    FILM = 8
    BT2020 = 9
    ST428 = 10
    XYZ = ST428
    CIE1931 = ST428
    ST431_2 = 11
    DCI_P3 = ST431_2
    ST432_1 = 12
    DISPLAY_P3 = ST432_1
    JEDEC_P22 = 22
    EBU3213 = JEDEC_P22

BSF_Format

Bases: IntEnum

Collection of known bitstream video_format values.

For more documentation on these, check out the H265 Specification (Table E.2)

Source code in muxtools/helpers/bsf/bsf_generic.py

class BSF_Format(IntEnum):
    """
    Collection of known bitstream video_format values.

    For more documentation on these, check out the [H265 Specification](https://www.itu.int/rec/t-rec-h.265) (Table E.2)
    """

    COMPONENT = 0
    PAL = 1
    NTSC = 2
    SECAM = 3
    MAC = 4
    UNSPECIFIED = 5

Functions

apply_mpeg2_bsf(fileIn, dar=None, fps=None, format=None, primaries=None, transfer=None, matrix=None, quiet=True)

A helper for the FFMpeg mpeg2_metadata bitstream filter.

None values will do nothing to the respective metadata flags.

Parameters:

Name	Type	Description	Default
fileIn	PathLike	The file to modify	required
dar	MPEG2_DAR | str | None	Set the display aspect ratio in the stream	None
fps	MPEG2_FPS | str | None	Set the frame rate in the stream	None
format	BSF_Format | int | None	Set the video format in the stream	None
primaries	BSF_Primaries | int | None	Set the color primaries in the stream	None
transfer	BSF_Transfer | int | None	Set the transfer characteristics in the stream	None
matrix	BSF_Matrix | int | None	Set the matrix coefficients in the stream	None
quiet	bool	Suppresses the output of ffmpeg	True

Source code in muxtools/helpers/bsf/bsf_mpeg2.py

def apply_mpeg2_bsf(
    fileIn: PathLike,
    dar: MPEG2_DAR | str | None = None,
    fps: MPEG2_FPS | str | None = None,
    format: BSF_Format | int | None = None,
    primaries: BSF_Primaries | int | None = None,
    transfer: BSF_Transfer | int | None = None,
    matrix: BSF_Matrix | int | None = None,
    quiet: bool = True,
):
    """
    A helper for the FFMpeg [mpeg2_metadata](https://ffmpeg.org/ffmpeg-bitstream-filters.html#mpeg2_005fmetadata) bitstream filter.

    `None` values will do nothing to the respective metadata flags.

    :param fileIn:                      The file to modify
    :param dar:                         Set the display aspect ratio in the stream
    :param fps:                         Set the frame rate in the stream
    :param format:                      Set the video format in the stream
    :param primaries:                   Set the color primaries in the stream
    :param transfer:                    Set the transfer characteristics in the stream
    :param matrix:                      Set the matrix coefficients in the stream
    :param quiet:                       Suppresses the output of ffmpeg
    """
    f = ensure_path_exists(fileIn, apply_mpeg2_bsf)
    filter_options = list[str]()

    if dar is not None:
        filter_options.append(f"display_aspect_ratio={str(dar.value) if isinstance(dar, MPEG2_DAR) else str(dar)}")

    if fps is not None:
        filter_options.append(f"frame_rate={str(fps.value) if isinstance(fps, MPEG2_FPS) else str(fps)}")

    if format is not None and (format := BSF_Format(format)) is not None:
        filter_options.append(f"video_format={str(format.value)}")

    if primaries is not None and (primaries := BSF_Primaries(primaries)) is not None:
        if primaries.value not in range(1, 8):
            raise error(f"'{primaries}' is not a valid primaries value for MPEG2 streams!")
        filter_options.append(f"colour_primaries={str(primaries.value)}")

    if transfer is not None and (transfer := BSF_Transfer(transfer)) is not None:
        if transfer.value not in range(1, 9):
            raise error(f"'{transfer}' is not a valid transfer value for MPEG2 streams!")
        filter_options.append(f"transfer_characteristics={str(transfer.value)}")

    if matrix is not None and (matrix := BSF_Matrix(matrix)) is not None:
        if matrix.value not in range(1, 8):
            raise error(f"'{matrix}' is not a valid matrix value for MPEG2 streams!")
        filter_options.append(f"matrix_coefficients={str(matrix.value)}")

    if not filter_options:
        raise error("No changes to be made!", apply_mpeg2_bsf)

    _apply_bsf(f, "mpeg2_metadata", filter_options, apply_mpeg2_bsf, quiet)

apply_avc_bsf(fileIn, sar=None, cloc_type=None, full_range=None, format=None, primaries=None, transfer=None, matrix=None, crop=None, quiet=True, **kwargs)

A helper for the FFMpeg h264_metadata bitstream filter.

None values will do nothing to the respective metadata flags.

Parameters:

Name	Type	Description	Default
fileIn	PathLike	The file to modify	required
sar	int | None	Set the sample aspect ratio in the stream	None
cloc_type	BSF_ChromaLocation | int | None	Set the chroma sample location in the stream	None
full_range	bool | int | None	Set the full range flag in the stream	None
format	BSF_Format | int | None	Set the video format in the stream	None
primaries	BSF_Primaries | int | None	Set the color primaries in the stream	None
transfer	BSF_Transfer | int | None	Set the transfer characteristics in the stream	None
matrix	BSF_Matrix | int | None	Set the matrix coefficients in the stream	None
crop	int | tuple[int, int] | tuple[int, int, int, int] | None	Set the crop values in the stream	None
quiet	bool	Suppresses the output of ffmpeg	True
kwargs	bool | str	Additional options for the filter. For other available options, check the hyperlink to the filter above.	{}

Source code in muxtools/helpers/bsf/bsf_hevc_avc.py

def apply_avc_bsf(
    fileIn: PathLike,
    sar: int | None = None,
    cloc_type: BSF_ChromaLocation | int | None = None,
    full_range: bool | int | None = None,
    format: BSF_Format | int | None = None,
    primaries: BSF_Primaries | int | None = None,
    transfer: BSF_Transfer | int | None = None,
    matrix: BSF_Matrix | int | None = None,
    crop: int | tuple[int, int] | tuple[int, int, int, int] | None = None,
    quiet: bool = True,
    **kwargs: bool | str,
):
    """
    A helper for the FFMpeg [h264_metadata](https://ffmpeg.org/ffmpeg-bitstream-filters.html#h264_005fmetadata) bitstream filter.

    `None` values will do nothing to the respective metadata flags.

    :param fileIn:                      The file to modify
    :param sar:                         Set the sample aspect ratio in the stream
    :param cloc_type:                   Set the chroma sample location in the stream
    :param full_range:                  Set the full range flag in the stream
    :param format:                      Set the video format in the stream
    :param primaries:                   Set the color primaries in the stream
    :param transfer:                    Set the transfer characteristics in the stream
    :param matrix:                      Set the matrix coefficients in the stream
    :param crop:                        Set the crop values in the stream
    :param quiet:                       Suppresses the output of ffmpeg
    :param kwargs:                      Additional options for the filter.\n
                                        For other available options, check the hyperlink to the filter above.
    """

    _apply_avc_hevc_bsf(
        fileIn,
        "h264_metadata",
        sar=sar,
        cloc_type=cloc_type,
        full_range=full_range,
        format=format,
        primaries=primaries,
        transfer=transfer,
        matrix=matrix,
        crop=crop,
        quiet=quiet,
        caller=apply_avc_bsf,
        **kwargs,
    )

apply_hevc_bsf(fileIn, sar=None, cloc_type=None, full_range=None, format=None, primaries=None, transfer=None, matrix=None, crop=None, quiet=True, **kwargs)

A helper for the FFMpeg hevc_metadata bitstream filter.

None values will do nothing to the respective metadata flags.

Parameters:

Name	Type	Description	Default
fileIn	PathLike	The file to modify	required
sar	int | None	Set the sample aspect ratio in the stream	None
cloc_type	BSF_ChromaLocation | int | None	Set the chroma sample location in the stream	None
full_range	bool | int | None	Set the full range flag in the stream	None
format	BSF_Format | int | None	Set the video format in the stream	None
primaries	BSF_Primaries | int | None	Set the color primaries in the stream	None
transfer	BSF_Transfer | int | None	Set the transfer characteristics in the stream	None
matrix	BSF_Matrix | int | None	Set the matrix coefficients in the stream	None
crop	int | tuple[int, int] | tuple[int, int, int, int] | None	Set the crop values in the stream	None
quiet	bool	Suppresses the output of ffmpeg	True
kwargs	bool | str	Additional options for the filter. For available options, check the hyperlink to the filter above.	{}

Source code in muxtools/helpers/bsf/bsf_hevc_avc.py

def apply_hevc_bsf(
    fileIn: PathLike,
    sar: int | None = None,
    cloc_type: BSF_ChromaLocation | int | None = None,
    full_range: bool | int | None = None,
    format: BSF_Format | int | None = None,
    primaries: BSF_Primaries | int | None = None,
    transfer: BSF_Transfer | int | None = None,
    matrix: BSF_Matrix | int | None = None,
    crop: int | tuple[int, int] | tuple[int, int, int, int] | None = None,
    quiet: bool = True,
    **kwargs: bool | str,
):
    """
    A helper for the FFMpeg [hevc_metadata](https://ffmpeg.org/ffmpeg-bitstream-filters.html#hevc_005fmetadata) bitstream filter.

    `None` values will do nothing to the respective metadata flags.

    :param fileIn:                      The file to modify
    :param sar:                         Set the sample aspect ratio in the stream
    :param cloc_type:                   Set the chroma sample location in the stream
    :param full_range:                  Set the full range flag in the stream
    :param format:                      Set the video format in the stream
    :param primaries:                   Set the color primaries in the stream
    :param transfer:                    Set the transfer characteristics in the stream
    :param matrix:                      Set the matrix coefficients in the stream
    :param crop:                        Set the crop values in the stream
    :param quiet:                       Suppresses the output of ffmpeg
    :param kwargs:                      Additional options for the filter.\n
                                        For available options, check the hyperlink to the filter above.
    """

    _apply_avc_hevc_bsf(
        fileIn,
        "hevc_metadata",
        sar=sar,
        cloc_type=cloc_type,
        full_range=full_range,
        format=format,
        primaries=primaries,
        transfer=transfer,
        matrix=matrix,
        crop=crop,
        quiet=quiet,
        caller=apply_hevc_bsf,
        **kwargs,
    )