OxiMedia Python Bindings

Status: [Stable] | Version: 0.2.0 | Tests: extensively tested | Updated: 2026-07-14

Python bindings for OxiMedia, a royalty-free multimedia processing library written in Rust.

Part of the oximedia workspace — a comprehensive pure-Rust media processing framework.

Features

Video Codecs: AV1 (encode/decode), VP9 (decode), VP8 (decode)
Audio Codecs: Opus (encode/decode), Vorbis (decode), FLAC (decode)
Container Formats: Matroska/WebM (demux/mux), Ogg (demux/mux), FLAC (demux), WAV (demux)
Filter Graph: Scale, crop, volume, normalize filter bindings
Pipeline: Multi-stage media pipeline builder
Batch Processing: Batch transcoding operations
Progress Tracking: Long-running operation progress tracking
Media Probing: Media format and stream information queries
Metadata: Typed metadata field access
Error Types: Structured error types with categories and severity
Format Information: Container capabilities and codec queries
Media Hashing: Content hashing and fingerprinting
ml — PyO3 bindings for oximedia-ml typed pipelines (SceneClassifier, ShotBoundaryDetector, AestheticScorer, ObjectDetector, FaceEmbedder)
neural — PyO3 bindings for oximedia-neural tensor and inference models (Tensor, SceneClassifier, ThumbnailRanker, SrUpscaler, FeatureExtractor)
analytics — PyO3 bindings for oximedia-analytics viewer-session tracking, engagement scoring, and attention heatmaps (ViewerSession, SessionMetrics, ContentEngagementScore)
cache — PyO3 bindings for oximedia-cache's LRU cache (LruCache, CacheStats)
Zero-copy operations where possible
Thread-safe Python bindings

Installation

From PyPI

pip install oximedia

From Source

cd crates/oximedia-py
pip install maturin
maturin develop

Quick Start

Video Decoding

import oximedia

# Create AV1 decoder
decoder = oximedia.Av1Decoder()

# Send compressed packet
decoder.send_packet(packet_data, pts=0)

# Receive decoded frame
frame = decoder.receive_frame()
if frame:
    print(f"Frame: {frame.width}x{frame.height}")
    y_plane = frame.plane_data(0)  # Y plane
    u_plane = frame.plane_data(1)  # U plane
    v_plane = frame.plane_data(2)  # V plane

Video Encoding

import oximedia

# Create encoder configuration
config = oximedia.EncoderConfig(
    width=1920,
    height=1080,
    framerate=(30, 1),
    crf=28.0,
    preset="medium",
    keyint=250
)

# Create AV1 encoder
encoder = oximedia.Av1Encoder(config)

# Encode frame
frame = oximedia.VideoFrame(1920, 1080, oximedia.PixelFormat("yuv420p"))
encoder.send_frame(frame)

# Receive encoded packet
packet = encoder.receive_packet()
if packet:
    print(f"Packet: {len(packet['data'])} bytes, keyframe={packet['keyframe']}")

Audio Decoding

import oximedia

# Create Opus decoder
decoder = oximedia.OpusDecoder(sample_rate=48000, channels=2)

# Decode packet
audio_frame = decoder.decode_packet(packet_data)

print(f"Audio: {audio_frame.sample_count} samples, {audio_frame.channels} channels")

# Get samples as float32
samples_f32 = audio_frame.to_f32()

# Get samples as int16
samples_i16 = audio_frame.to_i16()

Container Demuxing

import oximedia

# Open Matroska file
demuxer = oximedia.MatroskaDemuxer("video.mkv")
demuxer.probe()

# Get stream information
for stream in demuxer.streams():
    print(f"Stream {stream.index}: {stream.codec}")
    if stream.width:
        print(f"  Video: {stream.width}x{stream.height}")
    if stream.sample_rate:
        print(f"  Audio: {stream.sample_rate}Hz, {stream.channels} channels")

# Read packets
while True:
    try:
        packet = demuxer.read_packet()
        print(f"Packet: stream={packet.stream_index}, size={packet.size()}, "
              f"pts={packet.pts}, keyframe={packet.is_keyframe()}")
    except StopIteration:
        break

Container Muxing

import oximedia

