tensorcodec 0.1.0__tar.gz → 0.1.2__tar.gz

tensorcodec-0.1.2/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: tensorcodec
+Version: 0.1.2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+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.1), 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.2 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 | — |
+| 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.
+
+## 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, Windows, musl/Alpine and free-threaded Python wheels are
+  not release targets yet.
+- **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.
+
+```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.2/README.md

@@ -0,0 +1,171 @@
+<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.1), 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.2 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 | — |
+| 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.
+
+## 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, Windows, musl/Alpine and free-threaded Python wheels are
+  not release targets yet.
+- **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.
+
+```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.0 → tensorcodec-0.1.2}/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,14 @@ 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.

tensorcodec-0.1.2/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.2
+```
+
+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.0 → tensorcodec-0.1.2}/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.2/docs/releasing.md

@@ -0,0 +1,82 @@
+# Publishing TensorCodec
+
+Release version: `0.1.2`. 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.
+
+## Trusted publisher configuration
+
+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` |
+
+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
+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
+missing, tests fail, or the version has already been uploaded.
+
+```sh
+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.2/ before reporting
+success. Verify a fresh `uv pip install tensorcodec==0.1.2` and a decode without
+Torch/PyAV on both architectures. Update the version before subsequent releases;
+PyPI versions cannot be overwritten.
+
+The local Linux build is reproducible using `scripts/build_linux_wheel.sh` inside
+`quay.io/pypa/manylinux2014_x86_64` or
+`quay.io/pypa/manylinux2014_aarch64` with Rust, maturin, libclang, NASM and Perl.
+Both native source archives are version- and checksum-pinned. Their licensing
+and source links are recorded in `licenses/README.md`.
+
+## CI versus release builds
+
+- Ordinary CI uses prebuilt conda-forge FFmpeg 7.1.1 through Pixi, including its
+  headers and shared libraries. It builds only the TensorCodec extension.
+- PyPI wheels use the smaller LGPL FFmpeg 7.1.5 build plus OpenSSL 3.5.9.
+  Their native prefix is cached by architecture, glibc baseline and build-script
+  checksums. This preserves the wheel's codec set, dependency size and licensing rather than bundling the full
+  conda-forge dependency graph.
+- Release validation installs each repaired wheel on glibc 2.17 with Python 3.10
+  and 3.13 and decodes video/audio without Torch, PyAV or a system FFmpeg. Python
+  3.10 also checks the minimum NumPy line (1.26.4). Native
+  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.

tensorcodec-0.1.2/docs/system_ffmpeg.md

@@ -0,0 +1,77 @@
+# Reusing an existing FFmpeg installation
+
+## Default install
+
+```sh
+uv venv
+uv pip install tensorcodec
+```
+
+Supported Linux wheels include minimal shared FFmpeg 7.1.5 and OpenSSL libraries.
+No FFmpeg CLI, Pixi, Rust or libclang is required at runtime. This is the recommended
+installation for a new environment.
+
+## Source build with shared FFmpeg 7
+
+Use this path when a server or container already provides compatible shared
+FFmpeg libraries, or when you intentionally want the codec configuration of that
+installation. The result depends on that external installation rather than the
+bundled release libraries.
+
+Requirements: supported Python, Rust/Cargo, a C toolchain, Clang/libclang,
+`pkg-config`, and FFmpeg 7 headers and shared libraries. An executable-only or
+static-only FFmpeg installation is insufficient. FFmpeg 8/9 is not a supported
+replacement for the current native boundary. Do not point a repaired PyPI wheel
+at another FFmpeg installation by removing its bundled libraries.
+
+For a Linux Pixi example, the prebuilt FFmpeg configuration used by ordinary CI is:
+
+```sh
+pixi global install --environment tensorcodec-ffmpeg 'ffmpeg=7.1.1=gpl_*'
+
+# Pixi's default global environment location; adjust if PIXI_HOME is configured.
+export FFMPEG_DIR="${PIXI_HOME:-$HOME/.pixi}/envs/tensorcodec-ffmpeg"
+export LD_LIBRARY_PATH="$FFMPEG_DIR/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+
+test -f "$FFMPEG_DIR/include/libavcodec/avcodec.h"
+test -f "$FFMPEG_DIR/lib/libavcodec.so.61"
+
+uv venv
+uv pip install --no-binary tensorcodec 'tensorcodec==0.1.2'
+```
+
+The version/build constraint avoids silently selecting an incompatible FFmpeg
+major. `FFMPEG_DIR` tells the source build where to find headers and libraries;
+`LD_LIBRARY_PATH` tells the Linux loader where to find the libraries at runtime.
+Keep the latter in your application/container environment. Adding the FFmpeg
+executable to `PATH` is not enough. If libclang is outside the loader's search
+paths, also set `LIBCLANG_PATH` to its library directory.
+
+The example uses a GPL-enabled conda-forge build, unlike the minimal LGPL release
+build. Its additional codecs, dependencies and licensing apply to your environment.
+Review [`licenses/README.md`](../licenses/README.md) before redistributing a binary
+built against a different FFmpeg configuration.
+
+For development against the same prefix:
+
+```sh
+uv sync --group dev
+uv run maturin develop --locked --uv
+```
+
+Do not reuse an existing `dist/` wheel while verifying this path: it may contain the
+bundled release libraries. To verify library loading for a source-built install:
+
+```sh
+uv run --no-sync python - <<'PY'
+from tensorcodec.decoders import VideoDecoder
+with VideoDecoder("video.mp4") as decoder:
+    print(decoder.get_frame_at(0).data.shape)
+PY
+```
+
+The native extension build and playback contracts run against prebuilt FFmpeg
+7.1.1 in ordinary CI. The published-wheel tests separately verify decoding with
+no external FFmpeg library installation. Configuration-specific outputs can differ
+within the color-conversion tolerances described in the
+[compatibility contract](compatibility.md).

{tensorcodec-0.1.0 → tensorcodec-0.1.2}/native/Cargo.lock

@@ -455,7 +455,7 @@ checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
 
 [[package]]
 name = "tensorcodec-native"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "ffmpeg-sys-next",
  "numpy",