proteus-lib 0.5.3

# Proteus Library

`proteus-lib` is the core Rust library behind the Proteus audio tools. It provides:
- Container parsing for `.prot`/`.mka` files.
- A real-time playback engine and high-level `Player` API.
- DSP utilities (convolution reverb and impulse response loading).
- Diagnostics and benchmark helpers (optional feature flags).

**Quick Start**
```rust
use proteus_lib::playback::player::Player;

fn main() {
    let file_path = "/path/to/file.prot".to_string();
    let mut player = Player::new(&file_path);
    player.play();
    player.sleep_until_end();
}
```

## Structure

**`container/`**
- Parses `.prot`/`.mka` containers, reads `play_settings.json`, and exposes track selections.
- `info.rs` handles probe metadata, duration lookup, and full packet scanning.
- `play_settings/` models multiple schema versions via serde.

**`playback/`**
- `player.rs` is the main public API (`Player`) that manages state and threads.
- `engine/` contains the lower-level mixing engine, buffer management, and reverb worker.

**`dsp/`**
- `convolution.rs` provides FFT-based convolution (complex or real FFT).
- `reverb.rs` wraps convolution into a reusable per-channel reverb.
- `impulse_response.rs` loads and normalizes impulse responses from files or container attachments.

**`audio/`**
- Shared ring buffers and sample helpers used by the engine.

**`diagnostics/`**
- Optional benchmark utilities and a `Reporter` to emit playback status snapshots.

## Playback Model (High Level)

1. A `Prot` container resolves track selections and metadata.
2. Track decoder threads feed per-track ring buffers.
3. A mixing thread combines buffers into interleaved audio.
4. Optional convolution reverb is applied (if enabled).
5. The `Player` sends mixed audio to the output sink.

## Impulse Responses

Impulse responses can be loaded from:
- a file path (`file:ir.wav` or plain path)
- a `.prot`/`.mka` attachment (`attachment:ir.wav`)

Tail trimming defaults to `-60 dB` and can be overridden via settings or at runtime.

## Feature Flags

- `bench`: enables synthetic DSP benchmarks.
- `real-fft`: uses real FFTs for convolution instead of complex FFTs.

## Notes

- The library is designed for real-time playback and integrates with the CLI and GUI apps.
- Many settings are driven by the `play_settings.json` embedded in container files.