# Create muxer
muxer = oximedia.MatroskaMuxer("output.mkv", title="My Video")

# Write header
muxer.write_header()

# Write packets
for packet in packets:
    muxer.write_packet(packet)

# Finalize
muxer.write_trailer()

Zero-Copy NumPy Access

VideoFrame.plane(i), AudioFrame.samples, and cv2_compat.Mat implement the PyO3 buffer protocol, so NumPy can wrap the underlying Rust buffer without copying:

import oximedia
import numpy as np

# Decode a video file
decoder = oximedia.Av1Decoder()
# ... feed packets, get frames ...
frame = ...  # an oximedia.VideoFrame returned by the decoder

# Zero-copy numpy view of plane 0 (Y in YUV420P)
plane0 = np.asarray(frame.plane(0))
print(plane0.shape, plane0.dtype)  # (height, width, 1) uint8

# Audio interleaved samples as a numpy view
audio = oximedia.AudioFrame(...)
samples = np.asarray(audio.samples)

Each call to plane(i) / samples returns its own buffer view, so multiple concurrent views of the same frame are safe.

Command-Line Interface

The package ships a python -m oximedia entry point (installed with the wheel — no separate console script needed):

# Probe a media file (text or JSON output)
python -m oximedia probe input.mkv
python -m oximedia probe input.mkv --json

# Transcode using a built-in preset
python -m oximedia transcode input.mkv output.webm --preset youtube-1080p
python -m oximedia transcode input.mkv output.webm --crf 28

# Quality assessment between two files
python -m oximedia quality reference.mp4 distorted.mp4 --metric all

# cv2-style colour conversion / format conversion
python -m oximedia cv2 cvt-color input.png output.png --code BGR2RGB
python -m oximedia cv2 convert input.bmp output.jpg

# Inspect available presets / codecs / version
python -m oximedia presets
python -m oximedia codecs
python -m oximedia version

Run python -m oximedia --help (or python -m oximedia <subcommand> --help) for the full argument list.

Supported Codecs

OxiMedia only supports royalty-free, patent-unencumbered codecs:

Video

AV1 - Alliance for Open Media codec (encode + decode)
VP9 - Google's royalty-free codec (decode)
VP8 - Google's earlier royalty-free codec (decode)

Audio

Opus - Modern low-latency audio codec (encode + decode)
Vorbis - Xiph.Org audio codec (decode)
FLAC - Lossless audio codec (decode)

Containers

Matroska/WebM (.mkv, .webm) — demux + mux
Ogg (.ogg, .opus, .oga) — demux + mux
FLAC (.flac) — demux
WAV (.wav) — demux

API Overview

Core Python classes:

PixelFormat, SampleFormat, ChannelLayout — Format descriptors
VideoFrame, AudioFrame — Frame data containers
EncoderConfig, EncoderPreset, Rational — Encoding configuration

Video codecs:

Av1Decoder, Av1Encoder — AV1 codec
Vp9Decoder, Vp8Decoder — VP9/VP8 decoders

Audio codecs:

OpusDecoder, OpusEncoder, OpusEncoderConfig — Opus codec
VorbisDecoder, FlacDecoder — Vorbis/FLAC decoders

Filters:

PyScaleConfig, PyCropConfig, PyVolumeConfig, PyNormalizeConfig — Filter configurations

Container:

Packet, StreamInfo — Packet and stream data
MatroskaDemuxer, OggDemuxer — Container demuxers
MatroskaMuxer, OggMuxer — Container muxers

Probe/info:

PyVideoInfo, PyAudioInfo, PyStreamInfo, PyMediaInfo — Media information

Advanced (public modules):

batch, batch_bindings — Batch processing
codec_info — Codec information queries
error_types — Structured error types
filter_bindings — Filter graph bindings
format_info — Format information
media_hash — Content hashing/fingerprinting
pipeline_bindings, pipeline_builder — Pipeline construction
progress_tracker — Progress tracking
py_config — Configuration builder
py_error — Error handling
py_metadata — Metadata access
stream_reader — Streaming reader utilities
timeline — Timeline management
transcode_options — Transcoding options
video_bindings, video_meta — Video utilities

License

Patent Protection

