ruopus Documentation
====================
**ruopus** is a pure-Rust implementation of the `Opus audio codec (RFC 6716)
<https://www.rfc-editor.org/rfc/rfc6716>`_ with first-class Python/NumPy interop.
PCM crosses the Rust/Python boundary as NumPy arrays shaped ``(frames, channels)``,
moved out of Rust without an extra copy. The GIL is released for all encode/decode
operations.
Features
--------
**Encoding:**
- **Three encode paths**: automatic mode selection (SILK/hybrid/CELT), forced CELT, forced SILK, or hybrid
- **Full encoder control**: complexity, bitrate (CBR/VBR), DTX, in-band FEC, bandwidth, signal hint, application profile
- **Ogg Opus output**: single-call convenience for writing complete Ogg Opus files
**Decoding:**
- **float32 and int16 output**: ``decode_packet`` / ``decode_packet_i16``
- **Packet loss concealment**: ``decode_lost`` extrapolates the last pitch period
- **In-band FEC recovery**: ``decode_fec`` reconstructs a lost frame from its successor
- **Ogg Opus input**: demuxing, pre-skip removal, end trimming, and output gain
**Packet Introspection:**
- **TOC parsing**: mode, bandwidth, frame size, channel count from the single header byte
- **Packet parsing**: frame extraction for standard and self-delimited framing (RFC 6716 ยง3 and Appendix B)
**Advanced:**
- **Multistream decoding**: surround layouts via ``MultistreamDecoder`` (RFC 7845)
- **Low-level layers**: direct access to SILK, LPC arithmetic, and CELT codecs below the packet layer
Quick Examples
--------------
Encode and Decode
~~~~~~~~~~~~~~~~~
.. code-block:: python
import numpy as np
import ruopus
enc = ruopus.OpusEncoder(2, bitrate=64_000) # stereo, 64 kbps
dec = ruopus.OpusDecoder(2)
frame = np.zeros((960, 2), dtype=np.float32) # 20 ms stereo at 48 kHz
packet = enc.encode_auto(frame) # -> bytes
pcm = dec.decode_packet(packet) # -> (960, 2) float32
Ogg Opus Round-Trip
~~~~~~~~~~~~~~~~~~~
.. code-block:: python
import numpy as np
import ruopus
samples = np.random.randn(48_000 * 5).astype(np.float32) # 5 s mono
ogg_bytes = ruopus.encode_ogg_opus(samples, channels=1, bitrate=96_000)
pcm, head = ruopus.decode_ogg_opus(ogg_bytes)
print(f"Decoded {pcm.shape[0] / 48_000:.2f} s, {head.channel_count}-ch")
Packet Inspection
~~~~~~~~~~~~~~~~~
.. code-block:: python
import ruopus
pkt = ruopus.Packet(raw_bytes)
print(f"mode={pkt.toc.mode}, bw={pkt.toc.bandwidth}, frames={len(pkt)}")
Installation
------------
.. code-block:: bash
pip install ruopus
Build from source (requires a Rust toolchain and ``maturin``):
.. code-block:: bash
git clone https://github.com/jmg049/ruopus
cd ruopus
pip install maturin
maturin develop --release
Contents
--------
.. toctree::
:maxdepth: 2
:caption: User Guide
guide/installation
guide/quickstart
guide/codec_modes
guide/frame_sizes
guide/ogg
guide/fec_and_loss
guide/packet_inspection
guide/multistream
guide/lowlevel
.. toctree::
:maxdepth: 2
:caption: API Reference
api/index
Indices and Tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`