diff --git a/Cargo.lock b/Cargo.lock index 17a4dbb92..4a615a9b1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4449,6 +4449,7 @@ version = "0.6.0" dependencies = [ "anyhow", "async-channel", + "bytes", "cpal", "env_logger", "hex", diff --git a/Cargo.toml b/Cargo.toml index 27f3ad5e4..cf9aedf55 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -140,10 +140,8 @@ tokio-runtime = ["dep:tokio"] signal = ["tokio-runtime", "tokio/signal"] sqlite-storage = ["whatsapp-rust-sqlite-storage"] tokio-native = ["tokio-runtime", "tokio/rt-multi-thread"] -# VoIP calls media plane (opt-in, NOT default): pulls wacore's voip crypto plus the -# DTLS/SCTP/DataChannel transport (webrtc-rs) and libopus FFI. Not buildable on wasm32/esp32 -# (a compile_error in src/voip/mod.rs enforces this); use wacore's `voip` feature there. -voip = [ +# Shared native VoIP runtime. Public profiles below select which codec implementation is linked. +voip-runtime = [ "wacore/voip", "tokio-runtime", "tokio/net", @@ -152,9 +150,16 @@ voip = [ "dep:webrtc-data", "dep:webrtc-util", "dep:webrtc-util-011", - "dep:opus", "dep:rustls", ] +# Backwards-compatible full profile: preserves both codec adapters from the former single feature. +voip = ["voip-mlow", "voip-libopus"] +# Codec-bypass profile: raw MLOW/Opus payloads supplied by the application, no codec linked. +voip-encoded = ["voip-runtime"] +# Explicit spelling for consumers that assemble feature sets instead of using `voip`. +voip-mlow = ["voip-runtime", "wacore/voip-mlow"] +# Optional PCM adapter for standard Opus, including MLOW's CELT escape. Encoded I/O needs no libopus. +voip-libopus = ["voip-encoded", "dep:opus"] [dependencies] anyhow = { workspace = true } diff --git a/README.md b/README.md index 9564cecf1..a8f393e98 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,8 @@ A high-performance, async Rust library for the WhatsApp Web API. Inspired by [wh - **Authentication** — QR code pairing, pair code linking, persistent sessions - **Messaging** — E2E encrypted (Signal Protocol), 1-on-1 and group chats, editing, reactions, quoting, receipts - **Media** — Upload/download images, videos, documents, GIFs, audio with automatic encryption -- **Voice calls** — 1:1 VoIP audio calls (incoming and outgoing) behind the optional `voip` feature +- **Voice calls** — 1:1 VoIP audio calls with built-in MLOW or external encoded Opus/MLOW; see the + [codec boundary and production profiles](agent_docs/voip_audio_codecs.md) - **Groups & Communities** — Create, manage, invite, membership approval, subgroup linking - **Newsletters** — Create, join, send messages, reactions - **Status** — Text, image, and video status posts with privacy controls diff --git a/agent_docs/voip_audio_codecs.md b/agent_docs/voip_audio_codecs.md new file mode 100644 index 000000000..87c0dcdc1 --- /dev/null +++ b/agent_docs/voip_audio_codecs.md @@ -0,0 +1,125 @@ +# VoIP audio codecs + +The media core owns signaling, RTP timing, SRTP/WARP, relay transport, and receive statistics. +Applications may use the built-in PCM/MLOW path or exchange complete codec packets through +`encoded_audio`. + +```text +PCM source ── MLOW adapter ──┐ + ├── RTP + SRTP/WARP ── WhatsApp relay +encoded source/sink ─────────┘ +``` + +The encoded boundary does not transcode. `AudioFormat` fixes the codec profile, payload type, RTP +clock, and 60 ms packet cadence for the call. + +## Profiles + +| Format | Profile | PCM | RTP clock / step | PT | +| --- | --- | ---: | ---: | ---: | +| `MLOW_16KHZ_60MS` | MLOW | 16 kHz mono | 16 kHz / 960 | 120 | +| `OPUS_MLOW_16KHZ_60MS` | Opus CELT in MLOW | 16 kHz mono | 16 kHz / 960 | 120 | +| `OPUS_16KHZ_60MS` | Native Opus | 16 kHz mono | 16 kHz / 960 | 120 | +| `OPUS_RFC7587_16KHZ_60MS` | Native Opus | 16 kHz mono | 48 kHz / 2880 | 111 | +| `OPUS_RFC7587_48KHZ_60MS` | Native Opus | 48 kHz mono | 48 kHz / 2880 | 111 | + +All current profiles signal `