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,
17    atomic::{AtomicBool, AtomicU64, 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
29pub struct MediaStream {
30    id: String,
31    pub cancel_token: CancellationToken,
32    recorder_option: Mutex<Option<RecorderOption>>,
33    tracks: Mutex<HashMap<TrackId, (Box<dyn Track>, DtmfDetector)>>,
34    /// Trickle ICE candidates that arrived before any track existed to feed
35    /// them to. Drained into the next track started.
36    pending_ice_candidates: Mutex<Vec<(String, Option<String>, Option<u32>)>>,
37    suppressed_sources: Mutex<HashSet<TrackId>>,
38    event_sender: EventSender,
39    pub packet_sender: TrackPacketSender,
40    packet_receiver: Mutex<Option<TrackPacketReceiver>>,
41    recorder_sender: mpsc::UnboundedSender<AudioFrame>,
42    recorder_receiver: Mutex<Option<mpsc::UnboundedReceiver<AudioFrame>>>,
43    recorder_handle: Mutex<Option<JoinHandle<()>>>,
44    /// True once a recorder task is actually consuming `recorder_sender`.
45    /// The ambiance idle loop mirrors its frames to the recorder only when
46    /// this is set, avoiding unbounded buffering when recording starts late.
47    recording_active: Arc<AtomicBool>,
48    ambiance: Mutex<Option<Arc<StdMutex<AmbianceProcessor>>>>,
49    ambiance_source_id: StdMutex<Option<TrackId>>,
50    last_server_packet_ts: Arc<AtomicU64>,
51    ambiance_idle_started: AtomicBool,
52    /// Side-path audio distribution hub (see `media::monitor`). Lazily
53    /// created by `enable_monitor` when the call option asks for it.
54    monitor_hub: Mutex<Option<MonitorHub>>,
55}
56
57const CALLEE_TRACK_ID: &str = "callee-track";
58const QUEUE_HOLD_TRACK_ID: &str = "queue-hold-track";
59pub const SERVER_SIDE_TRACK_ID: &str = "server-side-track";
60const AMBIANCE_IDLE_TRACK_ID: &str = "ambiance-track";
61const AMBIANCE_IDLE_PTIME: Duration = Duration::from_millis(20);
62// Skip idle fill if server-side audio arrived within this window (TTS ptime is 20ms).
63const AMBIANCE_IDLE_GAP_MS: u64 = 25;
64
65pub struct MediaStreamBuilder {
66    cancel_token: Option<CancellationToken>,
67    id: Option<String>,
68    event_sender: EventSender,
69    recorder_config: Option<RecorderOption>,
70}
71
72impl MediaStreamBuilder {
73    pub fn new(event_sender: EventSender) -> Self {
74        Self {
75            id: Some(format!("ms:{}", uuid::Uuid::new_v4())),
76            cancel_token: None,
77            event_sender,
78            recorder_config: None,
79        }
80    }
81    pub fn with_id(mut self, id: String) -> Self {
82        self.id = Some(id);
83        self
84    }
85
86    pub fn with_cancel_token(mut self, cancel_token: CancellationToken) -> Self {
87        self.cancel_token = Some(cancel_token);
88        self
89    }
90
91    pub fn with_recorder_config(mut self, recorder_config: RecorderOption) -> Self {
92        self.recorder_config = Some(recorder_config);
93        self
94    }
95
96    pub fn build(self) -> MediaStream {
97        let cancel_token = self
98            .cancel_token
99            .unwrap_or_else(|| CancellationToken::new());
100        let tracks = Mutex::new(HashMap::new());
101        let (track_packet_sender, track_packet_receiver) = mpsc::unbounded_channel();
102        let (recorder_sender, recorder_receiver) = mpsc::unbounded_channel();
103        MediaStream {
104            id: self.id.unwrap_or_default(),
105            cancel_token,
106            recorder_option: Mutex::new(self.recorder_config),
107            tracks,
108            pending_ice_candidates: Mutex::new(Vec::new()),
109            suppressed_sources: Mutex::new(HashSet::new()),
110            event_sender: self.event_sender,
111            packet_sender: track_packet_sender,
112            packet_receiver: Mutex::new(Some(track_packet_receiver)),
113            recorder_sender,
114            recorder_receiver: Mutex::new(Some(recorder_receiver)),
115            recorder_handle: Mutex::new(None),
116            recording_active: Arc::new(AtomicBool::new(false)),
117            ambiance: Mutex::new(None),
118            ambiance_source_id: StdMutex::new(None),
119            last_server_packet_ts: Arc::new(AtomicU64::new(0)),
120            ambiance_idle_started: AtomicBool::new(false),
121            monitor_hub: Mutex::new(None),
122        }
123    }
124}
125
126impl MediaStream {
127    pub async fn serve(&self) -> Result<()> {
128        let packet_receiver = match self.packet_receiver.lock().await.take() {
129            Some(receiver) => receiver,
130            None => {
131                warn!(
132                    session_id = self.id,
133                    "MediaStream::serve() called multiple times, stream already serving"
134                );
135                return Ok(());
136            }
137        };
138        self.start_recorder().await.ok();
139        info!(session_id = self.id, "mediastream serving");
140        select! {
141            _ = self.cancel_token.cancelled() => {}
142            r = self.handle_forward_track(packet_receiver) => {
143                info!(session_id = self.id, "track packet receiver stopped {:?}", r);
144            }
145        }
146        Ok(())
147    }
148
149    /// Load ambiance once per call and keep mixing it while TTS/file playback is silent.
150    pub async fn ensure_ambiance(
151        &self,
152        option: AmbianceOption,
153        source_track_id: TrackId,
154    ) -> Result<Option<Arc<StdMutex<AmbianceProcessor>>>> {
155        let mut slot = self.ambiance.lock().await;
156        if let Some(existing) = slot.as_ref() {
157            return Ok(Some(existing.clone()));
158        }
159
160        if option.path.is_none() || option.enabled == Some(false) {
161            return Ok(None);
162        }
163
164        let processor = AmbianceProcessor::new(option).await?;
165        let shared = Arc::new(StdMutex::new(processor));
166        *slot = Some(shared.clone());
167        drop(slot);
168
169        *self.ambiance_source_id.lock().unwrap() = Some(source_track_id);
170        self.start_ambiance_idle_loop(shared.clone());
171        info!(session_id = self.id, "ambiance idle mixer started");
172        Ok(Some(shared))
173    }
174
175    fn start_ambiance_idle_loop(&self, processor: Arc<StdMutex<AmbianceProcessor>>) {
176        if self.ambiance_idle_started.swap(true, Ordering::SeqCst) {
177            return;
178        }
179
180        let cancel_token = self.cancel_token.clone();
181        let packet_sender = self.packet_sender.clone();
182        let last_server_packet_ts = self.last_server_packet_ts.clone();
183        let session_id = self.id.clone();
184        let recorder_sender = self.recorder_sender.clone();
185        let recording_active = self.recording_active.clone();
186
187        crate::spawn(async move {
188            let mut ticker = tokio::time::interval(AMBIANCE_IDLE_PTIME);
189            ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
190            loop {
191                tokio::select! {
192                    _ = cancel_token.cancelled() => break,
193                    _ = ticker.tick() => {
194                        let now = crate::media::get_timestamp();
195                        let last = last_server_packet_ts.load(Ordering::Relaxed);
196                        if last != 0 && now.saturating_sub(last) < AMBIANCE_IDLE_GAP_MS {
197                            continue;
198                        }
199
200                        let mut frame = AudioFrame {
201                            track_id: AMBIANCE_IDLE_TRACK_ID.to_string(),
202                            samples: Samples::Empty,
203                            timestamp: now,
204                            sample_rate: INTERNAL_SAMPLERATE,
205                            channels: 1,
206                            ..Default::default()
207                        };
208                        {
209                            let mut ambiance = match processor.lock() {
210                                Ok(guard) => guard,
211                                Err(_) => break,
212                            };
213                            if let Err(e) = ambiance.process_frame(&mut frame) {
214                                warn!(session_id, "ambiance idle mix failed: {}", e);
215                                continue;
216                            }
217                        }
218                        if matches!(frame.samples, Samples::Empty) {
219                            continue;
220                        }
221                        // Mirror the mixed idle ambiance into the recording so the
222                        // stereo WAV's server-side channel reflects what the user
223                        // actually heard, including silent-period background audio.
224                        if recording_active.load(Ordering::SeqCst) {
225                            let mut recorded = frame.clone();
226                            recorded.track_id = SERVER_SIDE_TRACK_ID.to_string();
227                            let _ = recorder_sender.send(recorded);
228                        }
229                        if packet_sender.send(frame).is_err() {
230                            debug!(session_id, "ambiance idle sender closed");
231                            break;
232                        }
233                    }
234                }
235            }
236        });
237    }
238
239    pub fn stop(&self, _reason: Option<String>, _initiator: Option<String>) {
240        self.cancel_token.cancel()
241    }
242
243    pub async fn cleanup(&self) -> Result<()> {
244        self.cancel_token.cancel();
245        {
246            let mut tracks = self.tracks.lock().await;
247            for (id, (track, _)) in tracks.drain() {
248                if let Err(e) = track.stop().await {
249                    warn!(session_id = self.id, track_id = %id, "failed to stop track during cleanup: {}", e);
250                }
251            }
252        }
253        self.suppressed_sources.lock().await.clear();
254
255        if let Some(recorder_handle) = self.recorder_handle.lock().await.take() {
256            if let Ok(Ok(_)) = tokio::time::timeout(Duration::from_secs(30), recorder_handle).await
257            {
258                info!(session_id = self.id, "recorder stopped");
259            } else {
260                warn!(session_id = self.id, "recorder timeout");
261            }
262        }
263        Ok(())
264    }
265    pub async fn track_count(&self) -> usize {
266        self.tracks.lock().await.len()
267    }
268
269    pub async fn update_recorder_option(&self, recorder_config: RecorderOption) {
270        *self.recorder_option.lock().await = Some(recorder_config);
271        self.start_recorder().await.ok();
272    }
273
274    /// Create the session's monitor hub on first use and return it. Idempotent.
275    pub async fn enable_monitor(&self) -> MonitorHub {
276        let mut slot = self.monitor_hub.lock().await;
277        if let Some(hub) = slot.as_ref() {
278            return hub.clone();
279        }
280        let hub = MonitorHub::new();
281        *slot = Some(hub.clone());
282        drop(slot);
283        info!(session_id = self.id, "monitor hub enabled");
284        hub
285    }
286
287    /// The session's monitor hub, if `enable_monitor` was called.
288    pub async fn monitor_hub(&self) -> Option<MonitorHub> {
289        self.monitor_hub.lock().await.clone()
290    }
291
292    /// Whether a track that has not ended is registered under `id`.
293    pub async fn has_live_track(&self, id: &TrackId) -> bool {
294        self.tracks
295            .lock()
296            .await
297            .get(id)
298            .is_some_and(|(track, _)| !track.has_ended())
299    }
300
301    pub async fn remove_track(&self, id: &TrackId, graceful: bool) {
302        let track_entry = { self.tracks.lock().await.remove(id) };
303        if let Some((track, _)) = track_entry {
304            self.suppressed_sources.lock().await.remove(id);
305            let res = if !graceful {
306                track.stop().await
307            } else {
308                track.stop_graceful().await
309            };
310            match res {
311                Ok(_) => {}
312                Err(e) => {
313                    warn!(session_id = self.id, "failed to stop track: {}", e);
314                }
315            }
316        }
317    }
318    pub async fn update_remote_description(
319        &self,
320        track_id: &TrackId,
321        answer: &String,
322    ) -> Result<()> {
323        let track_entry = { self.tracks.lock().await.remove(track_id) };
324        if let Some((mut track, dtmf)) = track_entry {
325            let res = track.update_remote_description(answer).await;
326            self.tracks
327                .lock()
328                .await
329                .insert(track_id.clone(), (track, dtmf));
330            res?;
331        }
332        Ok(())
333    }
334
335    pub async fn update_remote_description_force(
336        &self,
337        track_id: &TrackId,
338        answer: &String,
339    ) -> Result<()> {
340        let track_entry = { self.tracks.lock().await.remove(track_id) };
341        if let Some((mut track, dtmf)) = track_entry {
342            let res = track.update_remote_description_force(answer).await;
343            self.tracks
344                .lock()
345                .await
346                .insert(track_id.clone(), (track, dtmf));
347            res?;
348        }
349        Ok(())
350    }
351
352    /// Apply a provisional remote description (SIP 183 early media). See
353    /// `Track::update_remote_description_provisional`.
354    pub async fn update_remote_description_provisional(
355        &self,
356        track_id: &TrackId,
357        answer: &String,
358    ) -> Result<()> {
359        let track_entry = { self.tracks.lock().await.remove(track_id) };
360        if let Some((mut track, dtmf)) = track_entry {
361            let res = track.update_remote_description_provisional(answer).await;
362            self.tracks
363                .lock()
364                .await
365                .insert(track_id.clone(), (track, dtmf));
366            res?;
367        }
368        Ok(())
369    }
370
371    pub async fn handshake(
372        &self,
373        track_id: &TrackId,
374        offer: String,
375        timeout: Option<Duration>,
376    ) -> Result<String> {
377        let track_entry = { self.tracks.lock().await.remove(track_id) };
378        if let Some((mut track, dtmf)) = track_entry {
379            let res = track.handshake(offer, timeout).await;
380            self.tracks
381                .lock()
382                .await
383                .insert(track_id.clone(), (track, dtmf));
384            res
385        } else {
386            anyhow::bail!("track not found: {}", track_id)
387        }
388    }
389
390    pub async fn update_track(&self, mut track: Box<dyn Track>, play_id: Option<String>) {
391        self.remove_track(track.id(), false).await;
392        self.attach_recorder_tap(&mut track).await;
393        match track
394            .start(self.event_sender.clone(), self.packet_sender.clone())
395            .await
396        {
397            Ok(_) => {
398                info!(session_id = self.id, track_id = track.id(), "track started");
399                let track_id = track.id().clone();
400                if track_id.as_str() == self.id.as_str() {
401                    let pending = std::mem::take(&mut *self.pending_ice_candidates.lock().await);
402                    for (candidate, sdp_mid, sdp_mline_index) in pending {
403                        if let Err(e) =
404                            track.add_ice_candidate(&candidate, sdp_mid.as_deref(), sdp_mline_index)
405                        {
406                            warn!(
407                                session_id = self.id,
408                                track_id = track.id(),
409                                "failed to apply buffered ICE candidate: {}",
410                                e
411                            );
412                        }
413                    }
414                }
415                self.tracks
416                    .lock()
417                    .await
418                    .insert(track_id.clone(), (track, DtmfDetector::new()));
419                self.event_sender
420                    .send(SessionEvent::TrackStart {
421                        track_id,
422                        timestamp: crate::media::get_timestamp(),
423                        play_id,
424                    })
425                    .ok();
426            }
427            Err(e) => {
428                warn!(
429                    session_id = self.id,
430                    track_id = track.id(),
431                    play_id = play_id.as_deref(),
432                    "Failed to start track: {}",
433                    e
434                );
435            }
436        }
437    }
438
439    pub async fn mute_track(&self, id: Option<TrackId>) {
440        if let Some(id) = id {
441            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
442                MuteProcessor::mute_track(track.as_mut());
443            }
444        } else {
445            for (track, _) in self.tracks.lock().await.values_mut() {
446                MuteProcessor::mute_track(track.as_mut());
447            }
448        }
449    }
450
451    pub async fn unmute_track(&self, id: Option<TrackId>) {
452        if let Some(id) = id {
453            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
454                MuteProcessor::unmute_track(track.as_mut());
455            }
456        } else {
457            for (track, _) in self.tracks.lock().await.values_mut() {
458                MuteProcessor::unmute_track(track.as_mut());
459            }
460        }
461    }
462
463    /// Apply a new remote offer to the session's own (WebRTC) track without
464    /// recreating it, e.g. for an ICE restart, and return the new answer.
465    pub async fn renegotiate(&self, offer: String) -> Result<String> {
466        // hold the lock across the handshake (instead of taking the track out
467        // of the map like `handshake` does), so a trickled candidate for the
468        // new ICE generation waits for it rather than landing in
469        // `pending_ice_candidates`, which is only replayed on `update_track`
470        let mut tracks = self.tracks.lock().await;
471        let Some((track, _)) = tracks.get_mut(self.id.as_str()) else {
472            anyhow::bail!("track not found: {}", self.id)
473        };
474        let answer = track.handshake(offer, None).await?;
475        if answer.is_empty() {
476            anyhow::bail!("track {} does not support renegotiation", self.id)
477        }
478        Ok(answer)
479    }
480
481    /// See `Track::on_answered`.
482    pub async fn on_answered(&self, track_id: &TrackId, rtp_timeout: Option<Duration>) {
483        if let Some((track, _)) = self.tracks.lock().await.get(track_id) {
484            track.on_answered(rtp_timeout);
485        }
486    }
487
488    /// Trickle ICE: feed a remote candidate into the ICE-backed (WebRTC)
489    /// track, if it's up yet, or buffer it for `update_track` to replay
490    /// otherwise.
491    pub async fn add_ice_candidate(
492        &self,
493        candidate: &str,
494        sdp_mid: Option<&str>,
495        sdp_mline_index: Option<u32>,
496    ) -> Result<()> {
497        let tracks = self.tracks.lock().await;
498        if let Some((track, _)) = tracks.get(self.id.as_str()) {
499            track.add_ice_candidate(candidate, sdp_mid, sdp_mline_index)?;
500            return Ok(());
501        }
502        drop(tracks);
503        self.pending_ice_candidates.lock().await.push((
504            candidate.to_string(),
505            sdp_mid.map(|s| s.to_string()),
506            sdp_mline_index,
507        ));
508        Ok(())
509    }
510
511    pub async fn pause_playback(&self, id: TrackId) -> Result<()> {
512        self.set_playback_paused(id, true).await
513    }
514
515    pub async fn resume_playback(&self, id: TrackId) -> Result<()> {
516        self.set_playback_paused(id, false).await
517    }
518
519    async fn set_playback_paused(&self, id: TrackId, paused: bool) -> Result<()> {
520        if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
521            if track.set_paused(paused) {
522                Ok(())
523            } else {
524                warn!(
525                    session_id = self.id,
526                    track_id = %id,
527                    paused,
528                    "pause state requested for track that does not support pausing"
529                );
530                Err(anyhow::anyhow!("track does not support pausing: {}", id))
531            }
532        } else {
533            warn!(
534                session_id = self.id,
535                track_id = %id,
536                paused,
537                "pause state requested for unknown track"
538            );
539            Err(anyhow::anyhow!("track not found: {}", id))
540        }
541    }
542
543    pub async fn hold_track(&self, id: Option<TrackId>) {
544        if let Some(id) = id {
545            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
546                HoldTrack::hold_track(track.as_mut());
547            }
548        } else {
549            for (track, _) in self.tracks.lock().await.values_mut() {
550                HoldTrack::hold_track(track.as_mut());
551            }
552        }
553    }
554
555    pub async fn resume_track(&self, id: Option<TrackId>) {
556        if let Some(id) = id {
557            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
558                HoldTrack::resume_track(track.as_mut());
559            }
560        } else {
561            for (track, _) in self.tracks.lock().await.values_mut() {
562                HoldTrack::resume_track(track.as_mut());
563            }
564        }
565    }
566
567    pub async fn suppress_forwarding(&self, track_id: &TrackId) {
568        self.suppressed_sources
569            .lock()
570            .await
571            .insert(track_id.clone());
572    }
573
574    pub async fn resume_forwarding(&self, track_id: &TrackId) {
575        self.suppressed_sources.lock().await.remove(track_id);
576    }
577
578    pub async fn remove_processor<T: 'static>(&self, track_id: &TrackId) -> Result<()> {
579        if let Some((track, _)) = self.tracks.lock().await.get_mut(track_id) {
580            track.as_mut().processor_chain().remove_processor::<T>();
581            Ok(())
582        } else {
583            Err(anyhow::anyhow!("Track {} not found", track_id))
584        }
585    }
586
587    pub async fn append_processor(
588        &self,
589        track_id: &TrackId,
590        processor: Box<dyn crate::media::processor::Processor>,
591    ) -> Result<()> {
592        if let Some((track, _)) = self.tracks.lock().await.get_mut(track_id) {
593            track.as_mut().processor_chain().append_processor(processor);
594            Ok(())
595        } else {
596            Err(anyhow::anyhow!("Track {} not found", track_id))
597        }
598    }
599}
600
601#[derive(Clone)]
602pub struct RecorderProcessor {
603    sender: mpsc::UnboundedSender<AudioFrame>,
604    /// Only frames tagged with this track id are mirrored. A track may relay
605    /// another leg's audio (e.g. the media-pass track forwards the caller's
606    /// audio to the websocket); that relayed copy is already recorded at its
607    /// origin and must not be written to the recording a second time.
608    owner: TrackId,
609}
610
611impl RecorderProcessor {
612    pub fn new(sender: mpsc::UnboundedSender<AudioFrame>, owner: TrackId) -> Self {
613        Self { sender, owner }
614    }
615}
616
617impl Processor for RecorderProcessor {
618    fn process_frame(&mut self, frame: &mut AudioFrame) -> Result<()> {
619        if frame.track_id == self.owner {
620            let _ = self.sender.send(frame.clone());
621        }
622        Ok(())
623    }
624}
625
626impl MediaStream {
627    pub async fn start_recorder(&self) -> Result<()> {
628        let recorder_option = self.recorder_option.lock().await.clone();
629        if let Some(recorder_option) = recorder_option {
630            if recorder_option.recorder_file.is_empty() {
631                warn!(
632                    session_id = self.id,
633                    "recorder file is empty, skipping recorder start"
634                );
635                return Ok(());
636            }
637            let recorder_receiver = match self.recorder_receiver.lock().await.take() {
638                Some(receiver) => receiver,
639                None => {
640                    return Ok(());
641                }
642            };
643            let cancel_token = self.cancel_token.child_token();
644            let session_id_clone = self.id.clone();
645
646            info!(
647                session_id = session_id_clone,
648                sample_rate = recorder_option.samplerate,
649                native_samplerate = recorder_option.native_samplerate.unwrap_or(false),
650                ptime = recorder_option.ptime,
651                "start recorder",
652            );
653
654            let native = recorder_option.native_samplerate.unwrap_or(false);
655            let recorder_handle = crate::spawn(async move {
656                let recorder_file = recorder_option.recorder_file.clone();
657                let recorder =
658                    Recorder::new(cancel_token, session_id_clone.clone(), recorder_option);
659                match recorder
660                    .process_recording(Path::new(&recorder_file), recorder_receiver)
661                    .await
662                {
663                    Ok(_) => {}
664                    Err(e) => {
665                        warn!(
666                            session_id = session_id_clone,
667                            "Failed to process recorder: {}", e
668                        );
669                    }
670                }
671            });
672            *self.recorder_handle.lock().await = Some(recorder_handle);
673            self.recording_active.store(true, Ordering::SeqCst);
674
675            // Inject the recorder tap into tracks that were added before the
676            // recorder started. `set_raw_tap` replaces any previous tap, so
677            // this stays idempotent.
678            for (track, _) in self.tracks.lock().await.values_mut() {
679                if native {
680                    track.set_raw_tap(Some(self.recorder_sender.clone()));
681                } else {
682                    let owner = track.id().clone();
683                    // Go through the chain directly: the media-pass track
684                    // deliberately ignores `Track::insert_processor`, but the
685                    // audio it plays into the call must still be recorded.
686                    let chain = track.processor_chain();
687                    if !chain.has_processor::<RecorderProcessor>() {
688                        chain.append_processor(Box::new(RecorderProcessor::new(
689                            self.recorder_sender.clone(),
690                            owner,
691                        )));
692                    }
693                }
694            }
695        }
696        Ok(())
697    }
698
699    /// Attach the recorder tap to a track according to the recorder mode:
700    /// native-samplerate mode mirrors pre-resample frames via the chain's
701    /// raw tap, otherwise a post-pipeline RecorderProcessor is appended to
702    /// the track's processor chain. No-op when no recorder is configured.
703    async fn attach_recorder_tap(&self, track: &mut Box<dyn Track>) {
704        let Some(option) = self.recorder_option.lock().await.clone() else {
705            return;
706        };
707        if option.native_samplerate.unwrap_or(false) {
708            track.set_raw_tap(Some(self.recorder_sender.clone()));
709        } else {
710            let owner = track.id().clone();
711            // Reach into the processor chain directly rather than calling
712            // `Track::append_processor`: the media-pass track rejects that
713            // (it ignores audio processors) yet still needs to feed the
714            // recorder with the audio it plays into the call.
715            track
716                .processor_chain()
717                .append_processor(Box::new(RecorderProcessor::new(
718                    self.recorder_sender.clone(),
719                    owner,
720                )));
721        }
722    }
723
724    pub async fn set_track_refer(&self, track_id: &TrackId, refer: Option<bool>) {
725        if let Some((_, dtmf)) = self.tracks.lock().await.get_mut(track_id) {
726            dtmf.refer = refer;
727        }
728    }
729
730    pub async fn set_track_dtmf_forward(&self, track_id: &TrackId, forward: bool) {
731        if let Some((_, dtmf)) = self.tracks.lock().await.get_mut(track_id) {
732            dtmf.suppress_dtmf_forward = !forward;
733        }
734    }
735
736    async fn handle_forward_track(&self, mut packet_receiver: TrackPacketReceiver) {
737        let event_sender = self.event_sender.clone();
738        while let Some(packet) = packet_receiver.recv().await {
739            if self
740                .ambiance_source_id
741                .lock()
742                .ok()
743                .and_then(|id| id.clone())
744                .as_ref()
745                == Some(&packet.track_id)
746            {
747                self.last_server_packet_ts
748                    .store(crate::media::get_timestamp(), Ordering::Relaxed);
749            }
750
751            let suppressed = {
752                self.suppressed_sources
753                    .lock()
754                    .await
755                    .contains(&packet.track_id)
756            };
757
758            let is_dtmf = matches!(&packet.samples,
759                Samples::RTP { payload_type, .. } if *payload_type >= 96 && *payload_type <= 127);
760
761            let mut tracks = self.tracks.lock().await;
762
763            // Check once whether the source track suppresses DTMF forwarding.
764            let source_suppresses_dtmf = is_dtmf
765                && tracks
766                    .get(&packet.track_id)
767                    .map(|(_, d)| d.suppress_dtmf_forward)
768                    .unwrap_or(false);
769
770            for (track, dtmf_detector) in tracks.values_mut() {
771                if track.id() == &packet.track_id {
772                    if let Samples::RTP {
773                        payload_type,
774                        payload,
775                        ..
776                    } = &packet.samples
777                    {
778                        if let Some(digit) = dtmf_detector.detect_rtp(*payload_type, payload) {
779                            debug!(track_id = track.id(), digit, "DTMF detected");
780                            event_sender
781                                .send(SessionEvent::Dtmf {
782                                    track_id: packet.track_id.to_string(),
783                                    timestamp: packet.timestamp,
784                                    digit,
785                                    refer: dtmf_detector.refer,
786                                })
787                                .ok();
788                        }
789                    }
790                    continue;
791                }
792                if suppressed {
793                    continue;
794                }
795                // Skip DTMF forwarding if source or destination has it suppressed.
796                if source_suppresses_dtmf || (is_dtmf && dtmf_detector.suppress_dtmf_forward) {
797                    continue;
798                }
799                if packet.track_id == QUEUE_HOLD_TRACK_ID && track.id() == CALLEE_TRACK_ID {
800                    continue;
801                }
802                if let Err(e) = track.send_packet(&packet).await {
803                    warn!(
804                        id = track.id(),
805                        "media_stream: Failed to send packet to track: {}", e
806                    );
807                }
808            }
809        }
810    }
811}
812
813pub struct MuteProcessor;
814
815impl MuteProcessor {
816    pub fn mute_track(track: &mut dyn Track) {
817        let chain = track.processor_chain();
818        if !chain.has_processor::<MuteProcessor>() {
819            chain.insert_processor(Box::new(MuteProcessor));
820        }
821    }
822
823    pub fn unmute_track(track: &mut dyn Track) {
824        let chain = track.processor_chain();
825        chain.remove_processor::<MuteProcessor>();
826    }
827}
828
829impl Processor for MuteProcessor {
830    fn process_frame(&mut self, frame: &mut AudioFrame) -> Result<()> {
831        match &mut frame.samples {
832            Samples::PCM { samples } => {
833                samples.fill(0);
834            }
835            // discard DTMF frames
836            Samples::RTP { payload_type, .. } if *payload_type >= 96 && *payload_type <= 127 => {
837                frame.samples = Samples::Empty;
838            }
839            _ => {}
840        }
841        Ok(())
842    }
843}
844
845pub struct HoldTrack;
846
847impl HoldTrack {
848    pub fn hold_track(track: &mut dyn Track) {
849        let chain = track.processor_chain();
850        // Remove existing processor if present
851        chain.remove_processor::<HoldProcessor>();
852        // Add a new processor with hold state set to true
853        let processor = HoldProcessor::new();
854        processor.set_hold(true);
855        chain.insert_processor(Box::new(processor));
856    }
857
858    pub fn resume_track(track: &mut dyn Track) {
859        let chain = track.processor_chain();
860        // Simply remove the hold processor to resume normal operation
861        chain.remove_processor::<HoldProcessor>();
862    }
863}
864
865#[cfg(test)]
866mod recorder_owner_tests {
867    use super::*;
868    use crate::media::Samples;
869
870    fn pcm_frame(track_id: &str, len: usize) -> AudioFrame {
871        AudioFrame {
872            track_id: track_id.to_string(),
873            samples: Samples::PCM {
874                samples: vec![100i16; len],
875            },
876            sample_rate: 16000,
877            channels: 1,
878            ..Default::default()
879        }
880    }
881
882    /// Regression for media-pass recordings in non-native mode: the track's own
883    /// processor chain also processes audio it relays for another leg (the
884    /// caller's audio forwarded to the websocket). `RecorderProcessor` must
885    /// mirror only the track's own frames so the relayed copy is not written to
886    /// the recording twice.
887    #[test]
888    fn recorder_processor_only_mirrors_owned_frames() {
889        let (tx, mut rx) = mpsc::unbounded_channel();
890        let mut processor = RecorderProcessor::new(tx, "server-side-track".to_string());
891
892        let mut relayed = pcm_frame("caller-leg", 160);
893        processor.process_frame(&mut relayed).unwrap();
894        assert!(
895            rx.try_recv().is_err(),
896            "relayed caller audio must not be recorded"
897        );
898
899        let mut own = pcm_frame("server-side-track", 160);
900        processor.process_frame(&mut own).unwrap();
901        let mirrored = rx
902            .try_recv()
903            .expect("the track's own audio must be recorded");
904        assert_eq!(mirrored.track_id, "server-side-track");
905    }
906
907    /// A bare `RecorderProcessor` (e.g. attached to the caller leg) records its
908    /// own frames and ignores anything else.
909    #[test]
910    fn recorder_processor_records_caller_leg_only() {
911        let (tx, mut rx) = mpsc::unbounded_channel();
912        let mut processor = RecorderProcessor::new(tx, "caller-leg".to_string());
913
914        let mut own = pcm_frame("caller-leg", 160);
915        processor.process_frame(&mut own).unwrap();
916        assert!(rx.try_recv().is_ok());
917
918        let mut foreign = pcm_frame("server-side-track", 160);
919        processor.process_frame(&mut foreign).unwrap();
920        assert!(rx.try_recv().is_err());
921    }
922}