feat(audio): format detection and HTTP codec negotiation

[niklabh]

Implement Phase 1 roadmap item for sniffing audio containers (WAV, MP3, Ogg, FLAC) from magic bytes and MP3 sync, mapping Content-Type to the same codes, and rejecting obvious non-audio document responses when no audio signature is present.

Host (oxide-browser):

• Add audio_format module with sniffing, MIME helpers, AUDIO_HTTP_ACCEPT, and unit tests.
• Register api_audio_detect_format, api_audio_play_with_format, api_audio_channel_play_with_format, api_audio_last_url_content_type.
• Extend api_audio_play_url with Accept header, Content-Type capture, MIME vs sniff warnings, and fast-fail (-4) for document-like bodies.
• Add HostState::last_audio_url_content_type and audio_try_play hint helper with mismatch warnings.

SDK (oxide-sdk):

• Add AudioFormat enum and wrappers for detect, play with hint, channel play with hint, and last URL Content-Type string.

ROADMAP: mark Audio format detection and codec negotiation as shipped.
Made-with: Cursor

Summary by CodeRabbit

Release Notes

• New Features
  • Added automatic audio format detection for WAV, MP3, OGG, and FLAC formats
  • Introduced enhanced audio playback APIs with format hint support for improved control
  • Improved content-type detection and validation when fetching audio from URLs
  • Enhanced error handling to reject non-audio document responses

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This change implements audio format detection and codec negotiation for the oxide-browser audio subsystem. A new audio_format module provides container signature sniffing and MIME-type parsing to identify audio formats. New host APIs enable SDK guests to detect formats from byte buffers, retrieve last-fetched Content-Type headers, and play audio with format hints. The host now validates that fetched audio URLs return actual audio content rather than error pages.

Changes

Cohort / File(s)	Summary
Audio Format Detection oxide-browser/src/audio_format.rs	New module with byte-sniffing logic for WAV, MP3, OGG, FLAC detection via magic bytes and frame sync patterns; MIME-to-format mapping; non-audio document detection for HTML/plaintext/JSON/XML; comprehensive unit tests.
Host Capabilities Integration oxide-browser/src/capabilities.rs	Added last_audio_url_content_type state tracking; new audio_try_play() helper with format hint validation; four new Wasm imports for format detection, playback with hints, Content-Type retrieval, and per-channel playback; enhanced api_audio_play_url to record HTTP Content-Type, validate against non-audio documents, and log format mismatches.
Public API Exports oxide-browser/src/lib.rs, oxide-sdk/src/lib.rs	Exposed audio_format module from browser crate; extended SDK with new AudioFormat enum (Wav/Mp3/Ogg/Flac), format-detection function, format-hinted playback, Content-Type retrieval, and per-channel playback with format hints.
Documentation ROADMAP.md	Marked "Audio format detection and codec negotiation" as completed.

Sequence Diagram

sequenceDiagram
    participant Guest as Guest (SDK)
    participant Host as Host (Browser)
    participant Network as Network (HTTP)
    
    Guest->>Host: audio_play_url(url)
    Host->>Network: Fetch audio data
    Network-->>Host: Response + Content-Type header
    Host->>Host: Store Content-Type<br/>(last_audio_url_content_type)
    Host->>Host: Sniff format from bytes<br/>(magic signatures)
    Host->>Host: Validate not HTML/error<br/>(MIME checks)
    alt Format valid & signature found
        Host->>Host: Play audio data
        Host-->>Guest: Success
    else Non-audio document or no signature
        Host-->>Guest: Return -4 (error)
    end
    
    Guest->>Host: audio_play_with_format(data, format_hint)
    Host->>Host: Sniff format from bytes
    alt Hint matches sniffed format
        Host->>Host: Play audio on channel 0
        Host-->>Guest: Success
    else Hint mismatch
        Host->>Host: Log warning, play anyway
        Host-->>Guest: Success
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: add audio playback API (Phase 1) #10: Introduced the baseline audio playback subsystem (api_audio_play_url, audio_play host functions); this PR extends it with format detection, MIME validation, and new host imports for format-hinted playback and Content-Type retrieval.

Poem

🐰 Bytes whisper secrets, I sniff them all—
MP3 frames, FLAC magic, WAV's siren call.
No more HTML tricks sneaking through!
Audio format detected—hooray, it's true! 🎵

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately describes the main change: implementation of audio format detection and HTTP codec negotiation across the codebase, matching the PR's primary objective.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/audio-format-detection

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}