torchcodec 0.10.0__cp312-cp312-manylinux_2_28_x86_64.whl

torchcodec/samplers/_index_based.py

@@ -0,0 +1,287 @@
+from typing import Literal
+
+import torch
+
+from torchcodec import FrameBatch
+from torchcodec.decoders import VideoDecoder
+from torchcodec.samplers._common import (
+    _FRAMEBATCH_RETURN_DOCS,
+    _POLICY_FUNCTION_TYPE,
+    _POLICY_FUNCTIONS,
+    _reshape_4d_framebatch_into_5d,
+    _validate_common_params,
+)
+
+
+def _validate_params_index_based(*, num_clips, num_indices_between_frames):
+    if num_clips <= 0:
+        raise ValueError(f"num_clips ({num_clips}) must be > 0")
+
+    if num_indices_between_frames <= 0:
+        raise ValueError(
+            f"num_indices_between_frames ({num_indices_between_frames}) must be strictly positive"
+        )
+
+
+def _validate_sampling_range_index_based(
+    *,
+    num_indices_between_frames,
+    num_frames_per_clip,
+    sampling_range_start,
+    sampling_range_end,
+    num_frames_in_video,
+):
+    if sampling_range_start < 0:
+        sampling_range_start = num_frames_in_video + sampling_range_start
+
+    if sampling_range_start >= num_frames_in_video:
+        raise ValueError(
+            f"sampling_range_start ({sampling_range_start}) must be smaller than "
+            f"the number of frames ({num_frames_in_video})."
+        )
+
+    clip_span = _get_clip_span(
+        num_indices_between_frames=num_indices_between_frames,
+        num_frames_per_clip=num_frames_per_clip,
+    )
+
+    if sampling_range_end is None:
+        sampling_range_end = max(num_frames_in_video - clip_span + 1, 1)
+        if sampling_range_start >= sampling_range_end:
+            raise ValueError(
+                f"We determined that sampling_range_end should be {sampling_range_end}, "
+                "but it is smaller than or equal to sampling_range_start "
+                f"({sampling_range_start})."
+            )
+    else:
+        if sampling_range_end < 0:
+            # Support negative values so that -1 means last frame.
+            sampling_range_end = num_frames_in_video + sampling_range_end
+        sampling_range_end = min(sampling_range_end, num_frames_in_video)
+        if sampling_range_start >= sampling_range_end:
+            raise ValueError(
+                f"sampling_range_start ({sampling_range_start}) must be smaller than "
+                f"sampling_range_end ({sampling_range_end})."
+            )
+
+    return sampling_range_start, sampling_range_end
+
+
+def _get_clip_span(*, num_indices_between_frames, num_frames_per_clip):
+    """Return the span of a clip, i.e. the number of frames (or indices)
+    between the first and last frame in the clip, both included.
+
+    This isn't the same as the number of frames in a clip!
+    Example: f means a frame in the clip, x means a frame excluded from the clip
+    num_frames_per_clip = 4
+    num_indices_between_frames = 1, clip = ffff      , span = 4
+    num_indices_between_frames = 2, clip = fxfxfxf   , span = 7
+    num_indices_between_frames = 3, clip = fxxfxxfxxf, span = 10
+    """
+    return num_indices_between_frames * (num_frames_per_clip - 1) + 1
+
+
+def _build_all_clips_indices(
+    *,
+    clip_start_indices: torch.Tensor,  # 1D int tensor
+    num_frames_per_clip: int,
+    num_indices_between_frames: int,
+    num_frames_in_video: int,
+    policy_fun: _POLICY_FUNCTION_TYPE,
+) -> list[int]:
+    # From the clip_start_indices [f_00, f_10, f_20, ...]
+    # and from the rest of the parameters, return the list of all the frame
+    # indices that make up all the clips.
+    # I.e. the output is [f_00, f_01, f_02, f_03, f_10, f_11, f_12, f_13, ...]
+    # where f_01 is the index of frame 1 in clip 0.
+    #
+    # All clips in the output are of length num_frames_per_clip (=4 in example
+    # above). When the frame indices go beyond num_frames_in_video, we force the
+    # frame indices back to valid values by applying the user's policy (wrap,
+    # repeat, etc.).
+    all_clips_indices: list[int] = []
+
+    clip_span = _get_clip_span(
+        num_indices_between_frames=num_indices_between_frames,
+        num_frames_per_clip=num_frames_per_clip,
+    )
+
+    for start_index in clip_start_indices:
+        frame_index_upper_bound = min(start_index + clip_span, num_frames_in_video)
+        frame_indices = list(
+            range(start_index, frame_index_upper_bound, num_indices_between_frames)
+        )
+        if len(frame_indices) < num_frames_per_clip:
+            frame_indices = policy_fun(frame_indices, num_frames_per_clip)  # type: ignore[assignment]
+        all_clips_indices += frame_indices
+    return all_clips_indices
+
+
+def _generic_index_based_sampler(
+    kind: Literal["random", "regular"],
+    decoder: VideoDecoder,
+    *,
+    num_clips: int,
+    num_frames_per_clip: int,
+    num_indices_between_frames: int,
+    sampling_range_start: int,
+    sampling_range_end: int | None,  # interval is [start, end).
+    # Important note: sampling_range_end defines the upper bound of where a clip
+    # can *start*, not where a clip can end.
+    policy: Literal["repeat_last", "wrap", "error"],
+) -> FrameBatch:
+
+    _validate_common_params(
+        decoder=decoder,
+        num_frames_per_clip=num_frames_per_clip,
+        policy=policy,
+    )
+    _validate_params_index_based(
+        num_clips=num_clips,
+        num_indices_between_frames=num_indices_between_frames,
+    )
+
+    sampling_range_start, sampling_range_end = _validate_sampling_range_index_based(
+        num_frames_per_clip=num_frames_per_clip,
+        num_indices_between_frames=num_indices_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        num_frames_in_video=len(decoder),
+    )
+
+    if kind == "random":
+        clip_start_indices = torch.randint(
+            low=sampling_range_start, high=sampling_range_end, size=(num_clips,)
+        )
+    else:
+        # Note [num clips larger than sampling range]
+        # If we ask for more clips than there are frames in the sampling range or
+        # in the video, we rely on torch.linspace behavior which will return
+        # duplicated indices.
+        # E.g. torch.linspace(0, 10, steps=20, dtype=torch.int) returns
+        # 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 10
+        # Alternatively we could wrap around, but the current behavior is closer to
+        # the expected "equally spaced indices" sampling.
+        clip_start_indices = torch.linspace(
+            sampling_range_start,
+            sampling_range_end - 1,
+            steps=num_clips,
+            dtype=torch.int,
+        )
+
+    all_clips_indices = _build_all_clips_indices(
+        clip_start_indices=clip_start_indices,
+        num_frames_per_clip=num_frames_per_clip,
+        num_indices_between_frames=num_indices_between_frames,
+        num_frames_in_video=len(decoder),
+        policy_fun=_POLICY_FUNCTIONS[policy],
+    )
+
+    frames = decoder.get_frames_at(indices=all_clips_indices)
+    return _reshape_4d_framebatch_into_5d(
+        frames=frames,
+        num_clips=num_clips,
+        num_frames_per_clip=num_frames_per_clip,
+    )
+
+
+def clips_at_random_indices(
+    decoder: VideoDecoder,
+    *,
+    num_clips: int = 1,
+    num_frames_per_clip: int = 1,
+    num_indices_between_frames: int = 1,
+    sampling_range_start: int = 0,
+    sampling_range_end: int | None = None,  # interval is [start, end).
+    policy: Literal["repeat_last", "wrap", "error"] = "repeat_last",
+) -> FrameBatch:
+    # See docstring below
+    torch._C._log_api_usage_once("torchcodec.samplers.clips_at_random_indices")
+    return _generic_index_based_sampler(
+        kind="random",
+        decoder=decoder,
+        num_clips=num_clips,
+        num_frames_per_clip=num_frames_per_clip,
+        num_indices_between_frames=num_indices_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        policy=policy,
+    )
+
+
+def clips_at_regular_indices(
+    decoder: VideoDecoder,
+    *,
+    num_clips: int = 1,
+    num_frames_per_clip: int = 1,
+    num_indices_between_frames: int = 1,
+    sampling_range_start: int = 0,
+    sampling_range_end: int | None = None,  # interval is [start, end).
+    policy: Literal["repeat_last", "wrap", "error"] = "repeat_last",
+) -> FrameBatch:
+    # See docstring below
+    torch._C._log_api_usage_once("torchcodec.samplers.clips_at_regular_indices")
+    return _generic_index_based_sampler(
+        kind="regular",
+        decoder=decoder,
+        num_clips=num_clips,
+        num_frames_per_clip=num_frames_per_clip,
+        num_indices_between_frames=num_indices_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        policy=policy,
+    )
+
+
+_COMMON_DOCS = f"""
+    Args:
+        decoder (VideoDecoder): The :class:`~torchcodec.decoders.VideoDecoder`
+            instance to sample clips from.
+        num_clips (int, optional): The number of clips to return. Default: 1.
+        num_frames_per_clip (int, optional): The number of frames per clips. Default: 1.
+        num_indices_between_frames(int, optional): The number of indices between
+            the frames *within* a clip. Default: 1, which means frames are
+            consecutive. This is sometimes refered-to as "dilation".
+        sampling_range_start (int, optional): The start of the sampling range,
+            which defines the first index that a clip may *start* at. Default:
+            0, i.e. the start of the video.
+        sampling_range_end (int or None, optional): The end of the sampling
+            range, which defines the last index that a clip may *start* at. This
+            value is exclusive, i.e. a clip may only start within
+            [``sampling_range_start``, ``sampling_range_end``). If None
+            (default), the value is set automatically such that the clips never
+            span beyond the end of the video. For example if the last valid
+            index in a video is 99 and the clips span 10 frames, this value is
+            set to 99 - 10 + 1 = 90. Negative values are accepted and are
+            equivalent to ``len(video) - val``. When a clip spans beyond the end
+            of the video, the ``policy`` parameter defines how to construct such
+            clip.
+        policy (str, optional): Defines how to construct clips that span beyond
+            the end of the video. This is best described with an example:
+            assuming the last valid index in a video is 99, and a clip was
+            sampled to start at index 95, with ``num_frames_per_clip=5`` and
+            ``num_indices_between_frames=2``, the indices of the frames in the
+            clip are supposed to be [95, 97, 99, 101, 103]. But 101 and 103 are
+            invalid indices, so the ``policy`` parameter defines how to replace
+            those frames, with valid indices:
+
+            - "repeat_last": repeats the last valid frame of the clip. We would
+              get [95, 97, 99, 99, 99].
+            - "wrap": wraps around to the beginning of the clip. We would get
+              [95, 97, 99, 95, 97].
+            - "error": raises an error.
+
+            Default is "repeat_last". Note that when ``sampling_range_end=None``
+            (default), this policy parameter is unlikely to be relevant.
+
+    {_FRAMEBATCH_RETURN_DOCS}
+"""
+
+clips_at_random_indices.__doc__ = f"""Sample :term:`clips` at random indices.
+{_COMMON_DOCS}
+"""
+
+
+clips_at_regular_indices.__doc__ = f"""Sample :term:`clips` at regular (equally-spaced) indices.
+{_COMMON_DOCS}
+"""

