tensorcodec 0.1.0__tar.gz

tensorcodec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suhwan Choi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tensorcodec-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: tensorcodec
+Version: 0.1.0
+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
+
+# TensorCodec
+
+**TorchCodec-style video and audio decoding, without PyTorch.**
+
+- Use the CPU decoder API and playback rules of **TorchCodec 0.17.0**.
+- Get **NumPy arrays** instead of `torch.Tensor`.
+- Install **NumPy + TensorCodec**. No Torch, PyAV, or FFmpeg CLI at runtime.
+
+The goal is predictable frame selection, timestamps and audio ranges with a small
+runtime dependency set. This is a **CPU decoding subset**, not the entire
+TorchCodec package. It does not promise a speedup over PyAV or TorchCodec.
+
+## What is available?
+
+| Capability | TorchCodec 0.17.0 | TensorCodec 0.1.0 |
+| --- | --- | --- |
+| Python runtime dependency | PyTorch | NumPy |
+| Output arrays | `torch.Tensor` | `numpy.ndarray`; array interface + DLPack |
+| Video index/slice/batch access | Supported | Supported |
+| Playback time/range access | Supported | Supported |
+| CFR, VFR, offset PTS, B-frames | Supported | Tested |
+| Request ordering and duplicates | Preserved | Preserved |
+| Exact / approximate seeking | Supported | Supported; exact is the default |
+| NCHW / NHWC RGB | Supported | Supported |
+| uint8 / float32 video | Supported | Supported for SDR |
+| FPS sampling, custom frame mappings | Supported | Supported |
+| Audio ranges, resampling, channel mixing | Supported | Supported; float32 output |
+| Paths, URLs, bytes, seekable file objects | Supported | Supported |
+| Encoded tensor input | `torch.Tensor` | 1-D uint8 NumPy arrays |
+| CUDA decoding | Supported | **Not implemented** |
+| Decoder transforms | Supported | **Not implemented** |
+| HDR inputs / display rotation | Supported | **Rejected explicitly** |
+| Other modules, including samplers/encoders | Available | **Outside the initial scope** |
+
+### Compatibility means
+
+- Match the supported CPU API's frame selection, ordering, timing and metadata.
+- Check behavior independently **and** against pinned TorchCodec 0.17.0.
+- Allow color-conversion rounding: at most 1 uint8 unit or 1/65535 for float32
+  in the tested cases. Do not claim identical pixels across every FFmpeg build.
+- Accept empty index lists, including the case affected by the reference's
+  empty-list dtype inference bug.
+
+Details and the tested scope: [compatibility contract](docs/compatibility.md).
+
+### Current limits
+
+- Binary wheels: **Linux x86_64, glibc 2.28+, CPython 3.10+**.
+- No macOS or Windows wheels yet; free-threaded Python is not a release target.
+- Exact video seeking scans packet timestamps when opening the decoder.
+- Audio range queries currently decode from the beginning; late ranges can be
+  expensive.
+- NumPy return types require caller changes where code expects Torch tensors.
+- Historical avdec benchmarks are not TensorCodec performance results.
+
+## Install
+
+```sh
+python -m pip install tensorcodec
+```
+
+Linux wheels bundle shared FFmpeg libraries. Source builds need Rust, libclang
+and FFmpeg 7 development headers/libraries.
+
+Before the first PyPI upload, install a local wheel:
+
+```sh
+python -m pip install dist/tensorcodec-*.whl
+```
+
+## Use
+
+```python
+from tensorcodec.decoders import VideoDecoder, AudioDecoder
+
+with VideoDecoder("video.mp4") as video:
+    frame = video.get_frame_played_at(1.25)  # frame playing at this time
+    print(frame.data.shape)                 # CHW NumPy array
+    batch = video.get_frames_at([4, 0, 4])   # order and duplicates preserved
+    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)
+    print(samples.data.shape)               # channels × samples, float32
+```
+
+Decoded arrays keep their storage after the decoder closes. Input file objects
+remain caller-owned.
+
+## Implementation
+
+| Layer | Responsibility |
+| --- | --- |
+| Python | Public API, frame/time selection, validation, result objects |
+| Rust + PyO3 | FFmpeg handles, seeking/decoding, color conversion, resampling |
+| FFmpeg | Codec and container implementations |
+
+A batch crosses the Python/Rust boundary once. Native decoding releases the GIL.
+
+## Development and verification
+
+```sh
+# Requires Rust, Clang/libclang, pkg-config and FFmpeg 7 development libraries.
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install numpy pytest ruff 'maturin>=1.8,<2'
+maturin develop --locked
+
+# Reference dependencies are for tests only.
+python -m pip install torch==2.14.1 torchcodec==0.17.0 \
+  --index-url https://download.pytorch.org/whl/cpu
+pytest tests/test_video_contract.py tests/test_audio_contract.py --backend torchcodec
+pytest --compare
+```
+
+Tests generate fixtures with FFmpeg/ffprobe and Python's `wave` module.
+`--compare` requires the exact oracle version; otherwise differential tests skip.
+The old avdec decoder and tests are never executed.
+
+- [Playback rules](docs/playback_semantics.md)
+- [Release builds and PyPI publishing](docs/releasing.md)
+- [Native dependency licenses and source/build notices](licenses/README.md)
+
+TensorCodec's own code is MIT licensed.
+

