torchcodec 0.7.0__cp310-cp310-win_amd64.whl

torchcodec/_internally_replaced_utils.py

@@ -0,0 +1,67 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+import importlib
+import sys
+from pathlib import Path
+from types import ModuleType
+
+
+# Copy pasted from torchvision
+# https://github.com/pytorch/vision/blob/947ae1dc71867f28021d5bc0ff3a19c249236e2a/torchvision/_internally_replaced_utils.py#L25
+def _get_extension_path(lib_name: str) -> str:
+    extension_suffixes = []
+    if sys.platform == "linux":
+        extension_suffixes = importlib.machinery.EXTENSION_SUFFIXES
+    elif sys.platform == "darwin":
+        extension_suffixes = importlib.machinery.EXTENSION_SUFFIXES + [".dylib"]
+    elif sys.platform in ("win32", "cygwin"):
+        extension_suffixes = importlib.machinery.EXTENSION_SUFFIXES + [".dll", ".pyd"]
+    else:
+        raise NotImplementedError(f"{sys.platform = } is not not supported")
+    loader_details = (
+        importlib.machinery.ExtensionFileLoader,
+        extension_suffixes,
+    )
+
+    extfinder = importlib.machinery.FileFinder(
+        str(Path(__file__).parent), loader_details
+    )
+    ext_specs = extfinder.find_spec(lib_name)
+    if ext_specs is None:
+        raise ImportError(f"No spec found for {lib_name}")
+
+    if ext_specs.origin is None:
+        raise ImportError(f"Existing spec found for {lib_name} does not have an origin")
+
+    return ext_specs.origin
+
+
+def _load_pybind11_module(module_name: str, library_path: str) -> ModuleType:
+    spec = importlib.util.spec_from_file_location(
+        module_name,
+        library_path,
+    )
+    if spec is None or spec.loader is None:
+        raise ImportError(
+            f"Unable to load spec or spec.loader for module {module_name} from path {library_path}"
+        )
+
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    return mod
+
+
+# Note that the return value from this function must match the value used as
+# PYBIND_OPS_MODULE_NAME when we compile _core/pybind_ops.cpp. If the values
+# do not match, we will not be able to import the C++ shared library as a
+# Python module at runtime.
+#
+# The parameter ffmpeg_major_version is unused externally, but used
+# internally.
+def _get_pybind_ops_module_name(ffmpeg_major_version: int) -> str:
+    return "core_pybind_ops"

torchcodec/_samplers/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+from .video_clip_sampler import *  # noqa

torchcodec/_samplers/video_clip_sampler.py

