# Muxide API Contract (v0.2.x)

This document defines the public API contract and invariants for the v0.2.x series of Muxide. The contract is intended to be a stable reference for users of the crate and for implementers working on the internals. All public items in the `muxide::api` module are covered by this contract.

## High‑Level API

Muxide exposes a builder pattern for creating a `Muxer` instance that writes an MP4 container to an arbitrary writer (implementing `std::io::Write`).

### Types

* `VideoCodec`: Enumeration of supported video codecs.
  * `H264` — H.264/AVC video codec. Bitstreams must be in Annex B format.
  * `H265` — H.265/HEVC video codec. Bitstreams must be in Annex B format.
  * `Av1` — AV1 video codec. Bitstreams must be supplied as an OBU stream.
  * `Vp9` — VP9 video codec. Bitstreams must be supplied as compressed frames.

* `AudioCodec`: Enumeration of supported audio codecs.
  * `Aac(AacProfile)` — AAC audio codec, encoded as ADTS frames. Profile selects LC, Main, SSR, LTP, HE, or HEv2; LC offers the broadest playback compatibility.
  * `Opus` — Opus audio codec, supplied as raw Opus packets. (In MP4, Opus is always signaled at 48 kHz.)
  * `None` — Indicates that no audio track will be created.

* `MuxerBuilder<Writer>` — Type parameterised by an output writer.  Provides methods to configure the container and tracks and to build a `Muxer`.  The builder consumes itself on `build`.

* `Muxer<Writer>` — Type parameterised by an output writer.  Provides methods to write video and audio frames and to finalise the file.  The generic parameter is preserved to allow any type implementing `Write` as the underlying sink.

* `MuxerConfig` — Simple configuration struct for integrations that prefer a config-driven constructor.

* `MuxerStats` — Statistics returned when finishing a mux.

* `MuxerError` — Enumeration of error conditions that may be returned by builder or runtime operations.  This enum may grow as the implementation matures.

### Timebase

Muxide converts incoming timestamps in seconds (`pts: f64`) into a fixed internal media timebase.

- Muxide uses a **90 kHz** media timescale for track timing (a common convention for MP4/H.264).
- The media timebase is shared between video and audio when both tracks are present.

### MuxerBuilder Methods

* `new(writer: Writer) -> Self` — Constructs a builder for the given writer.  The writer is consumed by the builder and later moved into the `Muxer`.

* `video(self, codec: VideoCodec, width: u32, height: u32, framerate: f64) -> Self` — Configures the video track.  The frame rate must be positive and in the range (0, 120].  Non‑integer frame rates (e.g. 29.97) are permitted.

* `audio(self, codec: AudioCodec, sample_rate: u32, channels: u16) -> Self` — Configures an optional audio track.  At most one call to `audio` may be made.  Audio is optional; if omitted, the file will contain only video.  If `codec` is `None`, the sample rate and channels are ignored.

* `build(self) -> Result<Muxer<Writer>, MuxerError>` — Validates the configuration and returns a `Muxer` instance on success.  Validation rules:
  1. A video track must have been configured.  Otherwise a `MuxerError::MissingVideoConfig` is returned.
  2. If `AudioCodec::None` is selected, the muxer behaves as video-only.

### Muxer Methods

* `write_video(&mut self, pts: f64, data: &[u8], is_keyframe: bool) -> Result<(), MuxerError>` — Writes a video frame to the container.

  **Invariants:**
  - `pts` **must be non‑negative and strictly greater than the `pts` of the previous video frame**. Violations produce `MuxerError::NegativeVideoPts` or `MuxerError::NonIncreasingVideoPts`.
  - `data` must contain a complete encoded frame in the codec's expected format (Annex B for H.264/H.265; OBU stream for AV1; compressed frame for VP9).  The first video frame must be a keyframe and must include the codec configuration headers (SPS/PPS for H.264/H.265, Sequence Header OBU for AV1, frame header with parameters for VP9); missing headers produce `MuxerError::FirstVideoFrameMustBeKeyframe`, `MuxerError::FirstVideoFrameMissingSpsPps`, `MuxerError::FirstAv1FrameMissingSequenceHeader`, or `MuxerError::FirstVp9FrameMissingSequenceHeader`.
  - `is_keyframe` must accurately reflect whether the frame is a keyframe.  Incorrect keyframe flags may result in unseekable files.

  **B-frames:**
  - `write_video()` is intended for streams where **PTS == DTS** (no reordering).
  - For streams with B-frames (PTS != DTS), use `write_video_with_dts()` and feed frames in decode order.

