tensorcodec 0.1.1__tar.gz → 0.1.3__tar.gz

tensorcodec-0.1.3/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: tensorcodec
+Version: 0.1.3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Multimedia :: Video
+Requires-Dist: numpy>=1.26
+License-File: LICENSE
+License-File: licenses/FFmpeg-GPL-3.0.txt
+License-File: licenses/FFmpeg-LGPL-3.0.txt
+License-File: licenses/FFmpeg-NOTICE.md
+License-File: licenses/OpenSSL.txt
+License-File: licenses/README.md
+License-File: licenses/Zstandard.txt
+Summary: NumPy audio/video decoding with TorchCodec-compatible playback semantics
+Author-email: Suhwan Choi <milkclouds00@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Issues, https://github.com/MilkClouds/tensorcodec/issues
+Project-URL: Repository, https://github.com/MilkClouds/tensorcodec
+
+<div align="center">
+
+# TensorCodec
+
+CPU video/audio decoding with TorchCodec-style APIs and NumPy output.
+
+<p align="center">
+<a href="https://github.com/MilkClouds/tensorcodec/actions/workflows/ci.yml"><img src="https://github.com/MilkClouds/tensorcodec/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+<a href="https://pypi.org/project/tensorcodec/"><img src="https://img.shields.io/pypi/v/tensorcodec" alt="PyPI"></a>
+<a href="https://pypi.org/project/tensorcodec/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python"></a>
+<!-- wheel-size-badge:start -->
+<a href="#package-size"><img src="https://img.shields.io/badge/wheel-10.4%20MiB-blue" alt="Wheel download"></a>
+<!-- wheel-size-badge:end -->
+<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License: MIT"></a>
+</p>
+
+[Quick start](#quick-start) · [Features](#features) · [Package size](#package-size) · [Compatibility](docs/compatibility.md)
+
+</div>
+
+- **TorchCodec API without PyTorch.** CPU video/audio decoder interfaces follow
+  TorchCodec and return NumPy arrays.
+- **Validated playback semantics.** Frame selection, ordering, timestamps and audio
+  ranges are checked against TorchCodec 0.17.0 and independently generated media.
+- **Efficient batch decoding.** Rust/PyO3 bindings to FFmpeg process frame batches
+  in a single native call, avoiding per-frame Python calls.
+- **Lightweight installation.** Linux wheels are 10.2–10.4 MiB (v0.1.2), including
+  FFmpeg shared libraries. NumPy is the only Python dependency.
+
+## Quick start
+
+```sh
+uv pip install tensorcodec
+```
+
+Use an existing virtual environment, or create one with `uv venv` first.
+No separate FFmpeg installation is needed for the published Linux wheels.
+
+```python
+from tensorcodec.decoders import VideoDecoder, AudioDecoder
+
+with VideoDecoder("video.mp4") as video:
+    frame = video[0]                                  # RGB array: (C, H, W)
+    batch = video.get_frames_at([4, 0, 4])              # requested order, including duplicates
+    clip = video.get_frames_played_in_range(0, 1, fps=8)
+
+with AudioDecoder("audio.wav", sample_rate=16000, num_channels=1) as audio:
+    samples = audio.get_samples_played_in_range(0, 1)
+    waveform = samples.data                           # float32: (channels, samples)
+```
+
+Arrays keep their storage after the decoder closes. Paths, URLs, encoded bytes,
+1-D uint8 arrays and seekable file objects are supported.
+
+## Features
+
+TensorCodec 0.1.3 relative to TorchCodec 0.17.0.
+✓ supported · △ partial support · — not implemented.
+
+| Component | TensorCodec | TorchCodec 0.17.0 |
+| --- | --- | --- |
+| Video decoder | △ CPU, SDR/HDR RGB | ✓ CPU / CUDA |
+| Audio decoder | ✓ CPU | ✓ CPU |
+| Image decoders | — | ✓ |
+| Video / audio / image encoders | — | ✓ |
+| Clip samplers | — | ✓ |
+| Decoder transforms | — | ✓ |
+
+FPS-based frame queries are supported; clip samplers are a separate API.
+
+### Decoder compatibility
+
+| Capability | TensorCodec | TorchCodec 0.17.0 |
+| --- | --- | --- |
+| Index / slice / batch selection | ✓ | ✓ |
+| Playback timestamp / range queries | ✓ | ✓ |
+| Request order and duplicate frames | Preserved | Preserved |
+| Exact / approximate seeking | ✓ Default: exact | ✓ |
+| FPS queries / custom frame mappings | ✓ | ✓ |
+| CFR / VFR / offset PTS / B-frames | ✓ Tested | ✓ |
+| NCHW / NHWC RGB output | ✓ | ✓ |
+| uint8 / float32 / automatic dtype | ✓ SDR and high-bit-depth video | ✓ |
+| uint16 RGB output | ✓ Full-range RGB48 | — |
+| Native grayscale/depth and packed RGB(A) | ✓ Values preserved | — |
+| PQ / HLG decoding | ✓ Transfer-encoded RGB | ✓ |
+| Right-angle display rotation | ✓ | ✓ |
+| Audio ranges / resampling / channel mixing | ✓ float32 | ✓ |
+| Paths / URLs / bytes / seekable file objects | ✓ | ✓ |
+| Encoded array input | 1-D uint8 NumPy array | PyTorch tensor |
+| Decoded output | NumPy array; array interface / DLPack | PyTorch tensor |
+| CUDA decoding | — | ✓ |
+
+For high-bit-depth video, use `VideoDecoder(path, output_dtype="auto")` to select
+float32 above 8 bits, or `output_dtype="uint16"` for full-range 16-bit RGB.
+HDR output retains PQ/HLG encoding without SDR tone mapping. Rotation is applied
+automatically, and metadata dimensions match the output.
+
+For unmodified samples, use `VideoDecoder(path, output_format="native")`.
+Supported formats: `gray`, `gray12le`, `gray16le/be`, `rgb24`, `rgba`.
+Native output preserves channel count, integer values and pixel coordinates;
+`expected_pixel_format` optionally asserts the source format.
+
+## Package size
+
+<!-- wheel-size:start -->
+Linux CPU wheels, Python 3.12. Download / unpacked size in MiB.
+
+| Package | x86_64 | ARM64 |
+| --- | ---: | ---: |
+| TensorCodec | 10.2 / 24.7 | 10.4 / 22.9 |
+| PyAV | 33.4 / 125.5 | 31.2 / 90.4 |
+| TorchCodec + PyTorch (CPU) | 196.7 / 704.7 | 160.3 / 585.7 |
+<!-- wheel-size:end -->
+
+TensorCodec and PyAV bundle FFmpeg; TorchCodec needs it separately.
+Other dependencies are excluded. [Measurements](docs/package_size.md).
+
+## Scope and compatibility
+
+The supported CPU API is checked for frame selection, ordering, timestamps,
+durations, stream selection and metadata, both against TorchCodec 0.17.0 and
+independently generated media.
+
+- Pixel comparisons allow color-conversion rounding of at most 1 uint8 unit or
+  1/65535 for float32 in the tested cases.
+- Empty index lists are supported, including the case affected by the reference's
+  empty-list dtype inference bug.
+- NumPy output preserves the decoder API structure; callers expecting
+  `torch.Tensor` must adapt their array handling.
+
+See the [compatibility contract](docs/compatibility.md) and
+[playback rules](docs/playback_semantics.md) for the tested behavior.
+
+### Current limits
+
+- **Wheels:** Linux x86_64 and ARM64 (aarch64), glibc 2.17+, CPython 3.10+.
+  NumPy must also provide a compatible wheel; newer Python versions may require
+  a newer glibc. macOS 14+ wheels support ARM64 and x86_64. Windows, musl/Alpine
+  and free-threaded Python wheels are not provided.
+- **Exact seeking:** scans packet timestamps when opening the decoder. Incorrect
+  container keyframe flags can produce corrupt frames; repaired input or corrected
+  frame mappings are needed in that case.
+- **Audio ranges:** decode from the beginning, so late ranges can be expensive.
+- **Video conversion:** no HDR-to-SDR tone mapping or native YUV-plane output.
+  Reflected and non-right-angle display matrices are unsupported.
+
+See [container behavior](docs/container_robustness.md) for seek limitations and
+[benchmark tools](benchmarks/README.md) for workload measurements.
+
+## Development and verification
+
+<details>
+<summary>Build from source and run tests</summary>
+
+Source builds require Rust, Clang/libclang, pkg-config and FFmpeg 7 development
+headers/libraries. Python handles API and playback selection; Rust + PyO3 handles
+FFmpeg. Native decoding releases the GIL, allowing separate decoder instances to
+run concurrently across Python threads. Calls on the same instance are serialized.
+The default is one FFmpeg thread per decoder; use independent workers for concurrent
+windows and tune the total thread count to avoid oversubscription.
+
+```sh
+uv sync --group dev --group oracle
+
+uv run --group oracle pytest tests/test_video_contract.py tests/test_audio_contract.py --backend torchcodec
+uv run --group oracle pytest --compare
+
+# Rebuild after changing Rust code.
+uv run --group oracle maturin develop --locked --uv
+```
+
+Tests generate media with FFmpeg/ffprobe and Python's `wave` module.
+`--compare` requires the pinned oracle; differential tests otherwise skip.
+
+[Playback rules](docs/playback_semantics.md) · [Release guide](docs/releasing.md) · [Dependency licenses](licenses/README.md)
+
+</details>
+
+TensorCodec's own code is [MIT licensed](LICENSE).
+

tensorcodec-0.1.3/README.md

@@ -0,0 +1,179 @@
+<div align="center">
+
+# TensorCodec
+
+CPU video/audio decoding with TorchCodec-style APIs and NumPy output.
+
+<p align="center">
+<a href="https://github.com/MilkClouds/tensorcodec/actions/workflows/ci.yml"><img src="https://github.com/MilkClouds/tensorcodec/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+<a href="https://pypi.org/project/tensorcodec/"><img src="https://img.shields.io/pypi/v/tensorcodec" alt="PyPI"></a>
+<a href="https://pypi.org/project/tensorcodec/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python"></a>
+<!-- wheel-size-badge:start -->
+<a href="#package-size"><img src="https://img.shields.io/badge/wheel-10.4%20MiB-blue" alt="Wheel download"></a>
+<!-- wheel-size-badge:end -->
+<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License: MIT"></a>
+</p>
+
+[Quick start](#quick-start) · [Features](#features) · [Package size](#package-size) · [Compatibility](docs/compatibility.md)
+
+</div>
+
+- **TorchCodec API without PyTorch.** CPU video/audio decoder interfaces follow
+  TorchCodec and return NumPy arrays.
+- **Validated playback semantics.** Frame selection, ordering, timestamps and audio
+  ranges are checked against TorchCodec 0.17.0 and independently generated media.
+- **Efficient batch decoding.** Rust/PyO3 bindings to FFmpeg process frame batches
+  in a single native call, avoiding per-frame Python calls.
+- **Lightweight installation.** Linux wheels are 10.2–10.4 MiB (v0.1.2), including
+  FFmpeg shared libraries. NumPy is the only Python dependency.
+
+## Quick start
+
+```sh
+uv pip install tensorcodec
+```
+
+Use an existing virtual environment, or create one with `uv venv` first.
+No separate FFmpeg installation is needed for the published Linux wheels.
+
+```python
+from tensorcodec.decoders import VideoDecoder, AudioDecoder
+
+with VideoDecoder("video.mp4") as video:
+    frame = video[0]                                  # RGB array: (C, H, W)
+    batch = video.get_frames_at([4, 0, 4])              # requested order, including duplicates
+    clip = video.get_frames_played_in_range(0, 1, fps=8)
+
+with AudioDecoder("audio.wav", sample_rate=16000, num_channels=1) as audio:
+    samples = audio.get_samples_played_in_range(0, 1)
+    waveform = samples.data                           # float32: (channels, samples)
+```
+
+Arrays keep their storage after the decoder closes. Paths, URLs, encoded bytes,
+1-D uint8 arrays and seekable file objects are supported.
+
+## Features
+
+TensorCodec 0.1.3 relative to TorchCodec 0.17.0.
+✓ supported · △ partial support · — not implemented.
+
+| Component | TensorCodec | TorchCodec 0.17.0 |
+| --- | --- | --- |
+| Video decoder | △ CPU, SDR/HDR RGB | ✓ CPU / CUDA |
+| Audio decoder | ✓ CPU | ✓ CPU |
+| Image decoders | — | ✓ |
+| Video / audio / image encoders | — | ✓ |
+| Clip samplers | — | ✓ |
+| Decoder transforms | — | ✓ |
+
+FPS-based frame queries are supported; clip samplers are a separate API.
+
+### Decoder compatibility
+
+| Capability | TensorCodec | TorchCodec 0.17.0 |
+| --- | --- | --- |
+| Index / slice / batch selection | ✓ | ✓ |
+| Playback timestamp / range queries | ✓ | ✓ |
+| Request order and duplicate frames | Preserved | Preserved |
+| Exact / approximate seeking | ✓ Default: exact | ✓ |
+| FPS queries / custom frame mappings | ✓ | ✓ |
+| CFR / VFR / offset PTS / B-frames | ✓ Tested | ✓ |
+| NCHW / NHWC RGB output | ✓ | ✓ |
+| uint8 / float32 / automatic dtype | ✓ SDR and high-bit-depth video | ✓ |
+| uint16 RGB output | ✓ Full-range RGB48 | — |
+| Native grayscale/depth and packed RGB(A) | ✓ Values preserved | — |
+| PQ / HLG decoding | ✓ Transfer-encoded RGB | ✓ |
+| Right-angle display rotation | ✓ | ✓ |
+| Audio ranges / resampling / channel mixing | ✓ float32 | ✓ |
+| Paths / URLs / bytes / seekable file objects | ✓ | ✓ |
+| Encoded array input | 1-D uint8 NumPy array | PyTorch tensor |
+| Decoded output | NumPy array; array interface / DLPack | PyTorch tensor |
+| CUDA decoding | — | ✓ |
+
+For high-bit-depth video, use `VideoDecoder(path, output_dtype="auto")` to select
+float32 above 8 bits, or `output_dtype="uint16"` for full-range 16-bit RGB.
+HDR output retains PQ/HLG encoding without SDR tone mapping. Rotation is applied
+automatically, and metadata dimensions match the output.
+
+For unmodified samples, use `VideoDecoder(path, output_format="native")`.
+Supported formats: `gray`, `gray12le`, `gray16le/be`, `rgb24`, `rgba`.
+Native output preserves channel count, integer values and pixel coordinates;
+`expected_pixel_format` optionally asserts the source format.
+
+## Package size
+
+<!-- wheel-size:start -->
+Linux CPU wheels, Python 3.12. Download / unpacked size in MiB.
+
+| Package | x86_64 | ARM64 |
+| --- | ---: | ---: |
+| TensorCodec | 10.2 / 24.7 | 10.4 / 22.9 |
+| PyAV | 33.4 / 125.5 | 31.2 / 90.4 |
+| TorchCodec + PyTorch (CPU) | 196.7 / 704.7 | 160.3 / 585.7 |
+<!-- wheel-size:end -->
+
+TensorCodec and PyAV bundle FFmpeg; TorchCodec needs it separately.
+Other dependencies are excluded. [Measurements](docs/package_size.md).
+
+## Scope and compatibility
+
+The supported CPU API is checked for frame selection, ordering, timestamps,
+durations, stream selection and metadata, both against TorchCodec 0.17.0 and
+independently generated media.
+
+- Pixel comparisons allow color-conversion rounding of at most 1 uint8 unit or
+  1/65535 for float32 in the tested cases.
+- Empty index lists are supported, including the case affected by the reference's
+  empty-list dtype inference bug.
+- NumPy output preserves the decoder API structure; callers expecting
+  `torch.Tensor` must adapt their array handling.
+
+See the [compatibility contract](docs/compatibility.md) and
+[playback rules](docs/playback_semantics.md) for the tested behavior.
+
+### Current limits
+
+- **Wheels:** Linux x86_64 and ARM64 (aarch64), glibc 2.17+, CPython 3.10+.
+  NumPy must also provide a compatible wheel; newer Python versions may require
+  a newer glibc. macOS 14+ wheels support ARM64 and x86_64. Windows, musl/Alpine
+  and free-threaded Python wheels are not provided.
+- **Exact seeking:** scans packet timestamps when opening the decoder. Incorrect
+  container keyframe flags can produce corrupt frames; repaired input or corrected
+  frame mappings are needed in that case.
+- **Audio ranges:** decode from the beginning, so late ranges can be expensive.
+- **Video conversion:** no HDR-to-SDR tone mapping or native YUV-plane output.
+  Reflected and non-right-angle display matrices are unsupported.
+
+See [container behavior](docs/container_robustness.md) for seek limitations and
+[benchmark tools](benchmarks/README.md) for workload measurements.
+
+## Development and verification
+
+<details>
+<summary>Build from source and run tests</summary>
+
+Source builds require Rust, Clang/libclang, pkg-config and FFmpeg 7 development
+headers/libraries. Python handles API and playback selection; Rust + PyO3 handles
+FFmpeg. Native decoding releases the GIL, allowing separate decoder instances to
+run concurrently across Python threads. Calls on the same instance are serialized.
+The default is one FFmpeg thread per decoder; use independent workers for concurrent
+windows and tune the total thread count to avoid oversubscription.
+
+```sh
+uv sync --group dev --group oracle
+
+uv run --group oracle pytest tests/test_video_contract.py tests/test_audio_contract.py --backend torchcodec
+uv run --group oracle pytest --compare
+
+# Rebuild after changing Rust code.
+uv run --group oracle maturin develop --locked --uv
+```
+
+Tests generate media with FFmpeg/ffprobe and Python's `wave` module.
+`--compare` requires the pinned oracle; differential tests otherwise skip.
+
+[Playback rules](docs/playback_semantics.md) · [Release guide](docs/releasing.md) · [Dependency licenses](licenses/README.md)
+
+</details>
+
+TensorCodec's own code is [MIT licensed](LICENSE).

{tensorcodec-0.1.1 → tensorcodec-0.1.3}/docs/compatibility.md

@@ -14,12 +14,12 @@ FFmpeg; arrays are returned as NumPy instead of torch.Tensor.
   Also `get_all_frames`, FPS resampling and custom JSON frame mappings.
 - `tensorcodec.decoders.AudioDecoder`: constructor, metadata, stream_index,
   `get_all_samples`, `get_samples_played_in_range`, resampling and channel mixing.
-- NumPy uint8 or float32 video and float32 audio; float64 batch timestamps/durations.
+- NumPy uint8, uint16 or float32 video and float32 audio; float64 batch timestamps/durations.
   Float32 RGB uses 16-bit color conversion rather than scaling uint8 output.
 - NCHW/NHWC, paths/URLs, encoded bytes, uint8 arrays and seekable file-like input.
 - Exact and approximate video seeking; exact is the default.
 
-CUDA, torch inputs, torchvision transforms, HDR tone mapping, rotated video,
+CUDA, torch inputs, torchvision transforms, HDR tone mapping, arbitrary-angle rotation,
 encoders and samplers are outside the
 initial CPU decoding contract. Unsupported device/transform options fail explicitly.
 Do not advertise full-package or torch.Tensor type compatibility.
@@ -39,13 +39,12 @@ exception classes follow the reference, including its restrictions on slice step
 
 Fixtures are generated with FFmpeg from known grayscale frame identities and
 explicit timestamp schedules, and with Python's wave module from known PCM.
-ffprobe validates encoded packet metadata independently. The original avdec
-decoder and tests are not executed. Run the same contract tests against the
-reference before adding implementation:
+ffprobe validates encoded packet metadata independently. Run the same contract
+tests against the reference before adding implementation:
 
 ```sh
-pytest tests/test_video_contract.py tests/test_audio_contract.py --backend torchcodec
-pytest --compare
+uv run --group oracle pytest tests/test_video_contract.py tests/test_audio_contract.py --backend torchcodec
+uv run --group oracle pytest --compare
 ```
 
 Comparisons check timing separately from pixels. One uint8 RGB unit or 1/65535
@@ -56,3 +55,29 @@ when `--compare` is requested. Production installation does not require torch.
 Intentional fix: TensorCodec accepts empty index lists. TorchCodec 0.17.0 infers
 float for empty index lists; oracle tests use explicitly typed input tensors to
 isolate playback semantics from that conversion bug.
+
+## Video fidelity extensions
+
+PQ/HLG inputs decode as transfer-encoded RGB without tone mapping. `auto` uses
+float32 for source component depths above 8 bits, including high-depth SDR.
+Explicit uint16 returns full-range RGB48 and is a TensorCodec extension; it is
+not native YUV output. Source `bit_depth` and `color_range` metadata are also
+TensorCodec extensions. Right-angle display rotations are applied automatically;
+metadata dimensions describe the rotated output. Reflected and non-right-angle
+display matrices remain unsupported. Color metadata and pixel aspect ratio
+describe the source; HDR output is not linear light or sRGB.
+
+## Native video output
+
+`output_format="native"` bypasses color conversion and display transforms for
+`gray`, `gray12le`, `gray16le`, `gray16be`, `rgb24` and `rgba`. NCHW/NHWC keeps
+1, 3 or 4 channels. Output uses host-endian uint8/uint16 without range scaling;
+`output_dtype` may be omitted, `"auto"`, or the matching integer dtype.
+`expected_pixel_format` asserts the source layout. Unsupported formats, dtype
+conversions and changes of pixel format or dimensions fail explicitly.
+
+Frame/FrameBatch `pixel_format` records the native source format and survives
+indexing and FPS resampling. RGB results retain their existing behavior. Native
+mode preserves encoded pixel coordinates, including inputs with display matrices.
+Playback selection follows the same TorchCodec contract as RGB, including the
+frame overlapping a range's start; it does not copy PyAV's legacy PTS-only range rule.

tensorcodec-0.1.3/docs/package_size.md

@@ -0,0 +1,73 @@
+# Package size policy
+
+TensorCodec keeps its NumPy-only Python dependency set and bundles a minimal
+FFmpeg/OpenSSL runtime in its default Linux wheels. Size limits prevent additions
+from silently increasing the distributed binary footprint.
+
+## What is measured
+
+| Metric | Definition | Per-wheel limit |
+| --- | --- | ---: |
+| Download | Final `.whl` file size, in bytes | 15 MiB |
+| Unpacked | Sum of ZIP entry file sizes, including bundled libraries | 35 MiB |
+
+The sole policy file is [`packaging/size-policy.json`](../packaging/size-policy.json).
+The checker uses only Python's standard library and never extracts the archive.
+Unpacked size excludes filesystem allocation overhead. Both metrics exclude NumPy,
+Python, package caches and other external dependencies; they are not total
+installation sizes. Reports and the README use MiB (2^20 bytes).
+
+Check final, repaired wheels locally:
+
+```sh
+uv run --no-project python scripts/check_wheel_size.py dist/*.whl --output reports/wheel-size.json
+```
+
+Each architecture is checked independently. Exactly reaching a limit passes;
+exceeding either limit fails. The release workflow runs this after `auditwheel
+repair`, before uploading distributions. JSON reports are separate artifacts, not
+files in `dist/`. Actions summaries include changes from the committed published
+baseline. Ordinary CI tests the checker without building FFmpeg from source.
+
+Before changing a limit, explain the feature, the measured byte increase on both
+architectures and why a smaller configuration would not provide the same behavior.
+A limit change should be reviewed with the change that needs it.
+
+## Decoder comparison and badge
+
+[`packaging/size-baseline.json`](../packaging/size-baseline.json) records wheel URLs,
+SHA-256 hashes, versions and sizes for TensorCodec, PyAV, TorchCodec and
+PyTorch CPU. Artifacts come from PyPI except PyTorch, which uses the official
+CPU index. All wheels support CPython 3.12 on Linux x86_64 or ARM64.
+
+The README sums TorchCodec and PyTorch wheels. TensorCodec and PyAV include FFmpeg;
+TorchCodec requires it separately. NumPy and other external dependencies are
+excluded. These are package footprints, not complete environment sizes.
+
+After publication, the update script verifies hashes, checks TensorCodec's limits,
+and refreshes the table and badge. The badge shows the largest TensorCodec wheel
+download; candidate builds never update it.
+
+To reproduce or recover a documentation update after publication:
+
+```sh
+uv run --no-project python scripts/update_size_comparison.py --version 0.1.3
+```
+
+Review and commit `README.md` and `packaging/size-baseline.json` together. The script
+requires both architectures to have been published and fails on ambiguous wheels,
+yanked wheels, missing files or hash mismatches. If publication succeeded but the
+documentation job failed, repair the documentation separately; do not republish
+the same version. A concurrent change to `main` can reject the documentation push;
+the workflow never force-pushes.
+
+## Why FFmpeg stays bundled by default
+
+Bundling the selected FFmpeg libraries provides one-step installation and fixes the
+runtime ABI and codec configuration used by the release tests. A full conda-forge
+FFmpeg environment can include many additional codec, graphics and system packages;
+moving these outside the wheel does not necessarily reduce total installation size.
+
+Reusing an existing shared FFmpeg 7 installation is an advanced source-build option:
+[system FFmpeg guide](system_ffmpeg.md). FFmpeg CLI availability alone does not
+satisfy the native library requirement.

{tensorcodec-0.1.1 → tensorcodec-0.1.3}/docs/playback_semantics.md

@@ -2,7 +2,7 @@
 
 The supported behavior is specified in [compatibility.md](compatibility.md) and
 executable tests in `tests/test_video_contract.py` and `tests/test_audio_contract.py`.
-The reference is TorchCodec 0.17.0. These replace the previous avdec/PyAV design.
+The reference is TorchCodec 0.17.0.
 
 Exact video seeking scans presentation timestamps and preceding key-frame PTS.
 Index requests use that map; time requests select the frame playing at the requested

{tensorcodec-0.1.1 → tensorcodec-0.1.3}/docs/releasing.md

@@ -1,33 +1,31 @@
 # Publishing TensorCodec
 
-Release version: `0.1.1`. Distribution and import name: `tensorcodec`.
+Release version: `0.1.3`. Distribution and import name: `tensorcodec`.
 Binary wheels target Linux x86_64 and ARM64 (aarch64), glibc 2.17+, CPython 3.10+.
 NumPy must also provide a compatible wheel for the selected Python/glibc pair.
 The wheel bundles shared FFmpeg 7.1.5 and OpenSSL 3.5.9 LTS; its only Python
-runtime dependency is NumPy. macOS/Windows wheels are not yet provided.
+runtime dependency is NumPy. macOS 14+ ARM64/x86_64 wheels bundle the same minimal
+runtime. Windows wheels are not provided.
 
-## One-time account setup
+## Trusted publisher configuration
 
-1. Rename `MilkClouds/avdec` to `tensorcodec` in GitHub repository Settings.
-   Preserve the current visibility; publishing does not require making it public.
-2. Open https://pypi.org/manage/account/publishing/ and add a **pending GitHub
-   publisher** for a new project with these values:
+The PyPI project is already registered. Its GitHub Trusted Publisher uses:
 
-   | Field | Value |
-   | --- | --- |
-   | PyPI project name | `tensorcodec` |
-   | GitHub owner | `MilkClouds` |
-   | Repository | `tensorcodec` |
-   | Workflow filename | `publish.yml` |
-   | Environment | `pypi` |
+| Field | Value |
+| --- | --- |
+| PyPI project name | `tensorcodec` |
+| GitHub owner | `MilkClouds` |
+| Repository | `tensorcodec` |
+| Workflow filename | `publish.yml` |
+| Environment | `pypi` |
 
-A pending publisher creates the project on its first successful upload. If the
-project already exists, register the publisher in that project's Publishing
-settings instead. Do not put an API token in the repository or chat.
+Manage this configuration in the project's PyPI Publishing settings when moving
+or renaming the repository or workflow. Publishing uses GitHub OIDC; no API token
+is needed. Repository visibility does not need to change for a release.
 
 ## Release
 
-Run the **Publish to PyPI** workflow on `main`. It builds the portable Linux wheels
+Run the **Publish to PyPI** workflow on `main`. It builds the portable Linux/macOS wheels
 and source distribution, checks package metadata, validates the pinned oracle
 and compares playback before uploading through PyPI Trusted Publishing. It uses
 the existing GitHub `pypi` environment. Publication fails if authorization is
@@ -39,8 +37,8 @@ gh workflow run publish.yml --repo MilkClouds/tensorcodec --ref main
 
 For a build and full validation without uploading, pass `--field publish=false`.
 
-Check the workflow and https://pypi.org/project/tensorcodec/0.1.1/ before reporting
-success. Verify a fresh `uv pip install tensorcodec==0.1.1` and a decode without
+Check the workflow and https://pypi.org/project/tensorcodec/0.1.3/ before reporting
+success. Verify a fresh `uv pip install tensorcodec==0.1.3` and a decode without
 Torch/PyAV on both architectures. Update the version before subsequent releases;
 PyPI versions cannot be overwritten.
 
@@ -64,3 +62,22 @@ and source links are recorded in `licenses/README.md`.
   x86_64 and ARM64 runners also run the full pinned playback oracle comparison.
 - Release validation still tests the installed repaired wheel. The fixture CLI
   can be FFmpeg 6 or 7; fixtures explicitly remove auxiliary sentinel packets.
+
+## Size checks and published comparison
+
+Final repaired wheels must stay within 15 MiB download and 35 MiB unpacked per
+architecture. The build job checks `packaging/size-policy.json` and uploads a
+separate `wheel-size-*` report, including differences from the last published
+baseline. Size reports must not be placed in `dist/`.
+
+After a successful publication, the `update-size-docs` job measures hash-verified
+PyPI wheels for the release and pinned TorchCodec 0.17.0. It commits the published
+snapshot and README table/badge with a normal push to `main`. Only this documentation
+job has `contents: write`; the PyPI publisher retains OIDC plus read access. The
+repository must permit the Actions bot to push these documentation updates.
+
+If the documentation job fails after a successful publication, recover by running
+`scripts/update_size_comparison.py --version <published-version>` and committing
+its two outputs. Never retry publication of an already uploaded version. See the
+[package size policy](package_size.md) for measurement definitions and the
+[external FFmpeg guide](system_ffmpeg.md) for the optional source-build path.