celux 0.7.3

Lightspeed video decoding directly into tensors!

CeLux

CeLux is a high‑performance Python library for video processing, leveraging the power of libav(FFmpeg). It delivers some of the fastest decode times for full‑HD videos globally, enabling efficient video decoding directly into PyTorch tensors—and now simplified, one‑call audio muxing straight from a tensor. At present, CeLux offers limited, but functional encoding support.

The name CeLux comes from the Latin words celer (speed) and lux (light), reflecting its commitment to speed and efficiency.

Check out the latest changes

[0.7.3] - 2025-08-17

Added

• New VideoReader.frame_at(pos) method for random access:
  • Pass a float for timestamp in seconds.
  • Pass an int for frame index (0-based).
• Uses a separate decoder internally, so sequential iteration (read_frame, __iter__) isn’t interrupted.
• Returns HWC tensors with the same dtype rules as 0.7.2:
  • uint8 for 8-bit sources
  • uint16 for 10-bit and higher

Example

from celux import VideoReader

vr = VideoReader("input.mp4")

frame_ts = vr.frame_at(12.34)   # by timestamp
frame_idx = vr.frame_at(1000)   # by frame index

print(frame_ts.shape, frame_ts.dtype)
print(frame_idx.shape, frame_idx.dtype)

📚 Documentation

• 📝 Changelog
• 🍎 Audio & Muxing Guide
• 📊 Benchmarks

🚀 Features

• ⚡ Ultra‑Fast Video Decoding: Lightning‑fast decode times for full‑HD videos using hardware acceleration.
• 🔗 Direct Decoding to Tensors: Frames come out as PyTorch tensors (HWC layout by default).
• 🔊 Simplified Audio Encoding: One call to encode_audio_tensor() streams raw PCM into the encoder.
• 🔄 Easy Integration: Drop‑in replacement for your existing Python + PyTorch workflows.

Q: How do I report a bug or request a feature?

A: Open an issue on our GitHub Issues with as much detail as you can (FFmpeg version, platform, repro steps, etc.).

⚡ Quick Start

pip install celux

FOR LINUX

• Download the most recent release (.whl)

pip install ./*.whl

from celux import VideoReader
import torch

reader = VideoReader("/path/to/input.mp4")
with reader.create_encoder("/path/to/output.mp4") as enc:
    # 1) Re‑encode video frames
    for frame in reader:
        enc.encode_frame(frame)

    # 2) If there’s audio, hand off the entire PCM in one go:
    if reader.has_audio:
        pcm = reader.audio.tensor().to(torch.int16)
        enc.encode_audio_frame(pcm)

print("Done!")

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.

🙏 Acknowledgments

• FFmpeg: The backbone of video processing in CeLux.
• PyTorch: For tensor operations and CUDA support.
• Vcpkg: Simplifies cross‑platform dependency management.
• @NevermindNilas: For assistance with testing, API suggestions, and more.

🚤 Roadmap

• Support for Additional Codecs:
  • Expand hardware‑accelerated decoding/muxing support to VP9, AV1, etc.
• Audio Filters & Effects:
  • Add simple audio‑only filters (gain, resample, stereo panning).
• Advanced Muxing Options:
  • Expose more container parameters (subtitle tracks, chapters).
• Cross‑Platform CI:
  • Ensure Windows, macOS, Linux builds all pass full audio+video tests. (My current focus is windows, would love help getting linux side working as well!)