@@ -0,0 +1,430 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+import abc
+import json
+import sys
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Tuple, Union
+
+import torch
+from torch import nn, Tensor
+
+from torchcodec._core import (
+    add_video_stream,
+    create_from_tensor,
+    get_frames_at_indices,
+    get_json_metadata,
+    get_next_frame,
+    scan_all_streams_to_update_metadata,
+    seek_to_pts,
+)
+
+
+class VideoTooShortException(Exception):
+    pass
+
+
+@dataclass
+class DecoderArgs:
+    num_threads: int = 0
+
+
+@dataclass
+class VideoArgs:
+    """
+    VideoArgs contains video related information. Video width/heigh can't be co-exist with video min/max dimension.
+    Args:
+        desired_width (`int`): Target width of the video
+        desired_height (`int`): Target height of the video
+        desired_max_dimension (`int`): Target maximum dimension of the video
+        desired_min_dimension (`int`): Target minimum dimension of the video
+    """
+
+    desired_width: int = 0
+    desired_height: int = 0
+    desired_max_dimension: int = 0
+    desired_min_dimension: int = 0
+
+
+@dataclass
+class SamplerArgs(abc.ABC):
+    """
+    Abstract class of sampler args, extended by TimeBasedSamplerArgs and IndexBasedSamplerArgs.
+    Frame refers to a video/audio frame, and clip is a list of frames which may be non-consecutive.
+    Args:
+        sampler_type (`str`): Sampler type, can be random, uniform, periodic, target
+        clips_per_video (`int`): Number of clips per video, this applys to random and uniform sampling
+        frames_per_clip (`int`): Number of frames per clip
+    """
+
+    sampler_type: str
+    clips_per_video: int
+    frames_per_clip: int
+
+
+@dataclass
+class TimeBasedSamplerArgs(SamplerArgs):
+    """
+    TimeBasedSamplerArgs inherits from SamplerArgs and describe the time based sampling behavior.
+    Args:
+        video_frame_dilation (`int`): Frame dilation of the video, if frame dilation is 2, we will sample every other frame within a clip.
+        sample_start_second (`float`): Start second of the sampler range, applies to all sampler types
+        sample_end_second (`float`): End second of the sampler range, applies to all sampler types
+        sample_per_second (`float`): Sample per second of the sampler range, applies to periodic sampling
+        target_sample_start_second (`float`): Start second of the target sampling range, applies to target sampling
+    """
+
+    video_frame_dilation: int = 1
+    sample_start_second: float = 0.0
+    sample_end_second: float = float("inf")
+    sample_per_second: float = 0.0
+    target_sample_start_second: List[float] = field(default_factory=lambda: [])
+
+
+@dataclass
+class IndexBasedSamplerArgs(SamplerArgs):
+    """
+    IndexBasedSamplerArgs inherits from SamplerArgs and describe the index based sampling behavior.
+    sample_start_index and sample_end_index together decide the range of the sampling.
+    sample_step decides step between each clip.
+    video_frame_dilation decides step between each frame within a clip.
+    Args:
+        video_frame_dilation (`int`): Frame dilation of the video, if frame dilation is 2, we will sample every other frame within a clip, applies to all sampler types
+        sample_start_index (`int`): Start index of the sampler range, applies to all sampler types
+        sample_end_index (`int`): End index of the sampler range, this is last possile frame you want to sample, applies to all sampler types
+        sample_step (`int`): Step of the sampler range, if step is 10, the interval between start frames of each clip will be 10, applies to periodic sampling only.
+    """
+
+    video_frame_dilation: int = 1
+    sample_start_index: int = 0
+    sample_end_index: int = sys.maxsize
+    sample_step: int = 1
+
+
+class VideoClipSampler(nn.Module):
+    """
+    VideoClipSampler will do video clip sampling with given video args and sampler args.
+    The video args contains video related information, frames_per_clip, dimensions etc.
+    The sampler args can be either time-based or index-based, it will be used to decide clip start time pts or index.
+    ClipSampling support, random, uniform, periodic, target, keyframe sampling etc.
+
+    Args:
+        video_args (`VideoArgs`): The video args
+        sampler_args (`SamplerArgs`): The sampler args. Can be TimeBasedSamplerArgs or IndexBasedSamplerArgs
+        decoder_args (`DecoderArgs`): Decoder args contain value needs for decoder, for example, thread count
+
+    Example:
+        >>> video_args = VideoArgs(desired_width=224, desired_height=224)
+        >>> time_based_sampler_args = TimeBasedSamplerArgs(sampler_type="random", clips_per_video=1, frames_per_clip=4)
+        >>> video_decoder_args = DecoderArgs(num_threads=1)
+        >>> video_clip_sampler = VideoClipSampler(video_args, time_based_sampler_args, decoder_args)
+        >>> clips = video_clip_sampler(video_data)
+        clips now contains a list of clip, where clip is a list of frame tensors, each tensor represents a frame image.
+    """
+
+    def __init__(
+        self,
+        video_args: VideoArgs,
+        sampler_args: SamplerArgs,
+        decoder_args: Union[None, DecoderArgs] = None,
+    ) -> None:
+        super().__init__()
+        self.video_args = video_args
+        self.sampler_args = sampler_args
+        self.decoder_args = DecoderArgs() if decoder_args is None else decoder_args
+
+    def forward(self, video_data: Tensor) -> Union[List[Any]]:
+        """Sample video clips from the video data
+
+        Args:
+            video_data (`Tensor`): The video data
+
+        Return
+            clips (` List[List[Tensor]]`): List of clips, where each clip is a list of Tensors, each tensor represents a frame image.
+
+        """
+
+        video_decoder = create_from_tensor(video_data)
+        scan_all_streams_to_update_metadata(video_decoder)
+        add_video_stream(video_decoder)
+        metadata_json = json.loads(get_json_metadata(video_decoder))
+        target_width, target_height = self._compute_frame_width_height(
+            metadata_json["width"], metadata_json["height"]
+        )
+
+        video_decoder = create_from_tensor(video_data)
+        scan_all_streams_to_update_metadata(video_decoder)
+        add_video_stream(
+            video_decoder,
+            width=target_width,
+            height=target_height,
+            num_threads=self.decoder_args.num_threads,
+        )
+
+        clips: List[Any] = []
+        # Cast sampler args to be time based or index based
+        if isinstance(self.sampler_args, TimeBasedSamplerArgs):
+            time_based_sampler_args = self.sampler_args
+            clip_starts_in_seconds = self._get_start_seconds(
+                metadata_json, time_based_sampler_args
+            )
+            for start_ts in clip_starts_in_seconds:
+                clip = self._get_clip_with_start_second(
+                    start_ts,
+                    video_decoder,
+                    time_based_sampler_args.video_frame_dilation,
+                )
+                clips.append(clip)
+        elif isinstance(self.sampler_args, IndexBasedSamplerArgs):
+            index_based_sampler_args = self.sampler_args
+            clips = self._get_clips_for_index_based_sampling(
+                video_decoder,
+                index_based_sampler_args,
+                metadata_json,
+            )
+
+        return clips
+
+    def _get_clips_for_index_based_sampling(
+        self,
+        video_decoder: Tensor,
+        index_based_sampler_args: IndexBasedSamplerArgs,
+        metadata_json: Dict[str, Any],
+    ) -> List[Tensor]:
+        """Get clips for index based sampling, the sampling is done in 3 steps:
+            1. Compute clip_start_idxs based on the sampler type and the sampler args;
+            2. For each clip, given clip_start_idx, video_frame_dilation, frames_per_clip, get indexes for all frames
+            3. With given index, fetch the frame and group into clip and then clips
+
+        Args:
+            video_decoder (`Tensor`): The video decoder
+            index_based_sampler_args (`IndexBasedSamplerArgs`): The index based sampler args
+            metadata_json (`Dict[str, Any]`): The metadata of the video in json format
+
+        Returns:
+            clips (` List[Tensor]`): List of clips, where each clip is a Tensor represents list of frames, Tensor shape default is NCHW.
+        """
+
+        sample_start_index = max(0, index_based_sampler_args.sample_start_index)
+        sample_end_index = (
+            min(
+                index_based_sampler_args.sample_end_index + 1,
+                metadata_json["numFramesFromHeader"],
+            )
+            - index_based_sampler_args.video_frame_dilation
+            * index_based_sampler_args.frames_per_clip
+        )
+        sampler_type = index_based_sampler_args.sampler_type
+
+        if sampler_type == "random":
+            clip_start_idxs = torch.randint(
+                sample_start_index,
+                sample_end_index,
+                (index_based_sampler_args.clips_per_video,),
+            )
+        elif sampler_type == "uniform":
+            clip_start_idxs = torch.linspace(
+                sample_start_index,
+                sample_end_index,
+                index_based_sampler_args.clips_per_video,
+                dtype=torch.int32,
+            )
+
+        clips = []
+        for clip_start_idx in clip_start_idxs:
+            batch_indexes = [
+                clip_start_idx + i * index_based_sampler_args.video_frame_dilation
+                for i in range(index_based_sampler_args.frames_per_clip)
+            ]
+            frames, *_ = get_frames_at_indices(
+                video_decoder,
+                frame_indices=batch_indexes,
+            )
+            clips.append(frames)
+
+        return clips
+
+    def _get_start_seconds(
+        self,
+        metadata_json: Dict[str, Any],
+        time_based_sampler_args: TimeBasedSamplerArgs,
+    ) -> List[float]:
+        """Get start seconds for each clip.
+        Given different sampler type, the API returns different clip start seconds.
+
+        Args:
+            metadata_json (`Dict[str, Any]`): The metadata of the video in json format
+            time_based_sampler_args: (`TimeBasedSamplerArgs`): The time based sampler args
+
+        Returns:
+            (`List[float]`): List of the sampled clip start position in seconds
+        """
+        video_duration_in_seconds = metadata_json["durationSecondsFromHeader"]
+
+        clip_duration_in_seconds = (
+            time_based_sampler_args.frames_per_clip
+            * time_based_sampler_args.video_frame_dilation
+            + 1
+        ) / metadata_json["averageFpsFromHeader"]
+
+        beginStreamSecondsFromContent = (
+            metadata_json["beginStreamSecondsFromContent"]
+            if metadata_json["beginStreamSecondsFromContent"]
+            else 0
+        )
+        endStreamSecondsFromContent = (
+            metadata_json["endStreamSecondsFromContent"]
+            if metadata_json["endStreamSecondsFromContent"] > 0
+            else video_duration_in_seconds
+        )
+        last_possible_clip_start_in_seconds = (
+            endStreamSecondsFromContent - clip_duration_in_seconds
+        )
+        if last_possible_clip_start_in_seconds < 0:
+            raise VideoTooShortException(
+                "Cannot get clips because video duration is shorter than the clip duration!"
+            )
+        sampler_type = time_based_sampler_args.sampler_type
+        clip_starts_in_seconds: List[float] = []
+        sample_start_second = max(
+            time_based_sampler_args.sample_start_second,
+            beginStreamSecondsFromContent,
+        )
+        sample_end_second = min(
+            last_possible_clip_start_in_seconds,
+            time_based_sampler_args.sample_end_second,
+        )
+        if sampler_type == "random":
+            clip_starts_in_seconds = (
+                torch.rand(time_based_sampler_args.clips_per_video)
+                * (sample_end_second - sample_start_second)
+                + sample_start_second
+            ).tolist()
+            clip_starts_in_seconds.sort()
+        elif sampler_type == "uniform":
+            clip_starts_in_seconds = torch.linspace(
+                sample_start_second,
+                sample_end_second,
+                time_based_sampler_args.clips_per_video,
+            ).tolist()
+        else:
+            raise NotImplementedError
+
+        return clip_starts_in_seconds
+
+    def _get_clip_with_start_second(
+        self, start_second: float, video_decoder: Tensor, video_frame_dilation: int
+    ) -> List[Tensor]:
+        """Get clip with start second.
+
+        Args:
+            `start_second` (`float`): The start second of the clip
+            `video_decoder` (`Tensor`): The video decoder
+            `video_frame_dilation` (`int`): The video frame dilation, by default it's 1.
+
+        Returns:
+            `clip` (`List[Tensor]`): clip is list of frame tensor. Dimension of each frame tensor is user specified, by default it's HWC.
+        """
+        seek_to_pts(video_decoder, start_second)
+        frames_needed_per_clip = (
+            self.sampler_args.frames_per_clip - 1
+        ) * video_frame_dilation + 1
+        clip = []
+        for _ in range(frames_needed_per_clip):
+            frame, _, _ = get_next_frame(video_decoder)
+            clip.append(frame)
+
+        # slice the list of tensor with frame_dilation and stack to tensor
+        clip = clip[::video_frame_dilation]
+        return clip
+
+    def _compute_frame_width_height(
+        self, ori_width: int, ori_height: int
+    ) -> Tuple[int, int]:
+        """Compute output frame width and height
+        desired_width, desired_height, desired_min_dimension, desired_max_dimension, (`int`): Together decide the size of the decoded video clips. (Default: `0`).
+                Note that the desired_width/desired_height parameters are mutually exclusive with desired_min_dimension/desired_max_dimension parameters.
+                - When desired_width = 0, desired_height = 0, desired_min_dimension = 0,
+                    and desired_max_dimension = 0, keep the original frame resolution
+                - When desired_width = 0, desired_height != 0, desired_min_dimension = 0,
+                    and desired_max_dimension = 0, keep the aspect ratio and resize
+                    the frame so that frame target_height is $desired_height
+                - When desired_width != 0, desired_height == 0, desired_min_dimension = 0,
+                    and desired_max_dimension = 0, keep the aspect ratio and resize
+                    the frame so that frame target_width is $desired_width
+                - When desired_width != 0, desired_height != 0, video_min_dimension = 0,
+                    and desired_max_dimension = 0, resize the frame so that frame
+                    target_width and target_height are set to $desired_width and
+                    $desired_height, respectively
+                - When desired_width = 0, desired_height = 0, desired_min_dimension != 0,
+                    and desired_max_dimension = 0, keep the aspect ratio and resize the
+                    frame so that shorter edge size is desired_min_dimension
+                - When desired_width = 0, desired_height = 0, desired_min_dimension = 0,
+                    and desired_max_dimension != 0, keep the aspect ratio and resize
+                    the frame so that longer edge size is desired_max_dimension
+                - When desired_width = 0, desired_height = 0, desired_min_dimension != 0,
+                    and desired_max_dimension != 0, resize the frame so that shorter
+                    edge size is desired_min_dimension, and longer edge size is
+                    desired_max_dimension. The aspect ratio may not be preserved
+
+        Args:
+            ori_width (`int`): Original width of the video
+            ori_height (`int`): Original height of the video
+
+        Returns:
+            (`Tuple[int, int]`): output frame width and height
+        """
+        width_height_ratio = ori_width / ori_height
+        height_width_ratio = ori_height / ori_width
+
+        target_width, target_height = ori_width, ori_height
+
+        # video_height and/or video_width is non zero
+        if self.video_args.desired_width == 0 and self.video_args.desired_height != 0:
+            target_height = self.video_args.desired_height
+            target_width = int(width_height_ratio * target_height)
+        elif self.video_args.desired_width != 0 and self.video_args.desired_height == 0:
+            target_width = self.video_args.desired_width
+            target_height = int(height_width_ratio * target_width)
+        elif self.video_args.desired_width != 0 and self.video_args.desired_height != 0:
+            target_width, target_height = (
+                self.video_args.desired_width,
+                self.video_args.desired_height,
+            )
+        # video_min_dimension and/or video_max_dimension is non zero
+        elif (
+            self.video_args.desired_min_dimension != 0
+            and self.video_args.desired_max_dimension == 0
+        ):
+            if ori_width > ori_height:
+                target_height = self.video_args.desired_min_dimension
+                target_width = int(width_height_ratio * target_height)
+            else:
+                target_width = self.video_args.desired_min_dimension
+                target_height = int(height_width_ratio * target_width)
+        elif (
+            self.video_args.desired_min_dimension == 0
+            and self.video_args.desired_max_dimension != 0
+        ):
+            if ori_width > ori_height:
+                target_width = self.video_args.desired_max_dimension
+                target_height = int(height_width_ratio * target_width)
+            else:
+                target_height = self.video_args.desired_max_dimension
+                target_width = int(width_height_ratio * target_height)
+        elif (
+            self.video_args.desired_min_dimension != 0
+            and self.video_args.desired_max_dimension != 0
+        ):
+            if ori_width > ori_height:
+                target_width = self.video_args.desired_max_dimension
+                target_height = self.video_args.desired_min_dimension
+            else:
+                target_height = self.video_args.desired_max_dimension
+                target_width = self.video_args.desired_min_dimension
+
+        return target_width, target_height

