Split into tensorcodec (pure Python) and tensorcodec-av; BMP; OpenCV >=4.12

[MilkClouds]

Image codecs only need OpenCV, but tensorcodec 0.2.0 was one maturin package. Its import loaded the Rust extension, and installing on Windows or Intel macOS fell back to an sdist that needs Rust and FFmpeg. This PR splits the project into two distributions, the way pydantic and pydantic-core are split. It also adds BMP to decode_image and replaces the OpenCV bound with a measured one. Versions go to 0.3.0, since 0.2.0 is already published as a single package. Nothing is released by this PR.

Size: +829/−309 across 40 files. Most of it is moved workflow steps, the copied av/LICENSE (+204) and tests; the runtime code change is about 50 lines.

Packaging split

PyPI project	Contents	Build backend	Distributions	License metadata
tensorcodec (root pyproject.toml)	Python API, image decoders/encoders (import tensorcodec)	hatchling	py3-none-any wheel, sdist	Apache-2.0, LICENSE only, OS Independent
tensorcodec-av (av/pyproject.toml, new)	Only the Rust/FFmpeg extension (import tensorcodec_av)	maturin	abi3 manylinux x86_64/aarch64 and macOS 14 arm64 wheels, sdist	Apache-2.0 AND LGPL-3.0-or-later AND BSD-2-Clause; the FFmpeg/dav1d/OpenSSL notices moved to av/licenses/

tensorcodec-av (the audio/video decoders; images live in tensorcodec) is unregistered on PyPI as of 2026-10-05. The Rust package lives in av/; the extension module is tensorcodec_av._av.

• Dependency. tensorcodec requires tensorcodec-av==<same version> behind the marker platform_python_implementation == 'CPython' and ((sys_platform == 'linux' and platform_machine in {x86_64, aarch64}) or (sys_platform == 'darwin' and platform_machine == 'arm64')).

  • So pip install tensorcodec behaves as before where tensorcodec-av wheels exist.
  • On Windows, Intel macOS, PyPy and 32-bit ARM it installs pure Python, with no Rust toolchain needed.
  • There is no native extra. Where the marker applies it would do nothing; elsewhere it would only trigger the same source build as installing tensorcodec-av directly. The docs say to install tensorcodec-av==<same version> explicitly to build it from source (needs Rust and FFmpeg 7).
  • The marker does not compare platform_release. pip's vendored packaging 22–25 raises InvalidVersion on Linux kernel strings like 6.8.0-azure; I verified this with packaging 22.0/23.2/24.2/25.0, and a test guards it.

• Lazy import and skew check. VideoDecoder and AudioDecoder import tensorcodec_av when constructed.

  • If it is missing, they raise an ImportError that explains which platforms have tensorcodec-av wheels.
  • The extension now exports __version__ (CARGO_PKG_VERSION). A tensorcodec-av whose version differs from tensorcodec is rejected with an explicit message.

• Lockstep. tests/test_versions.py (runs in every CI and release job) requires pyproject.toml, the pin, av/Cargo.toml (the tensorcodec-av version source), av/Cargo.lock and tensorcodec.__version__ to agree. It also checks that av/LICENSE equals LICENSE and that the marker matches the published wheel platforms.

• Workflows: one reusable workflow per distribution. CI and the release call the same two workflows:

  Workflow	Jobs	Artifacts
  build-python.yml (renamed from pure-python-wheel.yml)	build: tensorcodec wheel and sdist, python -m build + twine check --strict. test-without-av: installs tensorcodec[images] with --no-index on windows-2025 (Python 3.12, latest OpenCV = 5.0) and macos-15-intel (Python 3.10, OpenCV 4.12.0.88, the lower bound), then runs the image, encoder, optional-native and version tests	dist-python
  build-av.yml (replaces macos-wheels.yml and the inline Linux jobs in publish.yml)	linux (x86_64, aarch64): manylinux2014 via maturin-action with the existing native-deps cache, size check, glibc 2.17 Python 3.10/3.13 runtime check, contract and --compare oracle tests. macos (arm64): build, delocate, full pytest, clean 3.10/3.13 venvs. sdist. The wheel jobs validate against the dist-python wheel, so callers run build-python.yml first	dist-av-linux-{x86_64,aarch64}, dist-av-macos-arm64, dist-av-sdist, wheel-size-linux-*
  ci.yml	python → av, plus test (development build against conda-forge FFmpeg, Clippy, contract and --compare)
  publish.yml	python → av → publish (tensorcodec-av first, so the exact pin never points at a missing release, then tensorcodec) → update-size-docs (now measures tensorcodec-av)

  • ci.yml runs av on every push and PR, so a release commit has already passed the same Linux and macOS release builds.
  • With the native-deps caches warm, each Linux job takes about 3 minutes.
  • source.yml is removed: publish.yml --field publish=false produces the same artifacts.
  • The animated-GIF fixture uses a numbered input sequence, because Windows FFmpeg has no glob pattern support. Fixture FFmpeg comes from conda-forge, because Homebrew's build lacks libaom. The Windows OpenCV wheel has no AVIF decoder, so that test checks for the explicit error there.