OxiMedia is designed to only work with royalty-free codecs. Attempting to use patent-encumbered codecs (H.264, H.265, AAC, etc.) will result in an error.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oximedia-0.2.0.tar.gz (19.9 MB view details)

Uploaded Jul 15, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

oximedia-0.2.0-cp314-cp314-win_amd64.whl (9.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.14Windows x86-64

oximedia-0.2.0-cp314-cp314-macosx_11_0_arm64.whl (7.5 MB view details)

Uploaded Jul 15, 2026 CPython 3.14macOS 11.0+ ARM64

oximedia-0.2.0-cp314-cp314-macosx_10_12_x86_64.whl (8.0 MB view details)

Uploaded Jul 15, 2026 CPython 3.14macOS 10.12+ x86-64

oximedia-0.2.0-cp313-cp313-win_amd64.whl (9.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.13Windows x86-64

oximedia-0.2.0-cp313-cp313-manylinux_2_34_x86_64.whl (8.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.13manylinux: glibc 2.34+ x86-64

oximedia-0.2.0-cp313-cp313-manylinux_2_34_aarch64.whl (7.7 MB view details)

Uploaded Jul 15, 2026 CPython 3.13manylinux: glibc 2.34+ ARM64

oximedia-0.2.0-cp313-cp313-macosx_11_0_arm64.whl (7.5 MB view details)

Uploaded Jul 15, 2026 CPython 3.13macOS 11.0+ ARM64

oximedia-0.2.0-cp313-cp313-macosx_10_12_x86_64.whl (8.0 MB view details)

Uploaded Jul 15, 2026 CPython 3.13macOS 10.12+ x86-64

oximedia-0.2.0-cp312-cp312-win_amd64.whl (9.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.12Windows x86-64

oximedia-0.2.0-cp312-cp312-manylinux_2_34_x86_64.whl (8.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.12manylinux: glibc 2.34+ x86-64

oximedia-0.2.0-cp312-cp312-manylinux_2_34_aarch64.whl (7.7 MB view details)

Uploaded Jul 15, 2026 CPython 3.12manylinux: glibc 2.34+ ARM64

oximedia-0.2.0-cp312-cp312-macosx_11_0_arm64.whl (7.5 MB view details)

Uploaded Jul 15, 2026 CPython 3.12macOS 11.0+ ARM64

oximedia-0.2.0-cp312-cp312-macosx_10_12_x86_64.whl (8.0 MB view details)

Uploaded Jul 15, 2026 CPython 3.12macOS 10.12+ x86-64

oximedia-0.2.0-cp311-cp311-win_amd64.whl (9.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.11Windows x86-64

oximedia-0.2.0-cp311-cp311-manylinux_2_34_x86_64.whl (8.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.11manylinux: glibc 2.34+ x86-64

oximedia-0.2.0-cp311-cp311-manylinux_2_34_aarch64.whl (7.7 MB view details)

Uploaded Jul 15, 2026 CPython 3.11manylinux: glibc 2.34+ ARM64

oximedia-0.2.0-cp311-cp311-macosx_11_0_arm64.whl (7.6 MB view details)

Uploaded Jul 15, 2026 CPython 3.11macOS 11.0+ ARM64

oximedia-0.2.0-cp311-cp311-macosx_10_12_x86_64.whl (7.9 MB view details)

Uploaded Jul 15, 2026 CPython 3.11macOS 10.12+ x86-64

oximedia-0.2.0-cp310-cp310-win_amd64.whl (9.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.10Windows x86-64

oximedia-0.2.0-cp310-cp310-manylinux_2_34_x86_64.whl (8.2 MB view details)

Uploaded Jul 15, 2026 CPython 3.10manylinux: glibc 2.34+ x86-64

oximedia-0.2.0-cp310-cp310-manylinux_2_34_aarch64.whl (7.7 MB view details)

Uploaded Jul 15, 2026 CPython 3.10manylinux: glibc 2.34+ ARM64

File details

Details for the file oximedia-0.2.0.tar.gz.

File metadata

Download URL: oximedia-0.2.0.tar.gz
Upload date: Jul 15, 2026
Size: 19.9 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for oximedia-0.2.0.tar.gz
Algorithm	Hash digest
SHA256	`fc96a3a5e8647de9c1c4233aca5f2427b1283666900b92a057a94e3cb01e95e7`
MD5	`1e2b9875d90beaa6b3f6ec140202beb2`
BLAKE2b-256	`4cbcfb1281229212020cf3cef899d6fae9c46c65f84e764ec3a0e326739de820`

Algorithm	Hash digest
SHA256	`e3ea6b4d01eb5a09aedcd753d0679535c12c36c5cbbe5d214b0beb6adeec58f4`
MD5	`313137b54ad2c0a84fe0494c53321841`
BLAKE2b-256	`7ea27b7d87b3d6e22a27a76cdf540db05877a95731ca182b3171703d5276fb63`

Algorithm	Hash digest
SHA256	`f9ecb17404b7967b4a191e4ed03f5ec8757742baf75a082287716137f3c811e8`
MD5	`3de04d065f7edd4051ee885a39af8339`
BLAKE2b-256	`408aba6c5c63d489e9725d6248ccbd1c3f7e69707d2f4da2b87c28c10c37227f`

Algorithm	Hash digest
SHA256	`be1cbb23b74469b9c6c63fa822aa14e6b60cee9c6aa404f55cb08995531a766e`
MD5	`a60b042bdb4e1b586031ec59111425fd`
BLAKE2b-256	`cb1e01b97901ede7e9ae5a3d382e0739778afe08c34a82c0097b8da9c730d762`

Algorithm	Hash digest
SHA256	`f41029bb7b7370e41bd64f45100b14d50cdc0cc28bf5467a0385a4f632a871d7`
MD5	`9e8a46413d612925bfddcb7628ad58a0`
BLAKE2b-256	`19e0066a6bd47f303c22ece7cb8098cd602230c7fe35833741a08be6ffbbb3db`

Algorithm	Hash digest
SHA256	`2d197a521e1aa020a5d5195dd14025ca85eae114f457681e3d695a18601f86bd`
MD5	`a8c175ac77ef3ba580201c2a9c6f23ec`
BLAKE2b-256	`cadda6573a5a5cc67ed3bf0c97e6d632b2a46c1c88efbd8574bb678bb3c7f26d`

Algorithm	Hash digest
SHA256	`4d23df8cd65be4987b7538fe6d6ef3512e3bffca56d268aa6baa544f46a2a894`
MD5	`57c1103605ed134b562bbbf5fc5d36ce`
BLAKE2b-256	`93c36704a2248f16de405d2ff418a9b1cd52d033f217e9121cf2c18f4be86a02`

Algorithm	Hash digest
SHA256	`7e4abc5eeb39408e95361637621a55cfe1c52e25f8e0431c90d3b4b7eb852290`
MD5	`0812659ebd38134978cbf2c684f08c3d`
BLAKE2b-256	`f729e73fa4638bfe18e4412b139438a949341ae38ffa81acc02798fa2eb3a875`

Algorithm	Hash digest
SHA256	`23ca8bb6d82672fc3addb5cefd4289a239dc18de3937993764b65bde4890a919`
MD5	`9ff63d91ddf1621f40372fc6e6259c59`
BLAKE2b-256	`37aa192ab817b9f044995d44dba32d1c288a5e716286512372a4197ec2483567`

Algorithm	Hash digest
SHA256	`265d908244cc96c49f4194af586123e6ec063b0f2b5a81b4c0da5cc19ed7a917`
MD5	`2604b53ff5b56892b4721426abf9035b`
BLAKE2b-256	`8955fed7f0a99b0afb1734b2a9f550f94bc3f884b1b657a5dee7c3655bb3f7ca`

Algorithm	Hash digest
SHA256	`e245f92fc242f981f71022593c5ac441cfb169cd42ce7f5f6b3045a4881163db`
MD5	`267a0533834901bde86bbac33166699d`
BLAKE2b-256	`1a86d9853f669ed532641168ad837d48a0715f450417ec605a057d3720b22b0b`

Algorithm	Hash digest
SHA256	`b72484831000baf0b187ec28c7b40b49be6816e38b8b1d4b5372759bdd5d4833`
MD5	`f717dc3be360ec052b92549b3375c40e`
BLAKE2b-256	`79de192958d9154132b2c3e40824fddae160f000f4b3fd5510aa588f6d54366d`

Algorithm	Hash digest
SHA256	`2de60f97a06f3e8a3995fdb6dab9e47d18d0899f6d1dc84fd341f1586c646c18`
MD5	`1ba25da9855fe55dbee4c326e057fad1`
BLAKE2b-256	`1a377b96aef7125659ca764bc756252dba1c2c129cf6227a0e012cc92d877de5`

Algorithm	Hash digest
SHA256	`a40ebbbbe79bf617a6ad6da20dd50692f620eaf69667cedd8ec2a44fa1c67c50`
MD5	`5e4fd9668b4706d8ca9233cc835460db`
BLAKE2b-256	`3b37da73e40813ee326b9e5f16296f815d5ead8142210dbf0600a1358c73f593`

Algorithm	Hash digest
SHA256	`2e0eacbb18078aa12f175a12f40c36418e114631d5f7e26cb1f3cea80079591c`
MD5	`2389b83cf11f59d1c574fcf0affb7b09`
BLAKE2b-256	`8e3dce8fc9ae25e4bbba786b4a95f6784194722a43ffe67a344910ab075a612f`

Algorithm	Hash digest
SHA256	`6af61961a1a8e09743592a22045b71f81db6c5c49a9ee56085b9cf6da423b8ea`
MD5	`ab8b2127e6352bb3443c3d5bb7736f0d`
BLAKE2b-256	`b30adbf80ca6a6e811ae85c85fb9043b84dad97e78863dce57263bf5a923d532`

Algorithm	Hash digest
SHA256	`48fa954cd1f8ef6ca84148db7acb2df02c2ee7c99ff1b140b1417d8543f25467`
MD5	`ebb53b46c8376f6ea41c05fc24ce0134`
BLAKE2b-256	`3edbd180cf3074e26a6485bddf780256968a661367ca7d411e48c61da0b19ac0`

Algorithm	Hash digest
SHA256	`765d512adb1efd03f725c38e0503792060d342f4415f9be1bdb39dd06dee9bf7`
MD5	`9820a3717f1a561ddc027f0772956e05`
BLAKE2b-256	`16ce84a5c6df35851b1993a86ce18247e561a685e324765f2e6aa62aafad886c`

Algorithm	Hash digest
SHA256	`153f4562cc388b7054791717cbfa0791336b5850ca0008a83fc94a3bfdae7643`
MD5	`ba77af70093c9729d28eed461b1b0f7d`
BLAKE2b-256	`0d370cb0c8d20dc8e57d83e9aedaf0726d0224feaecf0ad5b92b995263e048c5`

Algorithm	Hash digest
SHA256	`f601d4a7b1f3af384e70c1139811bd9098ff73ad3ef81b6af64198527ac20d50`
MD5	`2dee346f475a54aa3ba30037fea118e1`
BLAKE2b-256	`033fbbcfcff16df2885b15876b05821724de47a3e75110a16a7eb3ccbe0c6de2`

Algorithm	Hash digest
SHA256	`cfffd45069b5998314441090e37348aef8c2188f295a242f3f82d7ec2f57a747`
MD5	`173c844a929b52348b879a5c7aeca237`
BLAKE2b-256	`f0b73878f4410aabaf7e418acb24e2d4d876cabfab375eb5d8fbae28d4f16c5f`

oximedia 0.2.0

OxiMedia Python Bindings

Features

Installation

From PyPI

From Source

Quick Start

Video Decoding

Video Encoding

Audio Decoding

Container Demuxing

Container Muxing

Zero-Copy NumPy Access

Command-Line Interface

Supported Codecs

Video

Audio

Containers

API Overview

License

Patent Protection

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Algorithm	Hash digest
SHA256	`5fc60ab5874bf8a5a7e7ba0ac3d837b229b37456056d98266d25e6a780bfd398`
MD5	`ca60d5f474c7c852ebb649a72359bf77`
BLAKE2b-256	`b5b6e3fad26beffa219593ff94ea1206efb64ac79f7a311aec4bc7461248322f`