tensorcodec-0.1.0/README.md

@@ -0,0 +1,124 @@
+# TensorCodec
+
+**TorchCodec-style video and audio decoding, without PyTorch.**
+
+- Use the CPU decoder API and playback rules of **TorchCodec 0.17.0**.
+- Get **NumPy arrays** instead of `torch.Tensor`.
+- Install **NumPy + TensorCodec**. No Torch, PyAV, or FFmpeg CLI at runtime.
+
+The goal is predictable frame selection, timestamps and audio ranges with a small
+runtime dependency set. This is a **CPU decoding subset**, not the entire
+TorchCodec package. It does not promise a speedup over PyAV or TorchCodec.
+
+## What is available?
+
+| Capability | TorchCodec 0.17.0 | TensorCodec 0.1.0 |
+| --- | --- | --- |
+| Python runtime dependency | PyTorch | NumPy |
+| Output arrays | `torch.Tensor` | `numpy.ndarray`; array interface + DLPack |
+| Video index/slice/batch access | Supported | Supported |
+| Playback time/range access | Supported | Supported |
+| CFR, VFR, offset PTS, B-frames | Supported | Tested |
+| Request ordering and duplicates | Preserved | Preserved |
+| Exact / approximate seeking | Supported | Supported; exact is the default |
+| NCHW / NHWC RGB | Supported | Supported |
+| uint8 / float32 video | Supported | Supported for SDR |
+| FPS sampling, custom frame mappings | Supported | Supported |
+| Audio ranges, resampling, channel mixing | Supported | Supported; float32 output |
+| Paths, URLs, bytes, seekable file objects | Supported | Supported |
+| Encoded tensor input | `torch.Tensor` | 1-D uint8 NumPy arrays |
+| CUDA decoding | Supported | **Not implemented** |
+| Decoder transforms | Supported | **Not implemented** |
+| HDR inputs / display rotation | Supported | **Rejected explicitly** |
+| Other modules, including samplers/encoders | Available | **Outside the initial scope** |
+
+### Compatibility means
+
+- Match the supported CPU API's frame selection, ordering, timing and metadata.
+- Check behavior independently **and** against pinned TorchCodec 0.17.0.
+- Allow color-conversion rounding: at most 1 uint8 unit or 1/65535 for float32
+  in the tested cases. Do not claim identical pixels across every FFmpeg build.
+- Accept empty index lists, including the case affected by the reference's
+  empty-list dtype inference bug.
+
+Details and the tested scope: [compatibility contract](docs/compatibility.md).
+
+### Current limits
+
+- Binary wheels: **Linux x86_64, glibc 2.28+, CPython 3.10+**.
+- No macOS or Windows wheels yet; free-threaded Python is not a release target.
+- Exact video seeking scans packet timestamps when opening the decoder.
+- Audio range queries currently decode from the beginning; late ranges can be
+  expensive.
+- NumPy return types require caller changes where code expects Torch tensors.
+- Historical avdec benchmarks are not TensorCodec performance results.
+
+## Install
+
+```sh
+python -m pip install tensorcodec
+```
+
+Linux wheels bundle shared FFmpeg libraries. Source builds need Rust, libclang
+and FFmpeg 7 development headers/libraries.
+
+Before the first PyPI upload, install a local wheel:
+
+```sh
+python -m pip install dist/tensorcodec-*.whl
+```
+
+## Use
+
+```python
+from tensorcodec.decoders import VideoDecoder, AudioDecoder
+
+with VideoDecoder("video.mp4") as video:
+    frame = video.get_frame_played_at(1.25)  # frame playing at this time
+    print(frame.data.shape)                 # CHW NumPy array
+    batch = video.get_frames_at([4, 0, 4])   # order and duplicates preserved
+    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)
+    print(samples.data.shape)               # channels × samples, float32
+```
+
+Decoded arrays keep their storage after the decoder closes. Input file objects
+remain caller-owned.
+
+## Implementation
+
+| Layer | Responsibility |
+| --- | --- |
+| Python | Public API, frame/time selection, validation, result objects |
+| Rust + PyO3 | FFmpeg handles, seeking/decoding, color conversion, resampling |
+| FFmpeg | Codec and container implementations |
+
+A batch crosses the Python/Rust boundary once. Native decoding releases the GIL.
+
+## Development and verification
+
+```sh
+# Requires Rust, Clang/libclang, pkg-config and FFmpeg 7 development libraries.
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install numpy pytest ruff 'maturin>=1.8,<2'
+maturin develop --locked
+
+# Reference dependencies are for tests only.
+python -m pip install torch==2.14.1 torchcodec==0.17.0 \
+  --index-url https://download.pytorch.org/whl/cpu
+pytest tests/test_video_contract.py tests/test_audio_contract.py --backend torchcodec
+pytest --compare
+```
+
+Tests generate fixtures with FFmpeg/ffprobe and Python's `wave` module.
+`--compare` requires the exact oracle version; otherwise differential tests skip.
+The old avdec decoder and tests are never executed.
+
+- [Playback rules](docs/playback_semantics.md)
+- [Release builds and PyPI publishing](docs/releasing.md)
+- [Native dependency licenses and source/build notices](licenses/README.md)
+
+TensorCodec's own code is MIT licensed.

