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

🚀 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!)

Metadata

Release files for celux 0.7.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for celux 0.7.3
File	Interpreter	ABI	Platform	Reset
celux-0.7.3-cp313-cp313-win_amd64.whl 11.2 MB Aug 17, 2025	CPython 3.13	CPython 3.13	Windows x86-64	Details

Release files / celux-0.7.3-cp313-cp313-win_amd64.whl

Download URL	celux-0.7.3-cp313-cp313-win_amd64.whl
Size	11.2 MB
Tags	CPython 3.13 Windows x86-64
SHA-256 checksum How to use checksums	`cfce154d0ccfa8334ea087c850550f229b0e279fd808829e315783f8ef1768dd`
BLAKE2b-256 checksum How to use checksums	`0cbcb2dbb43b3d613fd96f369fe311aac7d6c26ccb726e014ec3f3489a9c27a8`
Upload date	Aug 17, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.9.23`