torchcodec/samplers/_time_based.py

@@ -0,0 +1,358 @@
+from typing import Literal
+
+import torch
+
+from torchcodec import FrameBatch
+from torchcodec.samplers._common import (
+    _FRAMEBATCH_RETURN_DOCS,
+    _POLICY_FUNCTION_TYPE,
+    _POLICY_FUNCTIONS,
+    _reshape_4d_framebatch_into_5d,
+    _validate_common_params,
+)
+
+
+def _validate_params_time_based(
+    *,
+    decoder,
+    num_clips,
+    seconds_between_clip_starts,
+    seconds_between_frames,
+):
+
+    if (num_clips is None and seconds_between_clip_starts is None) or (
+        num_clips is not None and seconds_between_clip_starts is not None
+    ):
+        raise ValueError("This is internal only and should never happen.")
+
+    if seconds_between_clip_starts is not None and seconds_between_clip_starts <= 0:
+        raise ValueError(
+            f"seconds_between_clip_starts ({seconds_between_clip_starts}) must be > 0"
+        )
+
+    if num_clips is not None and num_clips <= 0:
+        raise ValueError(f"num_clips ({num_clips}) must be > 0")
+
+    if decoder.metadata.average_fps is None:
+        raise ValueError(
+            "Could not infer average fps from video metadata. "
+            "Try using an index-based sampler instead."
+        )
+
+    # Note that metadata.begin_stream_seconds is a property that will always yield a valid
+    # value; if it is not present in the actual metadata, the metadata object will return 0.
+    # Hence, we do not test for it here and only test metadata.end_stream_seconds.
+    if decoder.metadata.end_stream_seconds is None:
+        raise ValueError(
+            "Could not infer stream end from video metadata. "
+            "Try using an index-based sampler instead."
+        )
+
+    average_frame_duration_seconds = 1 / decoder.metadata.average_fps
+    if seconds_between_frames is None:
+        seconds_between_frames = average_frame_duration_seconds
+    elif seconds_between_frames <= 0:
+        raise ValueError(
+            f"seconds_between_clip_starts ({seconds_between_clip_starts}) must be > 0, got"
+        )
+
+    return seconds_between_frames
+
+
+def _validate_sampling_range_time_based(
+    *,
+    num_frames_per_clip,
+    seconds_between_frames,
+    sampling_range_start,
+    sampling_range_end,
+    begin_stream_seconds,
+    end_stream_seconds,
+):
+
+    if sampling_range_start is None:
+        sampling_range_start = begin_stream_seconds
+    else:
+        if sampling_range_start < begin_stream_seconds:
+            raise ValueError(
+                f"sampling_range_start ({sampling_range_start}) must be at least {begin_stream_seconds}"
+            )
+        if sampling_range_start >= end_stream_seconds:
+            raise ValueError(
+                f"sampling_range_start ({sampling_range_start}) must be smaller than {end_stream_seconds}"
+            )
+
+    if sampling_range_end is None:
+        # We allow a clip to start anywhere within
+        # [sampling_range_start, sampling_range_end)
+        # When sampling_range_end is None, we want to automatically set it to
+        # the largest possible value such that the sampled frames in any clip
+        # are within the bounds of the video duration (in other words, we don't
+        # want to have to resort to the `policy`).
+        # I.e. we want to guarantee that for all frames in any clip we have
+        # pts < end_stream_seconds.
+        #
+        # The frames of a clip will be sampled at the following pts:
+        # clip_timestamps = [
+        #  clip_start + 0 * seconds_between_frames,
+        #  clip_start + 1 * seconds_between_frames,
+        #  clip_start + 2 * seconds_between_frames,
+        #  ...
+        #  clip_start + (num_frames_per_clip - 1) * seconds_between_frames,
+        # ]
+        # To guarantee that any such value is < end_stream_seconds, we only need
+        # to guarantee that
+        # clip_start < end_stream_seconds - (num_frames_per_clip - 1) * seconds_between_frames
+        #
+        # So that's the value of sampling_range_end we want to use.
+        sampling_range_end = (
+            end_stream_seconds - (num_frames_per_clip - 1) * seconds_between_frames
+        )
+    elif sampling_range_end <= begin_stream_seconds:
+        raise ValueError(
+            f"sampling_range_end ({sampling_range_end}) must be at least {begin_stream_seconds}"
+        )
+
+    if sampling_range_start >= sampling_range_end:
+        raise ValueError(
+            f"sampling_range_start ({sampling_range_start}) must be smaller than sampling_range_end ({sampling_range_end})"
+        )
+
+    sampling_range_end = min(sampling_range_end, end_stream_seconds)
+
+    return sampling_range_start, sampling_range_end
+
+
+def _build_all_clips_timestamps(
+    *,
+    clip_start_seconds: torch.Tensor,  # 1D float tensor
+    num_frames_per_clip: int,
+    seconds_between_frames: float,
+    end_stream_seconds: float,
+    policy_fun: _POLICY_FUNCTION_TYPE,
+) -> list[float]:
+
+    all_clips_timestamps: list[float] = []
+    for start_seconds in clip_start_seconds:
+        clip_timestamps = [
+            timestamp
+            for i in range(num_frames_per_clip)
+            if (timestamp := start_seconds + i * seconds_between_frames)
+            < end_stream_seconds
+        ]
+
+        if len(clip_timestamps) < num_frames_per_clip:
+            clip_timestamps = policy_fun(clip_timestamps, num_frames_per_clip)
+        all_clips_timestamps += clip_timestamps
+
+    return all_clips_timestamps
+
+
+def _generic_time_based_sampler(
+    kind: Literal["random", "regular"],
+    decoder,
+    *,
+    num_clips: int | None,  # mutually exclusive with seconds_between_clip_starts
+    seconds_between_clip_starts: float | None,
+    num_frames_per_clip: int,
+    seconds_between_frames: float | None,
+    # None means "begining", which may not always be 0
+    sampling_range_start: float | None,
+    sampling_range_end: float | None,  # interval is [start, end).
+    policy: Literal["repeat_last", "wrap", "error"] = "repeat_last",
+) -> FrameBatch:
+    # Note: *everywhere*, sampling_range_end denotes the upper bound of where a
+    # clip can start. This is an *open* upper bound, i.e. we will make sure no
+    # clip starts exactly at (or above) sampling_range_end.
+
+    _validate_common_params(
+        decoder=decoder,
+        num_frames_per_clip=num_frames_per_clip,
+        policy=policy,
+    )
+
+    seconds_between_frames = _validate_params_time_based(
+        decoder=decoder,
+        num_clips=num_clips,
+        seconds_between_clip_starts=seconds_between_clip_starts,
+        seconds_between_frames=seconds_between_frames,
+    )
+
+    sampling_range_start, sampling_range_end = _validate_sampling_range_time_based(
+        num_frames_per_clip=num_frames_per_clip,
+        seconds_between_frames=seconds_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        begin_stream_seconds=decoder.metadata.begin_stream_seconds,
+        end_stream_seconds=decoder.metadata.end_stream_seconds,
+    )
+
+    if kind == "random":
+        assert num_clips is not None  # appease type-checker
+        sampling_range_width = sampling_range_end - sampling_range_start
+        # torch.rand() returns in [0, 1)
+        # which ensures all clip starts are < sampling_range_end
+        clip_start_seconds = (
+            torch.rand(num_clips) * sampling_range_width + sampling_range_start
+        )
+    else:
+        assert seconds_between_clip_starts is not None  # appease type-checker
+        clip_start_seconds = torch.arange(
+            sampling_range_start,
+            sampling_range_end,  # excluded
+            seconds_between_clip_starts,
+        )
+        # As mentioned in the docs, torch.arange may return values
+        # equal to or above `end` because of floating precision errors.
+        # Here, we manually ensure all values are strictly lower than `sample_range_end`
+        if clip_start_seconds[-1] >= sampling_range_end:
+            clip_start_seconds = clip_start_seconds[
+                clip_start_seconds < sampling_range_end
+            ]
+
+        num_clips = len(clip_start_seconds)
+
+    all_clips_timestamps = _build_all_clips_timestamps(
+        clip_start_seconds=clip_start_seconds,
+        num_frames_per_clip=num_frames_per_clip,
+        seconds_between_frames=seconds_between_frames,
+        end_stream_seconds=decoder.metadata.end_stream_seconds,
+        policy_fun=_POLICY_FUNCTIONS[policy],
+    )
+
+    frames = decoder.get_frames_played_at(seconds=all_clips_timestamps)
+    return _reshape_4d_framebatch_into_5d(
+        frames=frames,
+        num_clips=num_clips,
+        num_frames_per_clip=num_frames_per_clip,
+    )
+
+
+def clips_at_random_timestamps(
+    decoder,
+    *,
+    num_clips: int = 1,
+    num_frames_per_clip: int = 1,
+    seconds_between_frames: float | None = None,
+    # None means "begining", which may not always be 0
+    sampling_range_start: float | None = None,
+    sampling_range_end: float | None = None,  # interval is [start, end).
+    policy: Literal["repeat_last", "wrap", "error"] = "repeat_last",
+) -> FrameBatch:
+    # See docstring below
+    torch._C._log_api_usage_once("torchcodec.samplers.clips_at_random_timestamps")
+    return _generic_time_based_sampler(
+        kind="random",
+        decoder=decoder,
+        num_clips=num_clips,
+        seconds_between_clip_starts=None,
+        num_frames_per_clip=num_frames_per_clip,
+        seconds_between_frames=seconds_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        policy=policy,
+    )
+
+
+def clips_at_regular_timestamps(
+    decoder,
+    *,
+    seconds_between_clip_starts: float,
+    num_frames_per_clip: int = 1,
+    seconds_between_frames: float | None = None,
+    # None means "begining", which may not always be 0
+    sampling_range_start: float | None = None,
+    sampling_range_end: float | None = None,  # interval is [start, end).
+    policy: Literal["repeat_last", "wrap", "error"] = "repeat_last",
+) -> FrameBatch:
+    # See docstring below
+    torch._C._log_api_usage_once("torchcodec.samplers.clips_at_regular_timestamps")
+    return _generic_time_based_sampler(
+        kind="regular",
+        decoder=decoder,
+        num_clips=None,
+        seconds_between_clip_starts=seconds_between_clip_starts,
+        num_frames_per_clip=num_frames_per_clip,
+        seconds_between_frames=seconds_between_frames,
+        sampling_range_start=sampling_range_start,
+        sampling_range_end=sampling_range_end,
+        policy=policy,
+    )
+
+
+_COMMON_DOCS = """
+    {maybe_note}
+
+    Args:
+        decoder (VideoDecoder): The :class:`~torchcodec.decoders.VideoDecoder`
+            instance to sample clips from.
+        {num_clips_or_seconds_between_clip_starts}
+        num_frames_per_clip (int, optional): The number of frames per clips. Default: 1.
+        seconds_between_frames (float or None, optional): The time (in seconds)
+            between each frame within a clip. More accurately, this defines the
+            time between the *frame sampling point*, i.e. the timestamps at
+            which we sample the frames. Because frames span intervals in time ,
+            the resulting start of frames within a clip may not be exactly
+            spaced by ``seconds_between_frames`` - but on average, they will be.
+            Default is None, which is set to the average frame duration
+            (``1/average_fps``).
+        sampling_range_start (float or None, optional): The start of the
+            sampling range, which defines the first timestamp (in seconds) that
+            a clip may *start* at. Default: None, which corresponds to the start
+            of the video. (Note: some videos start at negative values, which is
+            why the default is not 0).
+        sampling_range_end (float or None, optional): The end of the sampling
+            range, which defines the last timestamp (in seconds) that a clip may
+            *start* at. This value is exclusive, i.e. a clip may only start within
+            [``sampling_range_start``, ``sampling_range_end``). If None
+            (default), the value is set automatically such that the clips never
+            span beyond the end of the video, i.e. it is set to
+            ``end_video_seconds - (num_frames_per_clip - 1) *
+            seconds_between_frames``. When a clip spans beyond the end of the
+            video, the ``policy`` parameter defines how to construct such clip.
+        policy (str, optional): Defines how to construct clips that span beyond
+            the end of the video. This is best described with an example:
+            assuming the last valid (seekable) timestamp in a video is 10.9, and
+            a clip was sampled to start at timestamp 10.5, with
+            ``num_frames_per_clip=5`` and ``seconds_between_frames=0.2``, the
+            sampling timestamps of the frames in the clip are supposed to be
+            [10.5, 10.7, 10.9, 11.1, 11.2]. But 11.1 and 11.2 are invalid
+            timestamps, so the ``policy`` parameter defines how to replace those
+            frames, with valid sampling timestamps:
+
+            - "repeat_last": repeats the last valid frame of the clip. We would
+              get frames sampled at timestamps [10.5, 10.7, 10.9, 10.9, 10.9].
+            - "wrap": wraps around to the beginning of the clip. We would get
+              frames sampled at timestamps [10.5, 10.7, 10.9, 10.5, 10.7].
+            - "error": raises an error.
+
+            Default is "repeat_last". Note that when ``sampling_range_end=None``
+            (default), this policy parameter is unlikely to be relevant.
+
+    {return_docs}
+"""
+
+
+_NUM_CLIPS_DOCS = """
+        num_clips (int, optional): The number of clips to return. Default: 1.
+"""
+clips_at_random_timestamps.__doc__ = f"""Sample :term:`clips` at random timestamps.
+{_COMMON_DOCS.format(maybe_note="", num_clips_or_seconds_between_clip_starts=_NUM_CLIPS_DOCS, return_docs=_FRAMEBATCH_RETURN_DOCS)}
+"""
+
+
+_SECONDS_BETWEEN_CLIP_STARTS = """
+        seconds_between_clip_starts (float): The space (in seconds) between each
+            clip start.
+"""
+
+_NOTE_DOCS = """
+    .. note::
+        For consistency with existing sampling APIs (such as torchvision), this
+        sampler takes a ``seconds_between_clip_starts`` parameter instead of
+        ``num_clips``. If you find that supporting ``num_clips`` would be
+        useful, please let us know by `opening a feature request
+        <https://github.com/pytorch/torchcodec/issues?q=is:open+is:issue>`_.
+"""
+clips_at_regular_timestamps.__doc__ = f"""Sample :term:`clips` at regular (equally-spaced) timestamps.
+{_COMMON_DOCS.format(maybe_note=_NOTE_DOCS, num_clips_or_seconds_between_clip_starts=_SECONDS_BETWEEN_CLIP_STARTS, return_docs=_FRAMEBATCH_RETURN_DOCS)}
+"""