torchcodec 0.8.0__cp313-cp313-macosx_12_0_arm64.whl

torchcodec/_core/ops.py

@@ -0,0 +1,498 @@
+# 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
+import json
+import warnings
+from types import ModuleType
+from typing import List, Optional, Tuple, Union
+
+import torch
+from torch.library import get_ctx, register_fake
+
+from torchcodec._internally_replaced_utils import (  # @manual=//pytorch/torchcodec/src:internally_replaced_utils
+    _get_extension_path,
+    _get_pybind_ops_module_name,
+    _load_pybind11_module,
+)
+
+_pybind_ops: Optional[ModuleType] = None
+
+
+def load_torchcodec_shared_libraries():
+    # Successively try to load the shared libraries for each version of FFmpeg
+    # that we support. We always start with the highest version, working our way
+    # down to the lowest version. Once we can load ALL shared libraries for a
+    # version of FFmpeg, we have succeeded and we stop.
+    #
+    # Note that we use two different methods for loading shared libraries:
+    #
+    #   1. torch.ops.load_library(): For PyTorch custom ops and the C++ only
+    #      libraries the custom ops depend on. Loading libraries through PyTorch
+    #      registers the custom ops with PyTorch's runtime and the ops can be
+    #      accessed through torch.ops after loading.
+    #
+    #   2. importlib: For pybind11 modules. We load them dynamically, rather
+    #      than using a plain import statement. A plain import statement only
+    #      works when the module name and file name match exactly. Our shared
+    #      libraries do not meet those conditions.
+
+    exceptions = []
+    for ffmpeg_major_version in (8, 7, 6, 5, 4):
+        pybind_ops_module_name = _get_pybind_ops_module_name(ffmpeg_major_version)
+        decoder_library_name = f"libtorchcodec_core{ffmpeg_major_version}"
+        custom_ops_library_name = f"libtorchcodec_custom_ops{ffmpeg_major_version}"
+        pybind_ops_library_name = f"libtorchcodec_pybind_ops{ffmpeg_major_version}"
+        try:
+            torch.ops.load_library(_get_extension_path(decoder_library_name))
+            torch.ops.load_library(_get_extension_path(custom_ops_library_name))
+
+            pybind_ops_library_path = _get_extension_path(pybind_ops_library_name)
+            global _pybind_ops
+            _pybind_ops = _load_pybind11_module(
+                pybind_ops_module_name, pybind_ops_library_path
+            )
+            return
+        except Exception as e:
+            # TODO: recording and reporting exceptions this way is OK for now as  it's just for debugging,
+            # but we should probably handle that via a proper logging mechanism.
+            exceptions.append((ffmpeg_major_version, e))
+
+    traceback = (
+        "\n[start of libtorchcodec loading traceback]\n"
+        + "\n".join(f"FFmpeg version {v}: {str(e)}" for v, e in exceptions)
+        + "\n[end of libtorchcodec loading traceback]."
+    )
+    raise RuntimeError(
+        f"""Could not load libtorchcodec. Likely causes:
+          1. FFmpeg is not properly installed in your environment. We support
+             versions 4, 5, 6 and 7.
+          2. The PyTorch version ({torch.__version__}) is not compatible with
+             this version of TorchCodec. Refer to the version compatibility
+             table:
+             https://github.com/pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec.
+          3. Another runtime dependency; see exceptions below.
+        The following exceptions were raised as we tried to load libtorchcodec:
+        """
+        f"{traceback}"
+    )
+
+
+load_torchcodec_shared_libraries()
+
+
+# Note: We use disallow_in_graph because PyTorch does constant propagation of
+# factory functions.
+create_from_file = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns.create_from_file.default
+)
+encode_audio_to_file = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns.encode_audio_to_file.default
+)
+encode_video_to_file = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns.encode_video_to_file.default
+)
+encode_audio_to_tensor = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns.encode_audio_to_tensor.default
+)
+_encode_audio_to_file_like = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns._encode_audio_to_file_like.default
+)
+create_from_tensor = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns.create_from_tensor.default
+)
+_create_from_file_like = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns._create_from_file_like.default
+)
+add_video_stream = torch.ops.torchcodec_ns.add_video_stream.default
+_add_video_stream = torch.ops.torchcodec_ns._add_video_stream.default
+add_audio_stream = torch.ops.torchcodec_ns.add_audio_stream.default
+seek_to_pts = torch.ops.torchcodec_ns.seek_to_pts.default
+get_next_frame = torch.ops.torchcodec_ns.get_next_frame.default
+get_frame_at_pts = torch.ops.torchcodec_ns.get_frame_at_pts.default
+get_frame_at_index = torch.ops.torchcodec_ns.get_frame_at_index.default
+_get_frames_at_indices_tensor_input = (
+    torch.ops.torchcodec_ns.get_frames_at_indices.default
+)
+_get_frames_by_pts_tensor_input = torch.ops.torchcodec_ns.get_frames_by_pts.default
+get_frames_in_range = torch.ops.torchcodec_ns.get_frames_in_range.default
+get_frames_by_pts_in_range = torch.ops.torchcodec_ns.get_frames_by_pts_in_range.default
+get_frames_by_pts_in_range_audio = (
+    torch.ops.torchcodec_ns.get_frames_by_pts_in_range_audio.default
+)
+get_json_metadata = torch.ops.torchcodec_ns.get_json_metadata.default
+_test_frame_pts_equality = torch.ops.torchcodec_ns._test_frame_pts_equality.default
+_get_container_json_metadata = (
+    torch.ops.torchcodec_ns.get_container_json_metadata.default
+)
+_get_key_frame_indices = torch.ops.torchcodec_ns._get_key_frame_indices.default
+scan_all_streams_to_update_metadata = (
+    torch.ops.torchcodec_ns.scan_all_streams_to_update_metadata.default
+)
+_get_stream_json_metadata = torch.ops.torchcodec_ns.get_stream_json_metadata.default
+_get_json_ffmpeg_library_versions = (
+    torch.ops.torchcodec_ns._get_json_ffmpeg_library_versions.default
+)
+
+
+# =============================
+# Functions not related to custom ops, but similar implementation to c++ ops
+# =============================
+def create_from_bytes(
+    video_bytes: bytes, seek_mode: Optional[str] = None
+) -> torch.Tensor:
+    with warnings.catch_warnings():
+        # Ignore warning stating that the underlying video_bytes buffer is
+        # non-writable.
+        warnings.filterwarnings("ignore", category=UserWarning)
+        buffer = torch.frombuffer(video_bytes, dtype=torch.uint8)
+    return create_from_tensor(buffer, seek_mode)
+
+
+def create_from_file_like(
+    file_like: Union[io.RawIOBase, io.BufferedReader], seek_mode: Optional[str] = None
+) -> torch.Tensor:
+    assert _pybind_ops is not None
+    return _create_from_file_like(
+        _pybind_ops.create_file_like_context(
+            file_like, False  # False means not for writing
+        ),
+        seek_mode,
+    )
+
+
+def encode_audio_to_file_like(
+    samples: torch.Tensor,
+    sample_rate: int,
+    format: str,
+    file_like: Union[io.RawIOBase, io.BufferedIOBase],
+    bit_rate: Optional[int] = None,
+    num_channels: Optional[int] = None,
+    desired_sample_rate: Optional[int] = None,
+) -> None:
+    """Encode audio samples to a file-like object.
+
+    Args:
+        samples: Audio samples tensor
+        sample_rate: Sample rate in Hz
+        format: Audio format (e.g., "wav", "mp3", "flac")
+        file_like: File-like object that supports write() and seek() methods
+        bit_rate: Optional bit rate for encoding
+        num_channels: Optional number of output channels
+        desired_sample_rate: Optional desired sample rate for the output.
+    """
+    assert _pybind_ops is not None
+
+    if samples.dtype != torch.float32:
+        raise ValueError(f"samples must have dtype torch.float32, got {samples.dtype}")
+
+    _encode_audio_to_file_like(
+        samples,
+        sample_rate,
+        format,
+        _pybind_ops.create_file_like_context(file_like, True),  # True means for writing
+        bit_rate,
+        num_channels,
+        desired_sample_rate,
+    )
+
+
+def get_frames_at_indices(
+    decoder: torch.Tensor, *, frame_indices: Union[torch.Tensor, list[int]]
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    if isinstance(frame_indices, torch.Tensor):
+        # Ensure indices is the correct dtype (int64)
+        frame_indices = frame_indices.to(torch.int64)
+    else:
+        # Convert list to tensor for dispatch
+        frame_indices = torch.tensor(frame_indices)
+    return _get_frames_at_indices_tensor_input(decoder, frame_indices=frame_indices)
+
+
+def get_frames_by_pts(
+    decoder: torch.Tensor, *, timestamps: Union[torch.Tensor, list[float]]
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    if isinstance(timestamps, torch.Tensor):
+        # Ensure indices is the correct dtype (float64)
+        timestamps = timestamps.to(torch.float64)
+    else:
+        # Convert list to tensor for dispatch
+        try:
+            timestamps = torch.tensor(timestamps, dtype=torch.float64)
+        except Exception as e:
+            raise ValueError("Couldn't convert timestamps input to a tensor") from e
+    return _get_frames_by_pts_tensor_input(decoder, timestamps=timestamps)
+
+
+# ==============================
+# Abstract impl for the operators. Needed by torch.compile.
+# ==============================
+@register_fake("torchcodec_ns::create_from_file")
+def create_from_file_abstract(filename: str, seek_mode: Optional[str]) -> torch.Tensor:
+    return torch.empty([], dtype=torch.long)
+
+
+@register_fake("torchcodec_ns::_create_from_file_like")
+def _create_from_file_like_abstract(
+    file_like: int, seek_mode: Optional[str]
+) -> torch.Tensor:
+    return torch.empty([], dtype=torch.long)
+
+
+@register_fake("torchcodec_ns::encode_audio_to_file")
+def encode_audio_to_file_abstract(
+    samples: torch.Tensor,
+    sample_rate: int,
+    filename: str,
+    bit_rate: Optional[int] = None,
+    num_channels: Optional[int] = None,
+    desired_sample_rate: Optional[int] = None,
+) -> None:
+    return
+
+
+@register_fake("torchcodec_ns::encode_video_to_file")
+def encode_video_to_file_abstract(
+    frames: torch.Tensor,
+    frame_rate: int,
+    filename: str,
+    crf: Optional[int] = None,
+) -> None:
+    return
+
+
+@register_fake("torchcodec_ns::encode_audio_to_tensor")
+def encode_audio_to_tensor_abstract(
+    samples: torch.Tensor,
+    sample_rate: int,
+    format: str,
+    bit_rate: Optional[int] = None,
+    num_channels: Optional[int] = None,
+    desired_sample_rate: Optional[int] = None,
+) -> torch.Tensor:
+    return torch.empty([], dtype=torch.long)
+
+
+@register_fake("torchcodec_ns::_encode_audio_to_file_like")
+def _encode_audio_to_file_like_abstract(
+    samples: torch.Tensor,
+    sample_rate: int,
+    format: str,
+    file_like_context: int,
+    bit_rate: Optional[int] = None,
+    num_channels: Optional[int] = None,
+    desired_sample_rate: Optional[int] = None,
+) -> None:
+    return
+
+
+@register_fake("torchcodec_ns::create_from_tensor")
+def create_from_tensor_abstract(
+    video_tensor: torch.Tensor, seek_mode: Optional[str]
+) -> torch.Tensor:
+    return torch.empty([], dtype=torch.long)
+
+
+@register_fake("torchcodec_ns::_add_video_stream")
+def _add_video_stream_abstract(
+    decoder: torch.Tensor,
+    *,
+    num_threads: Optional[int] = None,
+    dimension_order: Optional[str] = None,
+    stream_index: Optional[int] = None,
+    device: str = "cpu",
+    device_variant: str = "default",
+    transform_specs: str = "",
+    custom_frame_mappings: Optional[
+        tuple[torch.Tensor, torch.Tensor, torch.Tensor]
+    ] = None,
+    color_conversion_library: Optional[str] = None,
+) -> None:
+    return
+
+
+@register_fake("torchcodec_ns::add_video_stream")
+def add_video_stream_abstract(
+    decoder: torch.Tensor,
+    *,
+    num_threads: Optional[int] = None,
+    dimension_order: Optional[str] = None,
+    stream_index: Optional[int] = None,
+    device: str = "cpu",
+    device_variant: str = "default",
+    transform_specs: str = "",
+    custom_frame_mappings: Optional[
+        tuple[torch.Tensor, torch.Tensor, torch.Tensor]
+    ] = None,
+) -> None:
+    return
+
+
+@register_fake("torchcodec_ns::add_audio_stream")
+def add_audio_stream_abstract(
+    decoder: torch.Tensor,
+    *,
+    stream_index: Optional[int] = None,
+    sample_rate: Optional[int] = None,
+    num_channels: Optional[int] = None,
+) -> None:
+    return
+
+
+@register_fake("torchcodec_ns::seek_to_pts")
+def seek_abstract(decoder: torch.Tensor, seconds: float) -> None:
+    return
+
+
+@register_fake("torchcodec_ns::get_next_frame")
+def get_next_frame_abstract(
+    decoder: torch.Tensor,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    # Images are 3 dimensions: height, width, channels.
+    # The exact permutation depends on the constructor options passed in.
+    image_size = [get_ctx().new_dynamic_size() for _ in range(3)]
+    return (
+        torch.empty(image_size),
+        torch.empty([], dtype=torch.float),
+        torch.empty([], dtype=torch.float),
+    )
+
+
+@register_fake("torchcodec_ns::get_frame_at_pts")
+def get_frame_at_pts_abstract(
+    decoder: torch.Tensor, seconds: float
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    image_size = [get_ctx().new_dynamic_size() for _ in range(3)]
+    return (
+        torch.empty(image_size),
+        torch.empty([], dtype=torch.float),
+        torch.empty([], dtype=torch.float),
+    )
+
+
+@register_fake("torchcodec_ns::get_frames_by_pts")
+def get_frames_by_pts_abstract(
+    decoder: torch.Tensor,
+    *,
+    timestamps: Union[torch.Tensor, List[float]],
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    image_size = [get_ctx().new_dynamic_size() for _ in range(4)]
+    return (
+        torch.empty(image_size),
+        torch.empty([], dtype=torch.float),
+        torch.empty([], dtype=torch.float),
+    )
+
+
+@register_fake("torchcodec_ns::get_frame_at_index")
+def get_frame_at_index_abstract(
+    decoder: torch.Tensor, *, frame_index: int
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    image_size = [get_ctx().new_dynamic_size() for _ in range(3)]
+    return (
+        torch.empty(image_size),
+        torch.empty([], dtype=torch.float),
+        torch.empty([], dtype=torch.float),
+    )
+
+
+@register_fake("torchcodec_ns::get_frames_at_indices")
+def get_frames_at_indices_abstract(
+    decoder: torch.Tensor, *, frame_indices: Union[torch.Tensor, List[int]]
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    image_size = [get_ctx().new_dynamic_size() for _ in range(4)]
+    return (
+        torch.empty(image_size),
+        torch.empty([], dtype=torch.float),
+        torch.empty([], dtype=torch.float),
+    )
+
+
+@register_fake("torchcodec_ns::get_frames_in_range")
+def get_frames_in_range_abstract(
+    decoder: torch.Tensor,
+    *,
+    start: int,
+    stop: int,
+    step: Optional[int] = None,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    image_size = [get_ctx().new_dynamic_size() for _ in range(4)]
+    return (
+        torch.empty(image_size),
+        torch.empty([], dtype=torch.float),
+        torch.empty([], dtype=torch.float),
+    )
+
+
+@register_fake("torchcodec_ns::get_frames_by_pts_in_range")
+def get_frames_by_pts_in_range_abstract(
+    decoder: torch.Tensor,
+    *,
+    start_seconds: float,
+    stop_seconds: float,
+) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    image_size = [get_ctx().new_dynamic_size() for _ in range(4)]
+    return (
+        torch.empty(image_size),
+        torch.empty([], dtype=torch.float),
+        torch.empty([], dtype=torch.float),
+    )
+
+
+@register_fake("torchcodec_ns::get_frames_by_pts_in_range_audio")
+def get_frames_by_pts_in_range_audio_abstract(
+    decoder: torch.Tensor,
+    *,
+    start_seconds: float,
+    stop_seconds: Optional[float] = None,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    image_size = [get_ctx().new_dynamic_size() for _ in range(4)]
+    return (torch.empty(image_size), torch.empty([], dtype=torch.float))
+
+
+@register_fake("torchcodec_ns::_get_key_frame_indices")
+def get_key_frame_indices_abstract(decoder: torch.Tensor) -> torch.Tensor:
+    return torch.empty([], dtype=torch.int)
+
+
+@register_fake("torchcodec_ns::get_json_metadata")
+def get_json_metadata_abstract(decoder: torch.Tensor) -> str:
+    return ""
+
+
+@register_fake("torchcodec_ns::get_container_json_metadata")
+def get_container_json_metadata_abstract(decoder: torch.Tensor) -> str:
+    return ""
+
+
+@register_fake("torchcodec_ns::get_stream_json_metadata")
+def get_stream_json_metadata_abstract(decoder: torch.Tensor, stream_idx: int) -> str:
+    return ""
+
+
+@register_fake("torchcodec_ns::_test_frame_pts_equality")
+def _test_frame_pts_equality_abstract(
+    decoder: torch.Tensor,
+    *,
+    frame_index: int,
+    pts_seconds_to_test: float,
+) -> bool:
+    return False
+
+
+@register_fake("torchcodec_ns::_get_json_ffmpeg_library_versions")
+def _get_json_ffmpeg_library_versions_abstract() -> str:
+    return ""
+
+
+@register_fake("torchcodec_ns::scan_all_streams_to_update_metadata")
+def scan_all_streams_to_update_metadata_abstract(decoder: torch.Tensor) -> None:
+    return
+
+
+def get_ffmpeg_library_versions():
+    versions_json = _get_json_ffmpeg_library_versions()
+    return json.loads(versions_json)

torchcodec/_core/pybind_ops.cpp

@@ -0,0 +1,50 @@
+// 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.
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include <cstdint>
+
+#include "src/torchcodec/_core/AVIOFileLikeContext.h"
+
+namespace py = pybind11;
+
+namespace facebook::torchcodec {
+
+// Note: It's not immediately obvous why we need both custom_ops.cpp and
+//       pybind_ops.cpp. We do all other Python to C++ bridging in
+//       custom_ops.cpp, and that even depends on pybind11, so why have an
+//       explicit pybind-only file?
+//
+//       The reason is that we want to accept OWNERSHIP of a file-like object
+//       from the Python side. In order to do that, we need a proper
+//       py::object. For raw bytes, we can launder that through a tensor on the
+//       custom_ops.cpp side, but we can't launder a proper Python object
+//       through a tensor. Custom ops can't accept a proper Python object
+//       through py::object, so we have to do direct pybind11 here.
+//
+// TODO: Investigate if we can do something better here. See:
+//         https://github.com/pytorch/torchcodec/issues/896
+//       Short version is that we're laundering a pointer through an int, the
+//       Python side forwards that to decoder creation functions in
+//       custom_ops.cpp and we do another cast on that side to get a pointer
+//       again. We want to investigate if we can do something cleaner by
+//       defining proper pybind objects.
+int64_t create_file_like_context(py::object file_like, bool is_for_writing) {
+  AVIOFileLikeContext* context =
+      new AVIOFileLikeContext(file_like, is_for_writing);
+  return reinterpret_cast<int64_t>(context);
+}
+
+#ifndef PYBIND_OPS_MODULE_NAME
+#error PYBIND_OPS_MODULE_NAME must be defined!
+#endif
+
+PYBIND11_MODULE(PYBIND_OPS_MODULE_NAME, m) {
+  m.def("create_file_like_context", &create_file_like_context);
+}
+
+} // namespace facebook::torchcodec

torchcodec/_frame.py

@@ -0,0 +1,145 @@
+# 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 dataclasses
+from dataclasses import dataclass
+from typing import Iterable, Iterator, Union
+
+from torch import Tensor
+
+
+def _frame_repr(self):
+    # Utility to replace __repr__ method of dataclasses below. This prints the
+    # shape of the .data tensor rather than printing the (potentially very long)
+    # data tensor itself.
+    s = self.__class__.__name__ + ":\n"
+    spaces = "  "
+    for field in dataclasses.fields(self):
+        field_name = field.name
+        field_val = getattr(self, field_name)
+        if field_name == "data":
+            field_name = "data (shape)"
+            field_val = field_val.shape
+        s += f"{spaces}{field_name}: {field_val}\n"
+    return s
+
+
+@dataclass
+class Frame(Iterable):
+    """A single video frame with associated metadata."""
+
+    data: Tensor
+    """The frame data as (3-D ``torch.Tensor``)."""
+    pts_seconds: float
+    """The :term:`pts` of the frame, in seconds (float)."""
+    duration_seconds: float
+    """The duration of the frame, in seconds (float)."""
+
+    def __post_init__(self):
+        # This is called after __init__() when a Frame is created. We can run
+        # input validation checks here.
+        if not self.data.ndim == 3:
+            raise ValueError(f"data must be 3-dimensional, got {self.data.shape = }")
+        self.pts_seconds = float(self.pts_seconds)
+        self.duration_seconds = float(self.duration_seconds)
+
+    def __iter__(self) -> Iterator[Union[Tensor, float]]:
+        for field in dataclasses.fields(self):
+            yield getattr(self, field.name)
+
+    def __repr__(self):
+        return _frame_repr(self)
+
+
+@dataclass
+class FrameBatch(Iterable):
+    """Multiple video frames with associated metadata.
+
+    The ``data`` tensor is typically 4D for sequences of frames (NHWC or NCHW),
+    or 5D for sequences of clips, as returned by the :ref:`samplers
+    <sphx_glr_generated_examples_decoding_sampling.py>`. When ``data`` is 4D (resp.  5D)
+    the ``pts_seconds`` and ``duration_seconds`` tensors are 1D (resp. 2D).
+
+    .. note::
+        The ``pts_seconds`` and ``duration_seconds`` Tensors are always returned
+        on CPU, even if ``data`` is on GPU.
+    """
+
+    data: Tensor
+    """The frames data (``torch.Tensor`` of uint8)."""
+    pts_seconds: Tensor
+    """The :term:`pts` of the frame, in seconds (``torch.Tensor`` of floats)."""
+    duration_seconds: Tensor
+    """The duration of the frame, in seconds (``torch.Tensor`` of floats)."""
+
+    def __post_init__(self):
+        # This is called after __init__() when a FrameBatch is created. We can
+        # run input validation checks here.
+        if self.data.ndim < 3:
+            raise ValueError(
+                f"data must be at least 3-dimensional, got {self.data.shape = }"
+            )
+
+        leading_dims = self.data.shape[:-3]
+        if not (leading_dims == self.pts_seconds.shape == self.duration_seconds.shape):
+            raise ValueError(
+                "Tried to create a FrameBatch but the leading dimensions of the inputs do not match. "
+                f"Got {self.data.shape = } so we expected the shape of pts_seconds and "
+                f"duration_seconds to be {leading_dims = }, but got "
+                f"{self.pts_seconds.shape = } and {self.duration_seconds.shape = }."
+            )
+
+    def __iter__(self) -> Iterator["FrameBatch"]:
+        for data, pts_seconds, duration_seconds in zip(
+            self.data, self.pts_seconds, self.duration_seconds
+        ):
+            yield FrameBatch(
+                data=data,
+                pts_seconds=pts_seconds,
+                duration_seconds=duration_seconds,
+            )
+
+    def __getitem__(self, key) -> "FrameBatch":
+        return FrameBatch(
+            data=self.data[key],
+            pts_seconds=self.pts_seconds[key],
+            duration_seconds=self.duration_seconds[key],
+        )
+
+    def __len__(self):
+        return len(self.data)
+
+    def __repr__(self):
+        return _frame_repr(self)
+
+
+@dataclass
+class AudioSamples(Iterable):
+    """Audio samples with associated metadata."""
+
+    data: Tensor
+    """The sample data (``torch.Tensor`` of float in [-1, 1], shape is ``(num_channels, num_samples)``)."""
+    pts_seconds: float
+    """The :term:`pts` of the first sample, in seconds."""
+    duration_seconds: float
+    """The duration of the samples, in seconds."""
+    sample_rate: int
+    """The sample rate of the samples, in Hz."""
+
+    def __post_init__(self):
+        # This is called after __init__() when a Frame is created. We can run
+        # input validation checks here.
+        if not self.data.ndim == 2:
+            raise ValueError(f"data must be 2-dimensional, got {self.data.shape = }")
+        self.pts_seconds = float(self.pts_seconds)
+        self.sample_rate = int(self.sample_rate)
+
+    def __iter__(self) -> Iterator[Union[Tensor, float]]:
+        for field in dataclasses.fields(self):
+            yield getattr(self, field.name)
+
+    def __repr__(self):
+        return _frame_repr(self)