Skip to main content

active_call/media/
monitor.rs

1//! Side-path (侧路) audio distribution: mirrors both call legs' audio to an
2//! external websocket server.
3//!
4//! Unlike [`crate::media::track::media_pass::MediaPassTrack`] — which replaces
5//! the media path with a bidirectional bridge — the monitor is a passive,
6//! one-way tap: `MonitorProcessor` instances are attached to the caller track
7//! (uplink, leg 1) and the server-side track (downlink, leg 0) processor
8//! chains, publish `[1-byte leg][pcm16]` frames into a [`MonitorHub`], and a
9//! forwarder task dials out to the configured websocket and pushes the frames.
10//! The main media path is never modified or blocked.
11//!
12//! Wire protocol:
13//! - the dial-out URL gets a `session_id` query parameter appended;
14//! - the first message is a JSON text frame (see [`monitor_start_metadata`])
15//!   carrying session info;
16//! - every following message is a binary frame `[1-byte leg][pcm16 mono]`
17//!   (leg `0` = agent/server side, `1` = caller), PCM at
18//!   [`INTERNAL_SAMPLERATE`].
19//!
20//! Failure semantics: the forwarder tries **once**. A failed handshake, a
21//! rejected upgrade or a dropped connection logs a warning and gives up for
22//! the rest of the call — audio is simply not published, the call itself is
23//! unaffected.
24use crate::media::{AudioFrame, INTERNAL_SAMPLERATE, Samples, TrackId};
25use anyhow::Result;
26use bytes::{Bytes, BytesMut};
27use futures::{SinkExt, StreamExt};
28use serde::{Deserialize, Serialize};
29use serde_json::json;
30use serde_with::skip_serializing_none;
31use std::{collections::HashMap, time::Duration};
32use tokio::sync::broadcast;
33use tokio_tungstenite::{
34    connect_async,
35    tungstenite::{
36        Message,
37        client::IntoClientRequest,
38        http::{HeaderName, HeaderValue},
39    },
40};
41use tokio_util::sync::CancellationToken;
42use tracing::{info, warn};
43
44/// Leg tag byte prepended to every published frame: server-side (agent) audio
45/// played towards the caller (TTS, media-pass downlink, ambiance).
46pub const LEG_AGENT: u8 = 0;
47/// Leg tag byte prepended to every published frame: caller uplink audio.
48pub const LEG_CALLER: u8 = 1;
49
50/// Broadcast channel capacity, in tagged frames. A slow consumer lags behind
51/// and silently drops its own frames instead of back-pressuring the media
52/// path (200 frames ≈ 4s of 20ms audio).
53pub const MONITOR_CHANNEL_CAPACITY: usize = 200;
54
55#[skip_serializing_none]
56#[derive(Debug, Deserialize, Serialize, Clone, Default)]
57#[serde(rename_all = "camelCase")]
58pub struct MonitorOption {
59    /// Websocket url to dial out to, e.g. `ws://asr-server:9000/audio`.
60    url: String,
61    /// Target size in bytes of each binary frame pushed to the remote (PCM16
62    /// payload, excluding the leg prefix byte). `None`/0 disables chunking:
63    /// tapped frames are forwarded as they arrive (about 20 ms each).
64    buffer_size: Option<u32>,
65    /// Interval in milliseconds at which partially filled buffers are flushed
66    /// to the remote. `None`/0 disables the flush timer.
67    ptime: Option<u32>,
68    /// Extra HTTP headers for the websocket handshake (e.g. `Authorization`).
69    headers: Option<HashMap<String, String>>,
70}
71
72impl MonitorOption {
73    pub fn new(
74        url: String,
75        buffer_size: Option<u32>,
76        ptime: Option<u32>,
77        headers: Option<HashMap<String, String>>,
78    ) -> Self {
79        Self {
80            url,
81            buffer_size,
82            ptime,
83            headers,
84        }
85    }
86
87    pub fn url(&self) -> &str {
88        &self.url
89    }
90
91    pub fn buffer_size(&self) -> Option<u32> {
92        self.buffer_size
93    }
94
95    pub fn ptime(&self) -> Option<u32> {
96        self.ptime
97    }
98
99    pub fn headers(&self) -> Option<&HashMap<String, String>> {
100        self.headers.as_ref()
101    }
102}
103
104/// Per-session fan-out point between the media-path taps and consumers (the
105/// outbound websocket forwarder today, possible local sinks later). With no
106/// subscriber a publish is a near no-op.
107#[derive(Clone)]
108pub struct MonitorHub {
109    sender: broadcast::Sender<Bytes>,
110}
111
112impl Default for MonitorHub {
113    fn default() -> Self {
114        Self::new()
115    }
116}
117
118impl MonitorHub {
119    pub fn new() -> Self {
120        let (sender, _) = broadcast::channel(MONITOR_CHANNEL_CAPACITY);
121        Self { sender }
122    }
123
124    pub fn subscribe(&self) -> broadcast::Receiver<Bytes> {
125        self.sender.subscribe()
126    }
127
128    pub(crate) fn publish(&self, data: Bytes) {
129        // No subscriber / lagging consumer: drop instead of back-pressuring.
130        let _ = self.sender.send(data);
131    }
132}
133
134/// Mirrors a track's own PCM frames into a [`MonitorHub`], tagged with a leg
135/// byte. Frames merely relayed for another leg (e.g. the caller's audio
136/// forwarded through the media-pass track's `send_packet`) are filtered out by
137/// the `owner` check — the originating track publishes its own copy.
138pub struct MonitorProcessor {
139    owner: TrackId,
140    leg: u8,
141    hub: MonitorHub,
142}
143
144impl MonitorProcessor {
145    pub fn new(owner: TrackId, leg: u8, hub: MonitorHub) -> Self {
146        Self { owner, leg, hub }
147    }
148}
149
150impl super::processor::Processor for MonitorProcessor {
151    fn process_frame(&mut self, frame: &mut AudioFrame) -> Result<()> {
152        if frame.track_id != self.owner {
153            return Ok(());
154        }
155        if let Samples::PCM { samples } = &frame.samples
156            && !samples.is_empty()
157        {
158            let pcm = audio_codec::samples_to_bytes(samples);
159            let mut data = Vec::with_capacity(pcm.len() + 1);
160            data.push(self.leg);
161            data.extend_from_slice(&pcm);
162            self.hub.publish(Bytes::from(data));
163        }
164        Ok(())
165    }
166}
167
168/// Build the JSON metadata frame sent as the first (text) message after the
169/// websocket is established. `extras` carries the call's custom variables
170/// (SIP extracted headers, playbook vars, …).
171pub fn monitor_start_metadata(
172    session_id: &str,
173    call_type: serde_json::Value,
174    started_at: String,
175    extras: serde_json::Value,
176) -> serde_json::Value {
177    json!({
178        "event": "monitor_start",
179        "sessionId": session_id,
180        "callType": call_type,
181        "startedAt": started_at,
182        "format": "pcm16/mono",
183        "sampleRate": INTERNAL_SAMPLERATE,
184        "legs": [
185            { "leg": LEG_AGENT, "direction": "agent", "sampleRate": INTERNAL_SAMPLERATE },
186            { "leg": LEG_CALLER, "direction": "caller", "sampleRate": INTERNAL_SAMPLERATE },
187        ],
188        "extras": extras,
189    })
190}
191
192/// Dial out to `option.url()` and push both legs' audio until the call ends or
193/// the connection breaks. Single attempt: any failure logs a warning and gives
194/// up for the rest of the call.
195pub async fn run_monitor_forwarder(
196    session_id: String,
197    option: MonitorOption,
198    metadata: serde_json::Value,
199    cancel_token: CancellationToken,
200    mut receiver: broadcast::Receiver<Bytes>,
201) {
202    let mut url = match url::Url::parse(option.url()) {
203        Ok(url) => url,
204        Err(e) => {
205            warn!(session_id, url = %option.url(), error = %e, "monitor: invalid url, giving up");
206            return;
207        }
208    };
209    {
210        let mut query = url.query_pairs_mut();
211        query.append_pair("session_id", &session_id);
212    }
213
214    // Start from the standard &str conversion so the required websocket
215    // handshake headers (Host/Connection/Upgrade/Sec-WebSocket-*) are
216    // generated, then layer the custom headers on top. A bare
217    // `Request::builder().uri(..)` would pass through `IntoClientRequest`
218    // untouched (the `Request` impl is a no-op) and fail the handshake.
219    let mut request = match url.as_str().into_client_request() {
220        Ok(request) => request,
221        Err(e) => {
222            warn!(session_id, url = %url, error = %e, "monitor: invalid request, giving up");
223            return;
224        }
225    };
226    if let Some(headers) = option.headers() {
227        for (name, value) in headers {
228            let (name, value) = match (
229                HeaderName::from_bytes(name.as_bytes()),
230                HeaderValue::from_str(value),
231            ) {
232                (Ok(name), Ok(value)) => (name, value),
233                (name_err, value_err) => {
234                    warn!(
235                        session_id,
236                        header = %name,
237                        name_error = ?name_err.err(),
238                        value_error = ?value_err.err(),
239                        "monitor: invalid header, giving up"
240                    );
241                    return;
242                }
243            };
244            request.headers_mut().insert(name, value);
245        }
246    }
247
248    info!(session_id, url = %url, "monitor: connecting");
249    let (ws, _) = match connect_async(request).await {
250        Ok(ok) => ok,
251        Err(e) => {
252            warn!(
253                session_id,
254                url = %url,
255                error = %e,
256                "monitor: connect failed, giving up for this call"
257            );
258            return;
259        }
260    };
261    let (mut ws_sink, mut ws_source) = ws.split();
262    // Keep draining the read side: tungstenite answers protocol pings while
263    // reading, and this observes a remote close instead of hanging the write
264    // half forever.
265    crate::spawn(async move {
266        while let Some(msg) = ws_source.next().await {
267            if msg.is_err() {
268                break;
269            }
270        }
271    });
272
273    if let Err(e) = ws_sink.send(Message::Text(metadata.to_string().into())).await {
274        warn!(
275            session_id,
276            error = %e,
277            "monitor: failed to send metadata, giving up for this call"
278        );
279        return;
280    }
281    info!(session_id, url = %url, "monitor: connected");
282
283    let buffer_size = option.buffer_size().filter(|size| *size > 0).unwrap_or(0) as usize;
284    let ptime_ms = option.ptime().filter(|p| *p > 0).unwrap_or(0);
285    let mut ticker = tokio::time::interval(Duration::from_millis(ptime_ms.max(1) as u64));
286    ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
287
288    // One buffer per leg: legs interleave on the hub and must not mix inside
289    // a chunk (and may even differ in format later).
290    let mut leg_buffers: HashMap<u8, BytesMut> = HashMap::new();
291
292    loop {
293        let mut outgoing: Vec<Bytes> = Vec::new();
294        tokio::select! {
295            biased;
296            _ = cancel_token.cancelled() => break,
297            _ = ticker.tick(), if ptime_ms > 0 => {
298                // Flush whatever accumulated, even a partial chunk — never
299                // pad with silence, a monitor must not fabricate audio.
300                for (leg, buffer) in leg_buffers.iter_mut() {
301                    if !buffer.is_empty() {
302                        outgoing.push(tag_frame(*leg, std::mem::take(buffer)));
303                    }
304                }
305            }
306            msg = receiver.recv() => match msg {
307                Ok(data) => {
308                    if data.is_empty() {
309                        continue;
310                    }
311                    let leg = data[0];
312                    let buffer = leg_buffers.entry(leg).or_default();
313                    buffer.extend_from_slice(&data[1..]);
314                    if buffer_size > 0 {
315                        // Emit exact-size chunks as soon as they fill.
316                        while buffer.len() >= buffer_size {
317                            outgoing.push(tag_frame(leg, buffer.split_to(buffer_size)));
318                        }
319                    } else if ptime_ms == 0 {
320                        // No buffering configured: pass frames straight through.
321                        outgoing.push(tag_frame(leg, std::mem::take(buffer)));
322                    }
323                }
324                Err(broadcast::error::RecvError::Lagged(dropped)) => {
325                    warn!(session_id, dropped, "monitor: lagged, dropping frames");
326                    continue;
327                }
328                Err(broadcast::error::RecvError::Closed) => break,
329            }
330        }
331
332        let mut failed = false;
333        for chunk in outgoing {
334            if let Err(e) = ws_sink.send(Message::Binary(chunk)).await {
335                warn!(
336                    session_id,
337                    error = %e,
338                    "monitor: websocket send failed, giving up for this call"
339                );
340                failed = true;
341                break;
342            }
343        }
344        if failed {
345            break;
346        }
347    }
348
349    let _ = ws_sink.close().await;
350    info!(session_id, url = %url, "monitor forwarder stopped");
351}
352
353fn tag_frame(leg: u8, pcm: BytesMut) -> Bytes {
354    let mut out = BytesMut::with_capacity(pcm.len() + 1);
355    out.extend_from_slice(&[leg]);
356    out.extend_from_slice(&pcm);
357    out.freeze()
358}
359
360#[cfg(test)]
361mod tests {
362    use super::*;
363
364    #[test]
365    fn monitor_option_parses_camel_case() {
366        let option: MonitorOption = serde_json::from_value(json!({
367            "url": "ws://server:9000/audio",
368            "bufferSize": 640,
369            "ptime": 100,
370            "headers": { "Authorization": "Bearer token", "X-Tenant-ID": "t1" }
371        }))
372        .unwrap();
373        assert_eq!(option.url(), "ws://server:9000/audio");
374        assert_eq!(option.buffer_size(), Some(640));
375        assert_eq!(option.ptime(), Some(100));
376        let headers = option.headers().unwrap();
377        assert_eq!(headers.get("Authorization").map(String::as_str), Some("Bearer token"));
378        assert_eq!(headers.get("X-Tenant-ID").map(String::as_str), Some("t1"));
379    }
380
381    #[test]
382    fn monitor_option_defaults_are_passthrough() {
383        let option: MonitorOption = serde_json::from_value(json!({ "url": "ws://x" })).unwrap();
384        assert_eq!(option.buffer_size(), None);
385        assert_eq!(option.ptime(), None);
386        assert_eq!(option.headers(), None);
387    }
388
389    #[test]
390    fn metadata_contains_session_and_legs() {
391        let metadata = monitor_start_metadata(
392            "s.1",
393            json!("sip"),
394            "2026-10-27T00:00:00Z".to_string(),
395            json!({ "k": "v" }),
396        );
397        assert_eq!(metadata["event"], "monitor_start");
398        assert_eq!(metadata["sessionId"], "s.1");
399        assert_eq!(metadata["callType"], "sip");
400        assert_eq!(metadata["sampleRate"], INTERNAL_SAMPLERATE);
401        assert_eq!(metadata["legs"][0]["leg"], LEG_AGENT);
402        assert_eq!(metadata["legs"][0]["direction"], "agent");
403        assert_eq!(metadata["legs"][1]["leg"], LEG_CALLER);
404        assert_eq!(metadata["legs"][1]["direction"], "caller");
405        assert_eq!(metadata["extras"]["k"], "v");
406    }
407}