torchcodec/decoders/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+from .._core import AudioStreamMetadata, VideoStreamMetadata
+from ._audio_decoder import AudioDecoder  # noqa
+from ._video_decoder import VideoDecoder  # noqa
+
+SimpleVideoDecoder = VideoDecoder

torchcodec/decoders/_audio_decoder.py

@@ -0,0 +1,177 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+import io
+from pathlib import Path
+from typing import Optional, Union
+
+import torch
+from torch import Tensor
+
+from torchcodec import _core as core, AudioSamples
+from torchcodec.decoders._decoder_utils import (
+    create_decoder,
+    ERROR_REPORTING_INSTRUCTIONS,
+)
+
+
+class AudioDecoder:
+    """A single-stream audio decoder.
+
+    This can be used to decode audio from pure audio files (e.g. mp3, wav,
+    etc.), or from videos that contain audio streams (e.g. mp4 videos).
+
+    Returned samples are float samples normalized in [-1, 1]
+
+    Args:
+        source (str, ``Pathlib.path``, bytes, ``torch.Tensor`` or file-like
+            object): The source of the video or audio:
+
+            - If ``str``: a local path or a URL to a video or audio file.
+            - If ``Pathlib.path``: a path to a local video or audio file.
+            - If ``bytes`` object or ``torch.Tensor``: the raw encoded audio data.
+            - If file-like object: we read video data from the object on demand. The object must
+              expose the methods `read(self, size: int) -> bytes` and
+              `seek(self, offset: int, whence: int) -> int`. Read more in:
+              :ref:`sphx_glr_generated_examples_decoding_file_like.py`.
+        stream_index (int, optional): Specifies which stream in the file to decode samples from.
+            Note that this index is absolute across all media types. If left unspecified, then
+            the :term:`best stream` is used.
+        sample_rate (int, optional): The desired output sample rate of the decoded samples.
+            By default, the sample rate of the source is used.
+        num_channels (int, optional): The desired number of channels of the decoded samples.
+            By default, the number of channels of the source is used.
+
+    Attributes:
+        metadata (AudioStreamMetadata): Metadata of the audio stream.
+        stream_index (int): The stream index that this decoder is retrieving samples from. If a
+            stream index was provided at initialization, this is the same value. If it was left
+            unspecified, this is the :term:`best stream`.
+    """
+
+    def __init__(
+        self,
+        source: Union[str, Path, io.RawIOBase, io.BufferedReader, bytes, Tensor],
+        *,
+        stream_index: Optional[int] = None,
+        sample_rate: Optional[int] = None,
+        num_channels: Optional[int] = None,
+    ):
+        torch._C._log_api_usage_once("torchcodec.decoders.AudioDecoder")
+        self._decoder = create_decoder(source=source, seek_mode="approximate")
+
+        core.add_audio_stream(
+            self._decoder,
+            stream_index=stream_index,
+            sample_rate=sample_rate,
+            num_channels=num_channels,
+        )
+
+        container_metadata = core.get_container_metadata(self._decoder)
+        self.stream_index = (
+            container_metadata.best_audio_stream_index
+            if stream_index is None
+            else stream_index
+        )
+        if self.stream_index is None:
+            raise ValueError(
+                "The best audio stream is unknown and there is no specified stream. "
+                + ERROR_REPORTING_INSTRUCTIONS
+            )
+        self.metadata = container_metadata.streams[self.stream_index]
+        assert isinstance(self.metadata, core.AudioStreamMetadata)  # mypy
+
+        self._desired_sample_rate = (
+            sample_rate if sample_rate is not None else self.metadata.sample_rate
+        )
+
+    def get_all_samples(self) -> AudioSamples:
+        """Returns all the audio samples from the source.
+
+        To decode samples in a specific range, use
+        :meth:`~torchcodec.decoders.AudioDecoder.get_samples_played_in_range`.
+
+        Returns:
+            AudioSamples: The samples within the file.
+        """
+        return self.get_samples_played_in_range()
+
+    def get_samples_played_in_range(
+        self, start_seconds: float = 0.0, stop_seconds: Optional[float] = None
+    ) -> AudioSamples:
+        """Returns audio samples in the given range.
+
+        Samples are in the half open range [start_seconds, stop_seconds).
+
+        To decode all the samples from beginning to end, you can call this
+        method while leaving ``start_seconds`` and ``stop_seconds`` to their
+        default values, or use
+        :meth:`~torchcodec.decoders.AudioDecoder.get_all_samples` as a more
+        convenient alias.
+
+        Args:
+            start_seconds (float): Time, in seconds, of the start of the
+                range. Default: 0.
+            stop_seconds (float or None): Time, in seconds, of the end of the
+                range. As a half open range, the end is excluded. Default: None,
+                which decodes samples until the end.
+
+        Returns:
+            AudioSamples: The samples within the specified range.
+        """
+        if stop_seconds is not None and not start_seconds <= stop_seconds:
+            raise ValueError(
+                f"Invalid start seconds: {start_seconds}. It must be less than or equal to stop seconds ({stop_seconds})."
+            )
+        frames, first_pts = core.get_frames_by_pts_in_range_audio(
+            self._decoder,
+            start_seconds=start_seconds,
+            stop_seconds=stop_seconds,
+        )
+        first_pts = first_pts.item()
+
+        # x = frame boundaries
+        #
+        #            first_pts                                    last_pts
+        #                v                                            v
+        # ....x..........x..........x...........x..........x..........x.....
+        #                    ^                                 ^
+        #               start_seconds                      stop_seconds
+        #
+        # We want to return the samples in [start_seconds, stop_seconds). But
+        # because the core API is based on frames, the `frames` tensor contains
+        # the samples in [first_pts, last_pts)
+        # So we do some basic math to figure out the position of the view that
+        # we'll return.
+
+        sample_rate = self._desired_sample_rate
+        # TODO: metadata's sample_rate should probably not be Optional
+        assert sample_rate is not None  # mypy.
+
+        if first_pts < start_seconds:
+            offset_beginning = round((start_seconds - first_pts) * sample_rate)
+            output_pts_seconds = start_seconds
+        else:
+            # In normal cases we'll have first_pts <= start_pts, but in some
+            # edge cases it's possible to have first_pts > start_seconds,
+            # typically if the stream's first frame's pts isn't exactly 0.
+            offset_beginning = 0
+            output_pts_seconds = first_pts
+
+        num_samples = frames.shape[1]
+        last_pts = first_pts + num_samples / sample_rate
+        if stop_seconds is not None and stop_seconds < last_pts:
+            offset_end = num_samples - round((last_pts - stop_seconds) * sample_rate)
+        else:
+            offset_end = num_samples
+
+        data = frames[:, offset_beginning:offset_end]
+        return AudioSamples(
+            data=data,
+            pts_seconds=output_pts_seconds,
+            duration_seconds=data.shape[1] / sample_rate,
+            sample_rate=sample_rate,
+        )