Source code for cutcutcodec.core.analysis.video.properties.range

"""Find or guess the color range of a video stream."""

import collections
import pathlib

from cutcutcodec.core.analysis._helper_properties import _check_pathexists_index, _mix_and_check
from cutcutcodec.core.analysis.ffprobe import _estimate_range_ffmpeg, _map_index_rel_to_abs




def get_range(
    filename: pathlib.Path | str | bytes, index: int = 0,
) -> str | None:
    """Read in the metadata, the color range.

    Parameters
    ----------
    filename : pathlike
        The pathlike of the file containing a video stream.
    index : int
        The relative index of the video stream being considered,
        by default the first stream encountered is selected.

    Returns
    -------
    range : str
        The name of the color range ``pc``, ``tv`` or None.

    Raises
    ------
    MissingStreamError
        If the file does not contain a playable video stream.
    MissingInformation
        If the information is unavailable.

    Examples
    --------
    >>> from cutcutcodec.core.analysis.video.properties.range import get_range
    >>> from cutcutcodec.utils import get_project_root
    >>> media = get_project_root() / "media" / "video" / "intro.webm"
    >>> get_range(media)
    'tv'
    >>>

    """
    _check_pathexists_index(filename, index)

    return _mix_and_check(
        None, False, (str(pathlib.Path(filename)), index),
        collections.OrderedDict([
            (
                (
                    lambda filename, index: _estimate_range_ffmpeg(
                        filename, _map_index_rel_to_abs(filename, index, "video"),
                    )
                ),
                {"accurate": False, "backend": "ffmpeg"},
            ),
        ]),
    )