Metadata-Version: 2.4
Name: oximedia
Version: 0.1.6
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Sound/Audio
Summary: Python bindings for OxiMedia - Royalty-free multimedia processing library
Home-Page: https://github.com/cool-japan/oximedia
Author: COOLJAPAN OU (Team Kitasan)
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Source Code, https://github.com/cool-japan/oximedia

# OxiMedia Python Bindings

**Status: [Stable]** | Version: 0.1.6 | Tests: 838 | Updated: 2026-04-26

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

Part of the [oximedia](https://github.com/cool-japan/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)
- **Zero-copy operations** where possible
- **Thread-safe** Python bindings

## Installation

### From PyPI

```bash
pip install oximedia
```

### From Source

```bash
cd crates/oximedia-py
pip install maturin
maturin develop
```

## Quick Start

### Video Decoding

```python
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

```python
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

```python
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

```python
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

```python
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()
```

## 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

Apache-2.0 — Copyright 2024-2026 COOLJAPAN OU (Team Kitasan)

## 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.

