Skip to main content

active_call/media/
stream.rs

1use crate::event::{EventSender, SessionEvent};
2use crate::media::ambiance::{AmbianceOption, AmbianceProcessor};
3use crate::media::dtmf::DtmfDetector;
4use crate::media::monitor::MonitorHub;
5use crate::media::volume_control::HoldProcessor;
6use crate::media::{AudioFrame, INTERNAL_SAMPLERATE, Samples, TrackId};
7use crate::media::{
8    processor::Processor,
9    recorder::{Recorder, RecorderOption},
10    track::{Track, TrackPacketReceiver, TrackPacketSender},
11};
12use anyhow::Result;
13use std::collections::{HashMap, HashSet};
14use std::path::Path;
15use std::sync::{
16    Arc, Mutex as StdMutex, Weak,
17    atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering},
18};
19use std::time::Duration;
20use tokio::task::JoinHandle;
21use tokio::{
22    select,
23    sync::{Mutex, mpsc},
24};
25use tokio_util::sync::CancellationToken;
26use tracing::{debug, info, warn};
27use uuid;
28
29// leak-diagnosis counters (LEAKSTAT)
30pub static STREAMS_LIVE: AtomicUsize = AtomicUsize::new(0);
31pub static RECORDER_LIVE: AtomicUsize = AtomicUsize::new(0);
32pub static RECORDER_SPAWNED: AtomicUsize = AtomicUsize::new(0);
33pub static RECORDER_DETACHED: AtomicUsize = AtomicUsize::new(0);
34pub static TRACKS_LIVE: AtomicUsize = AtomicUsize::new(0);
35
36pub struct MediaStream {
37    id: String,
38    pub cancel_token: CancellationToken,
39    recorder_option: Mutex<Option<RecorderOption>>,
40    tracks: Mutex<HashMap<TrackId, (Box<dyn Track>, DtmfDetector)>>,
41    /// Trickle ICE candidates that arrived before any track existed to feed
42    /// them to. Drained into the next track started.
43    pending_ice_candidates: Mutex<Vec<(String, Option<String>, Option<u32>)>>,
44    suppressed_sources: Mutex<HashSet<TrackId>>,
45    event_sender: EventSender,
46    pub packet_sender: TrackPacketSender,
47    packet_receiver: Mutex<Option<TrackPacketReceiver>>,
48    recorder_sender: mpsc::UnboundedSender<AudioFrame>,
49    recorder_receiver: Mutex<Option<mpsc::UnboundedReceiver<AudioFrame>>>,
50    recorder_handle: Mutex<Option<JoinHandle<()>>>,
51    /// Stops the recorder. Independent of `cancel_token`: when the stream
52    /// ends, the recorder supervisor either stops the recorder or hands the
53    /// recording to the bridged peer (`RecorderOption::follow_bridge`).
54    recorder_stop: CancellationToken,
55    /// The stream this one is bridged to, if any.
56    bridge_peer: Arc<StdMutex<Option<BridgePeer>>>,
57    /// Recordings of ended bridged peers that this stream now feeds.
58    adopted_recorders: StdMutex<Vec<AdoptedRecorder>>,
59    /// True once a recorder task is actually consuming `recorder_sender`.
60    /// The ambiance idle loop mirrors its frames to the recorder only when
61    /// this is set, avoiding unbounded buffering when recording starts late.
62    recording_active: Arc<AtomicBool>,
63    ambiance: Mutex<Option<Arc<StdMutex<AmbianceProcessor>>>>,
64    ambiance_source_id: StdMutex<Option<TrackId>>,
65    last_server_packet_ts: Arc<AtomicU64>,
66    ambiance_idle_started: AtomicBool,
67    /// Side-path audio distribution hub (see `media::monitor`). Lazily
68    /// created by `enable_monitor` when the call option asks for it.
69    monitor_hub: Mutex<Option<MonitorHub>>,
70}
71
72impl Drop for MediaStream {
73    fn drop(&mut self) {
74        STREAMS_LIVE.fetch_sub(1, Ordering::Relaxed);
75    }
76}
77
78const CALLEE_TRACK_ID: &str = "callee-track";
79/// Prefix of the forwarding tracks that carry a bridged peer's audio.
80pub const BRIDGE_TRACK_PREFIX: &str = "bridge:";
81const QUEUE_HOLD_TRACK_ID: &str = "queue-hold-track";
82pub const SERVER_SIDE_TRACK_ID: &str = "server-side-track";
83const AMBIANCE_IDLE_TRACK_ID: &str = "ambiance-track";
84const AMBIANCE_IDLE_PTIME: Duration = Duration::from_millis(20);
85// Skip idle fill if server-side audio arrived within this window (TTS ptime is 20ms).
86const AMBIANCE_IDLE_GAP_MS: u64 = 25;
87
88#[derive(Clone)]
89struct BridgePeer {
90    id: String,
91    stream: Weak<MediaStream>,
92}
93
94/// A recording handed over by an ended bridged peer.
95struct AdoptedRecorder {
96    sender: mpsc::UnboundedSender<AudioFrame>,
97    /// The ended peer's session id: the recorder's own-leg channel.
98    own_leg: TrackId,
99    stop: CancellationToken,
100}
101
102pub struct MediaStreamBuilder {
103    cancel_token: Option<CancellationToken>,
104    id: Option<String>,
105    event_sender: EventSender,
106    recorder_config: Option<RecorderOption>,
107}
108
109impl MediaStreamBuilder {
110    pub fn new(event_sender: EventSender) -> Self {
111        Self {
112            id: Some(format!("ms:{}", uuid::Uuid::new_v4())),
113            cancel_token: None,
114            event_sender,
115            recorder_config: None,
116        }
117    }
118    pub fn with_id(mut self, id: String) -> Self {
119        self.id = Some(id);
120        self
121    }
122
123    pub fn with_cancel_token(mut self, cancel_token: CancellationToken) -> Self {
124        self.cancel_token = Some(cancel_token);
125        self
126    }
127
128    pub fn with_recorder_config(mut self, recorder_config: RecorderOption) -> Self {
129        self.recorder_config = Some(recorder_config);
130        self
131    }
132
133    pub fn build(self) -> MediaStream {
134        let cancel_token = self
135            .cancel_token
136            .unwrap_or_else(|| CancellationToken::new());
137        let tracks = Mutex::new(HashMap::new());
138        let (track_packet_sender, track_packet_receiver) = mpsc::unbounded_channel();
139        let (recorder_sender, recorder_receiver) = mpsc::unbounded_channel();
140        STREAMS_LIVE.fetch_add(1, Ordering::Relaxed);
141        MediaStream {
142            id: self.id.unwrap_or_default(),
143            cancel_token,
144            recorder_option: Mutex::new(self.recorder_config),
145            tracks,
146            pending_ice_candidates: Mutex::new(Vec::new()),
147            suppressed_sources: Mutex::new(HashSet::new()),
148            event_sender: self.event_sender,
149            packet_sender: track_packet_sender,
150            packet_receiver: Mutex::new(Some(track_packet_receiver)),
151            recorder_sender,
152            recorder_receiver: Mutex::new(Some(recorder_receiver)),
153            recorder_handle: Mutex::new(None),
154            recorder_stop: CancellationToken::new(),
155            bridge_peer: Arc::new(StdMutex::new(None)),
156            adopted_recorders: StdMutex::new(Vec::new()),
157            recording_active: Arc::new(AtomicBool::new(false)),
158            ambiance: Mutex::new(None),
159            ambiance_source_id: StdMutex::new(None),
160            last_server_packet_ts: Arc::new(AtomicU64::new(0)),
161            ambiance_idle_started: AtomicBool::new(false),
162            monitor_hub: Mutex::new(None),
163        }
164    }
165}
166
167impl MediaStream {
168    pub async fn serve(&self) -> Result<()> {
169        let packet_receiver = match self.packet_receiver.lock().await.take() {
170            Some(receiver) => receiver,
171            None => {
172                warn!(
173                    session_id = self.id,
174                    "MediaStream::serve() called multiple times, stream already serving"
175                );
176                return Ok(());
177            }
178        };
179        self.start_recorder().await.ok();
180        info!(session_id = self.id, "mediastream serving");
181        select! {
182            _ = self.cancel_token.cancelled() => {}
183            r = self.handle_forward_track(packet_receiver) => {
184                info!(session_id = self.id, "track packet receiver stopped {:?}", r);
185            }
186        }
187        Ok(())
188    }
189
190    /// Load ambiance once per call and keep mixing it while TTS/file playback is silent.
191    pub async fn ensure_ambiance(
192        &self,
193        option: AmbianceOption,
194        source_track_id: TrackId,
195    ) -> Result<Option<Arc<StdMutex<AmbianceProcessor>>>> {
196        let mut slot = self.ambiance.lock().await;
197        if let Some(existing) = slot.as_ref() {
198            return Ok(Some(existing.clone()));
199        }
200
201        if option.path.is_none() || option.enabled == Some(false) {
202            return Ok(None);
203        }
204
205        let processor = AmbianceProcessor::new(option).await?;
206        let shared = Arc::new(StdMutex::new(processor));
207        *slot = Some(shared.clone());
208        drop(slot);
209
210        *self.ambiance_source_id.lock().unwrap() = Some(source_track_id);
211        self.start_ambiance_idle_loop(shared.clone());
212        info!(session_id = self.id, "ambiance idle mixer started");
213        Ok(Some(shared))
214    }
215
216    fn start_ambiance_idle_loop(&self, processor: Arc<StdMutex<AmbianceProcessor>>) {
217        if self.ambiance_idle_started.swap(true, Ordering::SeqCst) {
218            return;
219        }
220
221        let cancel_token = self.cancel_token.clone();
222        let packet_sender = self.packet_sender.clone();
223        let last_server_packet_ts = self.last_server_packet_ts.clone();
224        let session_id = self.id.clone();
225        let recorder_sender = self.recorder_sender.clone();
226        let recording_active = self.recording_active.clone();
227
228        crate::spawn(async move {
229            let mut ticker = tokio::time::interval(AMBIANCE_IDLE_PTIME);
230            ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
231            loop {
232                tokio::select! {
233                    _ = cancel_token.cancelled() => break,
234                    _ = ticker.tick() => {
235                        let now = crate::media::get_timestamp();
236                        let last = last_server_packet_ts.load(Ordering::Relaxed);
237                        if last != 0 && now.saturating_sub(last) < AMBIANCE_IDLE_GAP_MS {
238                            continue;
239                        }
240
241                        let mut frame = AudioFrame {
242                            track_id: AMBIANCE_IDLE_TRACK_ID.to_string(),
243                            samples: Samples::Empty,
244                            timestamp: now,
245                            sample_rate: INTERNAL_SAMPLERATE,
246                            channels: 1,
247                            ..Default::default()
248                        };
249                        {
250                            let mut ambiance = match processor.lock() {
251                                Ok(guard) => guard,
252                                Err(_) => break,
253                            };
254                            if let Err(e) = ambiance.process_frame(&mut frame) {
255                                warn!(session_id, "ambiance idle mix failed: {}", e);
256                                continue;
257                            }
258                        }
259                        if matches!(frame.samples, Samples::Empty) {
260                            continue;
261                        }
262                        // Mirror the mixed idle ambiance into the recording so the
263                        // stereo WAV's server-side channel reflects what the user
264                        // actually heard, including silent-period background audio.
265                        if recording_active.load(Ordering::SeqCst) {
266                            let mut recorded = frame.clone();
267                            recorded.track_id = SERVER_SIDE_TRACK_ID.to_string();
268                            let _ = recorder_sender.send(recorded);
269                        }
270                        if packet_sender.send(frame).is_err() {
271                            debug!(session_id, "ambiance idle sender closed");
272                            break;
273                        }
274                    }
275                }
276            }
277        });
278    }
279
280    pub fn stop(&self, _reason: Option<String>, _initiator: Option<String>) {
281        self.cancel_token.cancel()
282    }
283
284    pub async fn cleanup(&self) -> Result<()> {
285        self.cancel_token.cancel();
286        {
287            let mut tracks = self.tracks.lock().await;
288            TRACKS_LIVE.fetch_sub(tracks.len(), Ordering::Relaxed);
289            for (id, (track, _)) in tracks.drain() {
290                if let Err(e) = track.stop().await {
291                    warn!(session_id = self.id, track_id = %id, "failed to stop track during cleanup: {}", e);
292                }
293            }
294        }
295        self.suppressed_sources.lock().await.clear();
296
297        if let Some(recorder_handle) = self.recorder_handle.lock().await.take() {
298            // The supervisor stops the recorder now that the stream is
299            // cancelled, unless it handed the recording to a bridged peer:
300            // then the recording runs until the peer is done with it.
301            self.recorder_stop.cancelled().await;
302            if let Ok(Ok(_)) = tokio::time::timeout(Duration::from_secs(30), recorder_handle).await
303            {
304                info!(session_id = self.id, "recorder stopped");
305            } else {
306                warn!(session_id = self.id, "recorder timeout");
307                RECORDER_DETACHED.fetch_add(1, Ordering::Relaxed);
308            }
309        }
310        Ok(())
311    }
312    pub async fn track_count(&self) -> usize {
313        self.tracks.lock().await.len()
314    }
315
316    /// Record the stream this one is bridged to (`None` when unbridged). A
317    /// new bridge ends recordings adopted from a previous peer: that call is
318    /// over and this leg now talks to someone else.
319    pub fn set_bridge_peer(&self, peer: Option<&Arc<MediaStream>>) {
320        if peer.is_some() {
321            for recording in self.adopted_recorders.lock().unwrap().drain(..) {
322                recording.stop.cancel();
323            }
324        }
325        *self.bridge_peer.lock().unwrap() = peer.map(|p| BridgePeer {
326            id: p.id.clone(),
327            stream: Arc::downgrade(p),
328        });
329    }
330
331    /// Clear the bridge peer if it is `peer_id`.
332    pub fn clear_bridge_peer(&self, peer_id: &str) {
333        let mut peer = self.bridge_peer.lock().unwrap();
334        if peer.as_ref().is_some_and(|p| p.id == peer_id) {
335            *peer = None;
336        }
337    }
338
339    pub async fn update_recorder_option(&self, recorder_config: RecorderOption) {
340        *self.recorder_option.lock().await = Some(recorder_config);
341        self.start_recorder().await.ok();
342    }
343
344    /// Create the session's monitor hub on first use and return it. Idempotent.
345    pub async fn enable_monitor(&self) -> MonitorHub {
346        let mut slot = self.monitor_hub.lock().await;
347        if let Some(hub) = slot.as_ref() {
348            return hub.clone();
349        }
350        let hub = MonitorHub::new();
351        *slot = Some(hub.clone());
352        drop(slot);
353        info!(session_id = self.id, "monitor hub enabled");
354        hub
355    }
356
357    /// The session's monitor hub, if `enable_monitor` was called.
358    pub async fn monitor_hub(&self) -> Option<MonitorHub> {
359        self.monitor_hub.lock().await.clone()
360    }
361
362    /// Whether a track that has not ended is registered under `id`.
363    pub async fn has_live_track(&self, id: &TrackId) -> bool {
364        self.tracks
365            .lock()
366            .await
367            .get(id)
368            .is_some_and(|(track, _)| !track.has_ended())
369    }
370
371    pub async fn remove_track(&self, id: &TrackId, graceful: bool) {
372        let track_entry = {
373            let removed = self.tracks.lock().await.remove(id);
374            if removed.is_some() {
375                TRACKS_LIVE.fetch_sub(1, Ordering::Relaxed);
376            }
377            removed
378        };
379        if let Some((track, _)) = track_entry {
380            self.suppressed_sources.lock().await.remove(id);
381            let res = if !graceful {
382                track.stop().await
383            } else {
384                track.stop_graceful().await
385            };
386            match res {
387                Ok(_) => {}
388                Err(e) => {
389                    warn!(session_id = self.id, "failed to stop track: {}", e);
390                }
391            }
392        }
393    }
394    pub async fn update_remote_description(
395        &self,
396        track_id: &TrackId,
397        answer: &String,
398    ) -> Result<()> {
399        let track_entry = {
400            let removed = self.tracks.lock().await.remove(track_id);
401            if removed.is_some() {
402                TRACKS_LIVE.fetch_sub(1, Ordering::Relaxed);
403            }
404            removed
405        };
406        if let Some((mut track, dtmf)) = track_entry {
407            let res = track.update_remote_description(answer).await;
408            self.tracks
409                .lock()
410                .await
411                .insert(track_id.clone(), (track, dtmf));
412                TRACKS_LIVE.fetch_add(1, Ordering::Relaxed);
413            res?;
414        }
415        Ok(())
416    }
417
418    pub async fn update_remote_description_force(
419        &self,
420        track_id: &TrackId,
421        answer: &String,
422    ) -> Result<()> {
423        let track_entry = {
424            let removed = self.tracks.lock().await.remove(track_id);
425            if removed.is_some() {
426                TRACKS_LIVE.fetch_sub(1, Ordering::Relaxed);
427            }
428            removed
429        };
430        if let Some((mut track, dtmf)) = track_entry {
431            let res = track.update_remote_description_force(answer).await;
432            self.tracks
433                .lock()
434                .await
435                .insert(track_id.clone(), (track, dtmf));
436                TRACKS_LIVE.fetch_add(1, Ordering::Relaxed);
437            res?;
438        }
439        Ok(())
440    }
441
442    /// Apply a provisional remote description (SIP 183 early media). See
443    /// `Track::update_remote_description_provisional`.
444    pub async fn update_remote_description_provisional(
445        &self,
446        track_id: &TrackId,
447        answer: &String,
448    ) -> Result<()> {
449        let track_entry = {
450            let removed = self.tracks.lock().await.remove(track_id);
451            if removed.is_some() {
452                TRACKS_LIVE.fetch_sub(1, Ordering::Relaxed);
453            }
454            removed
455        };
456        if let Some((mut track, dtmf)) = track_entry {
457            let res = track.update_remote_description_provisional(answer).await;
458            self.tracks
459                .lock()
460                .await
461                .insert(track_id.clone(), (track, dtmf));
462                TRACKS_LIVE.fetch_add(1, Ordering::Relaxed);
463            res?;
464        }
465        Ok(())
466    }
467
468    pub async fn handshake(
469        &self,
470        track_id: &TrackId,
471        offer: String,
472        timeout: Option<Duration>,
473    ) -> Result<String> {
474        let track_entry = {
475            let removed = self.tracks.lock().await.remove(track_id);
476            if removed.is_some() {
477                TRACKS_LIVE.fetch_sub(1, Ordering::Relaxed);
478            }
479            removed
480        };
481        if let Some((mut track, dtmf)) = track_entry {
482            let res = track.handshake(offer, timeout).await;
483            self.tracks
484                .lock()
485                .await
486                .insert(track_id.clone(), (track, dtmf));
487                TRACKS_LIVE.fetch_add(1, Ordering::Relaxed);
488            res
489        } else {
490            anyhow::bail!("track not found: {}", track_id)
491        }
492    }
493
494    pub async fn update_track(&self, mut track: Box<dyn Track>, play_id: Option<String>) {
495        // Detach the replaced track WITHOUT closing its transport right away:
496        // the predecessor's PeerConnection teardown races against the
497        // successor's media setup and can leave the successor completely deaf
498        // (inbound RTP never demuxed — INVITE-mode auto-refer transfers hit
499        // exactly this: the transfer leg consumed no media and the session
500        // was hung up by the inactivity watchdog ~50s later). Disarm the old
501        // track's pipeline (inactivity watchdog, workers) now, and close its
502        // transport after a short grace period.
503        let replaced = {
504            let removed = self.tracks.lock().await.remove(track.id());
505            if removed.is_some() {
506                TRACKS_LIVE.fetch_sub(1, Ordering::Relaxed);
507            }
508            removed
509        };
510        if let Some((old_track, _)) = replaced {
511            old_track.cancel_pipeline();
512            crate::spawn(async move {
513                tokio::time::sleep(Duration::from_secs(3)).await;
514                let _ = old_track.stop().await;
515            });
516        }
517        self.attach_recorder_tap(&mut track).await;
518        match track
519            .start(self.event_sender.clone(), self.packet_sender.clone())
520            .await
521        {
522            Ok(_) => {
523                info!(session_id = self.id, track_id = track.id(), "track started");
524                let track_id = track.id().clone();
525                if track_id.as_str() == self.id.as_str() {
526                    let pending = std::mem::take(&mut *self.pending_ice_candidates.lock().await);
527                    for (candidate, sdp_mid, sdp_mline_index) in pending {
528                        if let Err(e) =
529                            track.add_ice_candidate(&candidate, sdp_mid.as_deref(), sdp_mline_index)
530                        {
531                            warn!(
532                                session_id = self.id,
533                                track_id = track.id(),
534                                "failed to apply buffered ICE candidate: {}",
535                                e
536                            );
537                        }
538                    }
539                }
540                self.tracks
541                    .lock()
542                    .await
543                    .insert(track_id.clone(), (track, DtmfDetector::new()));
544                TRACKS_LIVE.fetch_add(1, Ordering::Relaxed);
545                self.event_sender
546                    .send(SessionEvent::TrackStart {
547                        track_id,
548                        timestamp: crate::media::get_timestamp(),
549                        play_id,
550                    })
551                    .ok();
552            }
553            Err(e) => {
554                warn!(
555                    session_id = self.id,
556                    track_id = track.id(),
557                    play_id = play_id.as_deref(),
558                    "Failed to start track: {}",
559                    e
560                );
561            }
562        }
563    }
564
565    pub async fn mute_track(&self, id: Option<TrackId>) {
566        if let Some(id) = id {
567            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
568                MuteProcessor::mute_track(track.as_mut());
569            }
570        } else {
571            for (track, _) in self.tracks.lock().await.values_mut() {
572                MuteProcessor::mute_track(track.as_mut());
573            }
574        }
575    }
576
577    pub async fn unmute_track(&self, id: Option<TrackId>) {
578        if let Some(id) = id {
579            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
580                MuteProcessor::unmute_track(track.as_mut());
581            }
582        } else {
583            for (track, _) in self.tracks.lock().await.values_mut() {
584                MuteProcessor::unmute_track(track.as_mut());
585            }
586        }
587    }
588
589    /// Apply a new remote offer to the session's own (WebRTC) track without
590    /// recreating it, e.g. for an ICE restart, and return the new answer.
591    pub async fn renegotiate(&self, offer: String) -> Result<String> {
592        // hold the lock across the handshake (instead of taking the track out
593        // of the map like `handshake` does), so a trickled candidate for the
594        // new ICE generation waits for it rather than landing in
595        // `pending_ice_candidates`, which is only replayed on `update_track`
596        let mut tracks = self.tracks.lock().await;
597        let Some((track, _)) = tracks.get_mut(self.id.as_str()) else {
598            anyhow::bail!("track not found: {}", self.id)
599        };
600        let answer = track.handshake(offer, None).await?;
601        if answer.is_empty() {
602            anyhow::bail!("track {} does not support renegotiation", self.id)
603        }
604        Ok(answer)
605    }
606
607    /// See `Track::on_answered`.
608    pub async fn on_answered(&self, track_id: &TrackId, rtp_timeout: Option<Duration>) {
609        if let Some((track, _)) = self.tracks.lock().await.get(track_id) {
610            track.on_answered(rtp_timeout);
611        }
612    }
613
614    /// Trickle ICE: feed a remote candidate into the ICE-backed (WebRTC)
615    /// track, if it's up yet, or buffer it for `update_track` to replay
616    /// otherwise.
617    pub async fn add_ice_candidate(
618        &self,
619        candidate: &str,
620        sdp_mid: Option<&str>,
621        sdp_mline_index: Option<u32>,
622    ) -> Result<()> {
623        let tracks = self.tracks.lock().await;
624        if let Some((track, _)) = tracks.get(self.id.as_str()) {
625            track.add_ice_candidate(candidate, sdp_mid, sdp_mline_index)?;
626            return Ok(());
627        }
628        drop(tracks);
629        self.pending_ice_candidates.lock().await.push((
630            candidate.to_string(),
631            sdp_mid.map(|s| s.to_string()),
632            sdp_mline_index,
633        ));
634        Ok(())
635    }
636
637    pub async fn pause_playback(&self, id: TrackId) -> Result<()> {
638        self.set_playback_paused(id, true).await
639    }
640
641    pub async fn resume_playback(&self, id: TrackId) -> Result<()> {
642        self.set_playback_paused(id, false).await
643    }
644
645    async fn set_playback_paused(&self, id: TrackId, paused: bool) -> Result<()> {
646        if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
647            if track.set_paused(paused) {
648                Ok(())
649            } else {
650                warn!(
651                    session_id = self.id,
652                    track_id = %id,
653                    paused,
654                    "pause state requested for track that does not support pausing"
655                );
656                Err(anyhow::anyhow!("track does not support pausing: {}", id))
657            }
658        } else {
659            warn!(
660                session_id = self.id,
661                track_id = %id,
662                paused,
663                "pause state requested for unknown track"
664            );
665            Err(anyhow::anyhow!("track not found: {}", id))
666        }
667    }
668
669    pub async fn hold_track(&self, id: Option<TrackId>) {
670        if let Some(id) = id {
671            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
672                HoldTrack::hold_track(track.as_mut());
673            }
674        } else {
675            for (track, _) in self.tracks.lock().await.values_mut() {
676                HoldTrack::hold_track(track.as_mut());
677            }
678        }
679    }
680
681    pub async fn resume_track(&self, id: Option<TrackId>) {
682        if let Some(id) = id {
683            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
684                HoldTrack::resume_track(track.as_mut());
685            }
686        } else {
687            for (track, _) in self.tracks.lock().await.values_mut() {
688                HoldTrack::resume_track(track.as_mut());
689            }
690        }
691    }
692
693    pub async fn suppress_forwarding(&self, track_id: &TrackId) {
694        self.suppressed_sources
695            .lock()
696            .await
697            .insert(track_id.clone());
698    }
699
700    pub async fn resume_forwarding(&self, track_id: &TrackId) {
701        self.suppressed_sources.lock().await.remove(track_id);
702    }
703
704    pub async fn remove_processor<T: 'static>(&self, track_id: &TrackId) -> Result<()> {
705        if let Some((track, _)) = self.tracks.lock().await.get_mut(track_id) {
706            track.as_mut().processor_chain().remove_processor::<T>();
707            Ok(())
708        } else {
709            Err(anyhow::anyhow!("Track {} not found", track_id))
710        }
711    }
712
713    pub async fn append_processor(
714        &self,
715        track_id: &TrackId,
716        processor: Box<dyn crate::media::processor::Processor>,
717    ) -> Result<()> {
718        if let Some((track, _)) = self.tracks.lock().await.get_mut(track_id) {
719            track.as_mut().processor_chain().append_processor(processor);
720            Ok(())
721        } else {
722            Err(anyhow::anyhow!("Track {} not found", track_id))
723        }
724    }
725}
726
727#[derive(Clone)]
728pub struct RecorderProcessor {
729    sender: mpsc::UnboundedSender<AudioFrame>,
730    /// Only frames tagged with this track id are mirrored. A track may relay
731    /// another leg's audio (e.g. the media-pass track forwards the caller's
732    /// audio to the websocket); that relayed copy is already recorded at its
733    /// origin and must not be written to the recording a second time.
734    owner: TrackId,
735}
736
737impl RecorderProcessor {
738    pub fn new(sender: mpsc::UnboundedSender<AudioFrame>, owner: TrackId) -> Self {
739        Self { sender, owner }
740    }
741}
742
743impl Processor for RecorderProcessor {
744    fn process_frame(&mut self, frame: &mut AudioFrame) -> Result<()> {
745        if frame.track_id == self.owner {
746            let _ = self.sender.send(frame.clone());
747        }
748        Ok(())
749    }
750}
751
752impl MediaStream {
753    pub async fn start_recorder(&self) -> Result<()> {
754        let recorder_option = self.recorder_option.lock().await.clone();
755        if let Some(recorder_option) = recorder_option {
756            if recorder_option.recorder_file.is_empty() {
757                warn!(
758                    session_id = self.id,
759                    "recorder file is empty, skipping recorder start"
760                );
761                return Ok(());
762            }
763            let recorder_receiver = match self.recorder_receiver.lock().await.take() {
764                Some(receiver) => receiver,
765                None => {
766                    return Ok(());
767                }
768            };
769            let cancel_token = self.recorder_stop.clone();
770            let session_id_clone = self.id.clone();
771
772            info!(
773                session_id = session_id_clone,
774                sample_rate = recorder_option.samplerate,
775                native_samplerate = recorder_option.native_samplerate.unwrap_or(false),
776                ptime = recorder_option.ptime,
777                "start recorder",
778            );
779
780            let native = recorder_option.native_samplerate.unwrap_or(false);
781            RECORDER_SPAWNED.fetch_add(1, Ordering::Relaxed);
782            RECORDER_LIVE.fetch_add(1, Ordering::Relaxed);
783            let follow_bridge = recorder_option.follow_bridge.unwrap_or(false);
784            let recorder_stop = self.recorder_stop.clone();
785            let recorder_handle = crate::spawn(async move {
786                let recorder_file = recorder_option.recorder_file.clone();
787                let recorder =
788                    Recorder::new(cancel_token, session_id_clone.clone(), recorder_option);
789                match recorder
790                    .process_recording(Path::new(&recorder_file), recorder_receiver)
791                    .await
792                {
793                    Ok(_) => {}
794                    Err(e) => {
795                        warn!(
796                            session_id = session_id_clone,
797                            "Failed to process recorder: {}", e
798                        );
799                    }
800                }
801                RECORDER_LIVE.fetch_sub(1, Ordering::Relaxed);
802                // A failed recorder must not keep cleanup waiting.
803                recorder_stop.cancel();
804            });
805            *self.recorder_handle.lock().await = Some(recorder_handle);
806            self.spawn_recorder_supervisor(follow_bridge);
807            self.recording_active.store(true, Ordering::SeqCst);
808
809            // Inject the recorder tap into tracks that were added before the
810            // recorder started. `set_raw_tap` replaces any previous tap, so
811            // this stays idempotent.
812            for (track, _) in self.tracks.lock().await.values_mut() {
813                if native {
814                    track.set_raw_tap(Some(self.recorder_sender.clone()));
815                } else {
816                    let owner = track.id().clone();
817                    // Go through the chain directly: the media-pass track
818                    // deliberately ignores `Track::insert_processor`, but the
819                    // audio it plays into the call must still be recorded.
820                    let chain = track.processor_chain();
821                    if !chain.has_processor::<RecorderProcessor>() {
822                        chain.append_processor(Box::new(RecorderProcessor::new(
823                            self.recorder_sender.clone(),
824                            owner,
825                        )));
826                    }
827                }
828            }
829        }
830        Ok(())
831    }
832
833    /// Stop the recorder once the stream ends or, with `follow_bridge`, hand
834    /// the recording to the bridged peer and stop it when the peer is done.
835    fn spawn_recorder_supervisor(&self, follow_bridge: bool) {
836        let stream_cancel = self.cancel_token.clone();
837        let recorder_stop = self.recorder_stop.clone();
838        let bridge_peer = self.bridge_peer.clone();
839        let recording = AdoptedRecorder {
840            sender: self.recorder_sender.clone(),
841            own_leg: self.id.clone(),
842            stop: self.recorder_stop.clone(),
843        };
844        let session_id = self.id.clone();
845        crate::spawn(async move {
846            select! {
847                _ = recorder_stop.cancelled() => return,
848                _ = stream_cancel.cancelled() => {}
849            }
850            let adopted_by = follow_bridge
851                .then(|| bridge_peer.lock().unwrap().clone())
852                .flatten()
853                .and_then(|p| p.stream.upgrade())
854                .and_then(|stream| stream.adopt_recorder(recording));
855            if let Some(peer_cancel) = adopted_by {
856                info!(session_id, "recording handed over to bridged peer");
857                select! {
858                    _ = peer_cancel.cancelled() => {}
859                    _ = recorder_stop.cancelled() => {}
860                }
861            }
862            recorder_stop.cancel();
863        });
864    }
865
866    /// Take over feeding the recording of an ended bridged peer; returns
867    /// this stream's cancel token, which ends the recording at the latest.
868    /// Refused when this stream has ended or is no longer bridged back to
869    /// that peer (e.g. it was already bridged to someone else).
870    fn adopt_recorder(&self, recording: AdoptedRecorder) -> Option<CancellationToken> {
871        let bridged_back = self
872            .bridge_peer
873            .lock()
874            .unwrap()
875            .as_ref()
876            .is_some_and(|p| p.id == recording.own_leg);
877        if self.cancel_token.is_cancelled() || !bridged_back {
878            return None;
879        }
880        self.adopted_recorders.lock().unwrap().push(recording);
881        Some(self.cancel_token.clone())
882    }
883
884    /// Mirror a frame from one of this stream's tracks to the recordings
885    /// adopted from ended bridged peers. This stream's own leg is the far
886    /// side of those recordings; everything else it plays (TTS, files,
887    /// ambiance) takes the ended peer's place on the own channel.
888    fn feed_adopted_recorders(&self, frame: &AudioFrame) {
889        let mut adopted = self.adopted_recorders.lock().unwrap();
890        adopted.retain(|r| !r.stop.is_cancelled());
891        if adopted.is_empty()
892            || !matches!(frame.samples, Samples::PCM { .. })
893            // Bridge tracks carry the ended peer's own audio.
894            || frame.track_id.starts_with(BRIDGE_TRACK_PREFIX)
895        {
896            return;
897        }
898        for recording in adopted.iter() {
899            let mut mirrored = frame.clone();
900            if mirrored.track_id != self.id {
901                mirrored.track_id = recording.own_leg.clone();
902            }
903            let _ = recording.sender.send(mirrored);
904        }
905    }
906
907    /// Attach the recorder tap to a track according to the recorder mode:
908    /// native-samplerate mode mirrors pre-resample frames via the chain's
909    /// raw tap, otherwise a post-pipeline RecorderProcessor is appended to
910    /// the track's processor chain. No-op when no recorder is configured.
911    async fn attach_recorder_tap(&self, track: &mut Box<dyn Track>) {
912        let Some(option) = self.recorder_option.lock().await.clone() else {
913            return;
914        };
915        if option.native_samplerate.unwrap_or(false) {
916            track.set_raw_tap(Some(self.recorder_sender.clone()));
917        } else {
918            let owner = track.id().clone();
919            // Reach into the processor chain directly rather than calling
920            // `Track::append_processor`: the media-pass track rejects that
921            // (it ignores audio processors) yet still needs to feed the
922            // recorder with the audio it plays into the call.
923            track
924                .processor_chain()
925                .append_processor(Box::new(RecorderProcessor::new(
926                    self.recorder_sender.clone(),
927                    owner,
928                )));
929        }
930    }
931
932    pub async fn set_track_refer(&self, track_id: &TrackId, refer: Option<bool>) {
933        if let Some((_, dtmf)) = self.tracks.lock().await.get_mut(track_id) {
934            dtmf.refer = refer;
935        }
936    }
937
938    pub async fn set_track_dtmf_forward(&self, track_id: &TrackId, forward: bool) {
939        if let Some((_, dtmf)) = self.tracks.lock().await.get_mut(track_id) {
940            dtmf.suppress_dtmf_forward = !forward;
941        }
942    }
943
944    async fn handle_forward_track(&self, mut packet_receiver: TrackPacketReceiver) {
945        let event_sender = self.event_sender.clone();
946        while let Some(packet) = packet_receiver.recv().await {
947            self.feed_adopted_recorders(&packet);
948            if self
949                .ambiance_source_id
950                .lock()
951                .ok()
952                .and_then(|id| id.clone())
953                .as_ref()
954                == Some(&packet.track_id)
955            {
956                self.last_server_packet_ts
957                    .store(crate::media::get_timestamp(), Ordering::Relaxed);
958            }
959
960            let suppressed = {
961                self.suppressed_sources
962                    .lock()
963                    .await
964                    .contains(&packet.track_id)
965            };
966
967            let is_dtmf = matches!(&packet.samples,
968                Samples::RTP { payload_type, .. } if *payload_type >= 96 && *payload_type <= 127);
969
970            let mut tracks = self.tracks.lock().await;
971
972            // Check once whether the source track suppresses DTMF forwarding.
973            let source_suppresses_dtmf = is_dtmf
974                && tracks
975                    .get(&packet.track_id)
976                    .map(|(_, d)| d.suppress_dtmf_forward)
977                    .unwrap_or(false);
978
979            for (track, dtmf_detector) in tracks.values_mut() {
980                if track.id() == &packet.track_id {
981                    if let Samples::RTP {
982                        payload_type,
983                        payload,
984                        ..
985                    } = &packet.samples
986                    {
987                        if let Some(digit) = dtmf_detector.detect_rtp(*payload_type, payload) {
988                            debug!(track_id = track.id(), digit, "DTMF detected");
989                            event_sender
990                                .send(SessionEvent::Dtmf {
991                                    track_id: packet.track_id.to_string(),
992                                    timestamp: packet.timestamp,
993                                    digit,
994                                    refer: dtmf_detector.refer,
995                                })
996                                .ok();
997                        }
998                    }
999                    continue;
1000                }
1001                if suppressed {
1002                    continue;
1003                }
1004                // Skip DTMF forwarding if source or destination has it suppressed.
1005                if source_suppresses_dtmf || (is_dtmf && dtmf_detector.suppress_dtmf_forward) {
1006                    continue;
1007                }
1008                if packet.track_id == QUEUE_HOLD_TRACK_ID && track.id() == CALLEE_TRACK_ID {
1009                    continue;
1010                }
1011                if let Err(e) = track.send_packet(&packet).await {
1012                    warn!(
1013                        id = track.id(),
1014                        "media_stream: Failed to send packet to track: {}", e
1015                    );
1016                }
1017            }
1018        }
1019    }
1020}
1021
1022pub struct MuteProcessor;
1023
1024impl MuteProcessor {
1025    pub fn mute_track(track: &mut dyn Track) {
1026        let chain = track.processor_chain();
1027        if !chain.has_processor::<MuteProcessor>() {
1028            chain.insert_processor(Box::new(MuteProcessor));
1029        }
1030    }
1031
1032    pub fn unmute_track(track: &mut dyn Track) {
1033        let chain = track.processor_chain();
1034        chain.remove_processor::<MuteProcessor>();
1035    }
1036}
1037
1038impl Processor for MuteProcessor {
1039    fn process_frame(&mut self, frame: &mut AudioFrame) -> Result<()> {
1040        match &mut frame.samples {
1041            Samples::PCM { samples } => {
1042                samples.fill(0);
1043            }
1044            // discard DTMF frames
1045            Samples::RTP { payload_type, .. } if *payload_type >= 96 && *payload_type <= 127 => {
1046                frame.samples = Samples::Empty;
1047            }
1048            _ => {}
1049        }
1050        Ok(())
1051    }
1052}
1053
1054pub struct HoldTrack;
1055
1056impl HoldTrack {
1057    pub fn hold_track(track: &mut dyn Track) {
1058        let chain = track.processor_chain();
1059        // Remove existing processor if present
1060        chain.remove_processor::<HoldProcessor>();
1061        // Add a new processor with hold state set to true
1062        let processor = HoldProcessor::new();
1063        processor.set_hold(true);
1064        chain.insert_processor(Box::new(processor));
1065    }
1066
1067    pub fn resume_track(track: &mut dyn Track) {
1068        let chain = track.processor_chain();
1069        // Simply remove the hold processor to resume normal operation
1070        chain.remove_processor::<HoldProcessor>();
1071    }
1072}
1073
1074#[cfg(test)]
1075mod recorder_owner_tests {
1076    use super::*;
1077    use crate::media::Samples;
1078
1079    fn pcm_frame(track_id: &str, len: usize) -> AudioFrame {
1080        AudioFrame {
1081            track_id: track_id.to_string(),
1082            samples: Samples::PCM {
1083                samples: vec![100i16; len],
1084            },
1085            sample_rate: 16000,
1086            channels: 1,
1087            ..Default::default()
1088        }
1089    }
1090
1091    /// Regression for media-pass recordings in non-native mode: the track's own
1092    /// processor chain also processes audio it relays for another leg (the
1093    /// caller's audio forwarded to the websocket). `RecorderProcessor` must
1094    /// mirror only the track's own frames so the relayed copy is not written to
1095    /// the recording twice.
1096    #[test]
1097    fn recorder_processor_only_mirrors_owned_frames() {
1098        let (tx, mut rx) = mpsc::unbounded_channel();
1099        let mut processor = RecorderProcessor::new(tx, "server-side-track".to_string());
1100
1101        let mut relayed = pcm_frame("caller-leg", 160);
1102        processor.process_frame(&mut relayed).unwrap();
1103        assert!(
1104            rx.try_recv().is_err(),
1105            "relayed caller audio must not be recorded"
1106        );
1107
1108        let mut own = pcm_frame("server-side-track", 160);
1109        processor.process_frame(&mut own).unwrap();
1110        let mirrored = rx
1111            .try_recv()
1112            .expect("the track's own audio must be recorded");
1113        assert_eq!(mirrored.track_id, "server-side-track");
1114    }
1115
1116    /// A bare `RecorderProcessor` (e.g. attached to the caller leg) records its
1117    /// own frames and ignores anything else.
1118    #[test]
1119    fn recorder_processor_records_caller_leg_only() {
1120        let (tx, mut rx) = mpsc::unbounded_channel();
1121        let mut processor = RecorderProcessor::new(tx, "caller-leg".to_string());
1122
1123        let mut own = pcm_frame("caller-leg", 160);
1124        processor.process_frame(&mut own).unwrap();
1125        assert!(rx.try_recv().is_ok());
1126
1127        let mut foreign = pcm_frame("server-side-track", 160);
1128        processor.process_frame(&mut foreign).unwrap();
1129        assert!(rx.try_recv().is_err());
1130    }
1131}