tensorcodec-0.1.0/docs/compatibility.md

@@ -0,0 +1,58 @@
+# TensorCodec compatibility contract
+
+Reference: **TorchCodec 0.17.0**, CPU audio/video decoding. Python operations,
+frame selection, ordering, timestamps, durations, stream selection and metadata
+are tested independently and against this pinned version. Native decoding uses
+FFmpeg; arrays are returned as NumPy instead of torch.Tensor.
+
+## Public surface
+
+- `tensorcodec.Frame`, `FrameBatch`, `AudioSamples`
+- `tensorcodec.decoders.VideoDecoder`: constructor, `len`, integer/slice indexing,
+  `get_frame_at`, `get_frames_at`, `get_frames_in_range`, `get_frame_played_at`,
+  `get_frames_played_at`, `get_frames_played_in_range`, metadata, stream_index.
+  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.
+  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,
+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.
+
+## Playback rules
+
+Timestamp retrieval selects frame i for `pts[i] <= t < pts[i+1]`; the last frame
+ends at the content-derived stream end. This does not imply that returned frame
+duration equals the next PTS gap. In 0.17.0 the implementation of time ranges
+includes the frame playing at start, even when its PTS is before start. It excludes
+the frame starting exactly at stop. This differs from the reference docstring;
+we follow the tested implementation, with empty output when start equals stop.
+Indices preserve input order and duplicates. Shape/layout, bounds, defaults and
+exception classes follow the reference, including its restrictions on slice steps.
+
+## Tests first
+
+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:
+
+```sh
+pytest tests/test_video_contract.py tests/test_audio_contract.py --backend torchcodec
+pytest --compare
+```
+
+Comparisons check timing separately from pixels. One uint8 RGB unit or 1/65535
+for float32 RGB is allowed for conversion rounding; frame identities have independent
+expectations. Tests requiring the oracle must fail on a missing/wrong reference
+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.

tensorcodec-0.1.0/docs/playback_semantics.md

@@ -0,0 +1,24 @@
+# TensorCodec playback semantics
+
+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.
+
+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
+time. The native decoder seeks to a key frame and decodes forward to the exact
+PTS, restoring caller order and duplicates. It fails if the mapped frame cannot
+be found rather than silently returning another frame.
+
+Approximate seeking derives indices and time selection from header FPS. It does
+not provide the content-derived VFR guarantees of exact mode.
+
+For a time range, include the frame playing at its start and exclude a frame
+starting at its stop. With `fps`, sample a uniform grid starting at the requested
+start and return grid timestamps/durations, matching the reference implementation.
+Packet duration and the next frame's PTS gap are distinct quantities.
+
+Audio decoding preserves codec priming and encoder delay, then resamples with
+FFmpeg. Range selection rounds offsets at the output sample rate. Current audio
+queries replay decoding from the beginning; this trades speed for deterministic
+range output and is a future optimization boundary.

tensorcodec-0.1.0/docs/releasing.md

@@ -0,0 +1,60 @@
+# Publishing TensorCodec
+
+Release version: `0.1.0`. Distribution and import name: `tensorcodec`.
+The first binary release targets Linux x86_64, glibc 2.28+, CPython 3.10+.
+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.
+
+## One-time account setup
+
+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:
+
+   | 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.
+
+## Release
+
+Run the **Publish to PyPI** workflow on `main`. It builds the portable Linux wheel
+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.0/ before reporting
+success. Verify a fresh `pip install tensorcodec==0.1.0` and a decode without
+Torch/PyAV. 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/manylinux_2_28_x86_64` 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 the 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 still tests the installed repaired wheel. The fixture CLI
+  can be FFmpeg 6 or 7; fixtures explicitly remove auxiliary sentinel packets.