• Removed. scripts/build_pure_wheel.py.

• Docs. README, docs/releasing.md (two-project release, pending trusted publisher for tensorcodec-av, version-bump steps, recovery if the second upload fails), docs/system_ffmpeg.md, docs/images.md and docs/package_size.md.

Upgrade path: installing the 0.3.0 tensorcodec wheel over the published 0.2.0 removes tensorcodec/_native.abi3.so and tensorcodec.libs (checked locally). On marker platforms, the dependency then installs tensorcodec-av.

Known limitation (deliberate): environment markers cannot detect musl, free-threaded CPython or macOS older than 14. On those platforms installers still try tensorcodec-av and fall back to its sdist, which is what happened before the split. The README documents pip install --no-deps tensorcodec numpy for image-only use there. The adversarial review flags this; avoiding it would require making native opt-in everywhere, which changes pip install tensorcodec on the supported platforms.

BMP

• decode_image detects BM and decodes through cv2.imdecode, losslessly.
• Alpha matches Pillow: only 32-bit BI_BITFIELDS files with a nonzero alpha mask keep it.
• There is no decode_bmp, matching TorchCodec's function set.
• TIFF is not added. OpenCV premultiplies unassociated alpha, drops gray+alpha, and turns CMYK into RGBA, so lossless decoding cannot be promised. This is documented.

OpenCV bound: >=4.12, no upper cap

Image decoder/encoder/optional-AV tests (152 with TorchCodec 0.17.0 --compare). One throwaway venv per version; Linux, Python 3.12, PyPI opencv-python-headless.

Version	Result
4.8.0.76, 4.9.0.80	cv2 does not import with NumPy 2
4.10.0.84	everything passes except GIF (non-oracle run)
4.11.0.86	124 passed, 28 failed: all GIF and AVIF (OpenCV could not decode)
4.12.0.88	152 passed
4.13.0.92	152 passed
5.0.0.93	152 passed

• OpenCV's changelog lists the GIF decoder in 4.11 (#25691), but the 4.11 PyPI wheels report GIF: NO and AVIF: NO in cv2.getBuildInformation(). 4.12 reports both as YES.
• So 4.12 is the lowest version where the full suite passes. JPEG, PNG, WebP (including animation and orientation) and BMP already pass on 4.10.
• The runtime check in _opencv.py, the images extra and the dev group now use >=4.12, without the <5 cap. The reason is recorded at the check and in docs/images.md.

Validation

• CI (final commit a9f9e1b, all green), including the Linux release builds:
  • av / linux x86_64 and aarch64: cache hit, tensorcodec_av-0.3.0 wheel built, glibc 2.17 runtime checks, 67 contract and 462 --compare tests passed.
  • av / macos arm64: 316 passed.
  • av / sdist, python / build, and python / test-without-av on Windows and Intel macOS.
  • test.
• Local:
  • Built tensorcodec wheel and sdist: the wheel has only Python files and LICENSE. A wheel rebuilt from the sdist works, and the version tests pass in the extracted sdist.
  • tensorcodec-av sdist via maturin contains only the Rust sources and the notices.
  • Fresh copy-mode venvs (no site-packages edits): image tests pass on OpenCV 4.12 and 5.0, both with --compare.
• Codex review (review --scope branch, final state after the trim): no actionable regressions. Earlier rounds found the reuse of version 0.2.0, the platform_release marker crash and the sdist missing native/; all three are fixed.
• Adversarial review: remaining finding is the known limitation above.

Release steps (not done here)

1. On PyPI, add tensorcodec-av as a pending trusted publisher (same repository, publish.yml, environment pypi).
2. Merge, then run Publish to PyPI on main. A --field publish=false dry run is possible first.
3. Verify that pip install tensorcodec==0.3.0 pulls tensorcodec-av==0.3.0 on Linux and macOS arm64, and installs pure Python on Windows.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YAijSnAE4aAjuS1EcCTwqS