torchcodec 0.7.0__cp313-cp313-win_amd64.whl

torchcodec/_core/ops.py

@@ -0,0 +1,455 @@
+# 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 (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_audio_to_tensor = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns.encode_audio_to_tensor.default
+)
+create_from_tensor = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns.create_from_tensor.default
+)
+_convert_to_tensor = torch._dynamo.disallow_in_graph(
+    torch.ops.torchcodec_ns._convert_to_tensor.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 = torch.ops.torchcodec_ns.get_frames_at_indices.default
+get_frames_by_pts = 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 _convert_to_tensor(_pybind_ops.create_from_file_like(file_like, 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}")
+
+    # We're having the same problem as with the decoder's create_from_file_like:
+    # We should be able to pass a tensor directly, but this leads to a pybind
+    # error. In order to work around this, we pass the pointer to the tensor's
+    # data, and its shape, in order to re-construct it in C++. For this to work:
+    # - the tensor must be float32
+    # - the tensor  must be contiguous, which is why we call contiguous().
+    #   In theory we could avoid this restriction by also passing the strides?
+    # - IMPORTANT: the input samples tensor and its underlying data must be
+    #   alive during the call.
+    #
+    # A more elegant solution would be to cast the tensor into a py::object, but
+    # casting the py::object backk to a tensor in C++ seems to lead to the same
+    # pybing error.
+
+    samples = samples.contiguous()
+    _pybind_ops.encode_audio_to_file_like(
+        samples.data_ptr(),
+        list(samples.shape),
+        sample_rate,
+        format,
+        file_like,
+        bit_rate,
+        num_channels,
+        desired_sample_rate,
+    )
+
+    # This check is useless but it's critical to keep it to ensures that samples
+    # is still alive during the call to encode_audio_to_file_like.
+    assert samples.is_contiguous()
+
+
+# ==============================
+# 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::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_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::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::_convert_to_tensor")
+def _convert_to_tensor_abstract(decoder_ptr: int) -> torch.Tensor:
+    return torch.empty([], dtype=torch.long)
+
+
+@register_fake("torchcodec_ns::_add_video_stream")
+def _add_video_stream_abstract(
+    decoder: torch.Tensor,
+    *,
+    width: Optional[int] = None,
+    height: Optional[int] = None,
+    num_threads: Optional[int] = None,
+    dimension_order: Optional[str] = None,
+    stream_index: Optional[int] = None,
+    device: Optional[str] = None,
+    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,
+    *,
+    width: Optional[int] = None,
+    height: Optional[int] = None,
+    num_threads: Optional[int] = None,
+    dimension_order: Optional[str] = None,
+    stream_index: Optional[int] = None,
+    device: Optional[str] = None,
+    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: 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: 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,87 @@
+// 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 <string>
+
+#include "src/torchcodec/_core/AVIOFileLikeContext.h"
+#include "src/torchcodec/_core/Encoder.h"
+#include "src/torchcodec/_core/SingleStreamDecoder.h"
+#include "src/torchcodec/_core/StreamOptions.h"
+#include "src/torchcodec/_core/ValidationUtils.h"
+
+namespace py = pybind11;
+
+namespace facebook::torchcodec {
+
+// In principle, this should be able to return a tensor. But when we try that,
+// we run into the bug reported here:
+//
+//   https://github.com/pytorch/pytorch/issues/136664
+//
+// So we instead launder the pointer through an int, and then use a conversion
+// function on the custom ops side to launder that int into a tensor.
+int64_t create_from_file_like(
+    py::object file_like,
+    std::optional<std::string_view> seek_mode) {
+  SingleStreamDecoder::SeekMode realSeek = SingleStreamDecoder::SeekMode::exact;
+  if (seek_mode.has_value()) {
+    realSeek = seekModeFromString(seek_mode.value());
+  }
+
+  auto avioContextHolder =
+      std::make_unique<AVIOFileLikeContext>(file_like, /*isForWriting=*/false);
+
+  SingleStreamDecoder* decoder =
+      new SingleStreamDecoder(std::move(avioContextHolder), realSeek);
+  return reinterpret_cast<int64_t>(decoder);
+}
+
+void encode_audio_to_file_like(
+    int64_t data_ptr,
+    const std::vector<int64_t>& shape,
+    int64_t sample_rate,
+    std::string_view format,
+    py::object file_like,
+    std::optional<int64_t> bit_rate = std::nullopt,
+    std::optional<int64_t> num_channels = std::nullopt,
+    std::optional<int64_t> desired_sample_rate = std::nullopt) {
+  // We assume float32 *and* contiguity, this must be enforced by the caller.
+  auto tensor_options = torch::TensorOptions().dtype(torch::kFloat32);
+  auto samples = torch::from_blob(
+      reinterpret_cast<void*>(data_ptr), shape, tensor_options);
+
+  AudioStreamOptions audioStreamOptions;
+  audioStreamOptions.bitRate = validateOptionalInt64ToInt(bit_rate, "bit_rate");
+  audioStreamOptions.numChannels =
+      validateOptionalInt64ToInt(num_channels, "num_channels");
+  audioStreamOptions.sampleRate =
+      validateOptionalInt64ToInt(desired_sample_rate, "desired_sample_rate");
+
+  auto avioContextHolder =
+      std::make_unique<AVIOFileLikeContext>(file_like, /*isForWriting=*/true);
+
+  AudioEncoder encoder(
+      samples,
+      validateInt64ToInt(sample_rate, "sample_rate"),
+      format,
+      std::move(avioContextHolder),
+      audioStreamOptions);
+  encoder.encode();
+}
+
+#ifndef PYBIND_OPS_MODULE_NAME
+#error PYBIND_OPS_MODULE_NAME must be defined!
+#endif
+
+PYBIND11_MODULE(PYBIND_OPS_MODULE_NAME, m) {
+  m.def("create_from_file_like", &create_from_file_like);
+  m.def("encode_audio_to_file_like", &encode_audio_to_file_like);
+}
+
+} // 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)