* `write_audio(&mut self, pts: f64, data: &[u8]) -> Result<(), MuxerError>` — Writes an audio frame to the container.

  **Invariants:**
  - `pts` **must be non‑negative and strictly greater than or equal to the `pts` of the previous audio frame**.
  - Audio must not arrive before the first video frame (i.e. audio `pts` must be >= video `pts`).
  - `data` must contain a complete encoded audio frame:
    - AAC must be ADTS; invalid ADTS is rejected.
    - Opus must be a structurally valid Opus packet; invalid packets are rejected.

* `finish(self) -> Result<(), MuxerError>` — Finalises the container.  After calling this method, no further `write_*` calls may be made.  This method writes any pending metadata (e.g. `moov` box) to the output writer.

* `finish_with_stats(self) -> Result<MuxerStats, MuxerError>` — Finalises the container and returns muxing statistics.

* `finish_in_place(&mut self) -> Result<(), MuxerError>` — Finalises the container without consuming the muxer.  This is a convenience for applications that want an explicit “finalised” error on double-finish and on writes after finishing.

* `finish_in_place_with_stats(&mut self) -> Result<MuxerStats, MuxerError>` — In-place finalisation that returns muxing statistics.

### Error Semantics

All functions that can fail return a `MuxerError`. New error variants may be added in minor versions.

### Concurrency & Thread Safety

`Muxer<W>` is `Send` when `W: Send` and `Sync` when `W: Sync`.

Muxide itself is implemented as a single-threaded writer; thread-safety here refers to moving/sharing the muxer value when the underlying writer type supports it.

## Invariants & Correctness Rules

1. **Monotonic Timestamps:** For each track, presentation timestamps (`pts`) must be non‑negative and strictly increasing (video) or non‑decreasing (audio). If this invariant is violated, the operation must fail.
2. **Keyframes:** The first video frame must be a keyframe and must include the codec configuration required by that codec: SPS/PPS for H.264, VPS/SPS/PPS for H.265, a Sequence Header OBU for AV1, and valid frame header parameters for VP9. Subsequent keyframes must be marked via the `is_keyframe` flag. Files produced without proper keyframe signalling will not play back correctly and are considered incorrect.
3. **Single Video Track:** Exactly one video track is supported.  Multiple video tracks or the absence of a video track is an error.
4. **Single Audio Track:** At most one audio track is supported.  Adding multiple audio tracks is not allowed.
5. **B‑frames:** Streams with reordering (B-frames) are supported when callers use `write_video_with_dts()`:
  - Frames must be supplied in **decode order**.
  - DTS must be strictly increasing.
  - PTS may differ from DTS.
  For streams without reordering, callers may use `write_video()` which assumes PTS == DTS.
6. **Bitstream formats:**
  - H.264/H.265 video must be provided in Annex B format (start-code-prefixed NAL units).
  - AV1 video must be provided as an OBU stream.
  - VP9 video must be provided as compressed VP9 frames (with frame headers intact, not Annex B).
7. **Audio formats:**
  - AAC audio must be provided as ADTS frames.
  - Opus audio must be provided as raw Opus packets.

## B-frame Support

Muxide supports B-frames via the `write_video_with_dts()` method:

- When B-frames are present, callers must provide both PTS (presentation timestamp) and DTS (decode timestamp)
- DTS must be monotonically increasing (decode order)
- PTS may differ from DTS (display order ≠ decode order)
- The `ctts` (composition time offset) box is automatically generated

For streams without B-frames, use `write_video()` which assumes PTS == DTS.

## Examples (Pseudo‑Code)

```
use muxide::api::{AacProfile, AudioCodec, MuxerBuilder, VideoCodec};
use std::fs::File;

// Create an output file
let file = File::create("out.mp4")?;

// Build a muxer for 1920x1080 30 fps video and 48 kHz stereo audio
let mut mux = MuxerBuilder::new(file)
    .video(VideoCodec::H264, 1920, 1080, 30.0)
    .audio(AudioCodec::Aac(AacProfile::Lc), 48_000, 2)
    .build()?;

// Write frames (encoded elsewhere)
for (i, frame) in video_frames.iter().enumerate() {
    let pts = (i as f64) / 30.0;
    let is_key = i == 0 || i % 30 == 0;
    mux.write_video(pts, &frame.data, is_key)?;
    // Optionally interleave audio
}

// Finish the file
mux.finish()?;
```

## Stability

The API described here must not change in any breaking way within the v0.2.x series.  Additional methods may be added, but existing signatures and invariants must remain stable.  Breaking changes require a new major version.
