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    pub async fn remove_track(&self, id: &TrackId, graceful: bool) {
293        let track_entry = { self.tracks.lock().await.remove(id) };
294        if let Some((track, _)) = track_entry {
295            self.suppressed_sources.lock().await.remove(id);
296            let res = if !graceful {
297                track.stop().await
298            } else {
299                track.stop_graceful().await
300            };
301            match res {
302                Ok(_) => {}
303                Err(e) => {
304                    warn!(session_id = self.id, "failed to stop track: {}", e);
305                }
306            }
307        }
308    }
309    pub async fn update_remote_description(
310        &self,
311        track_id: &TrackId,
312        answer: &String,
313    ) -> Result<()> {
314        let track_entry = { self.tracks.lock().await.remove(track_id) };
315        if let Some((mut track, dtmf)) = track_entry {
316            let res = track.update_remote_description(answer).await;
317            self.tracks
318                .lock()
319                .await
320                .insert(track_id.clone(), (track, dtmf));
321            res?;
322        }
323        Ok(())
324    }
325
326    pub async fn update_remote_description_force(
327        &self,
328        track_id: &TrackId,
329        answer: &String,
330    ) -> Result<()> {
331        let track_entry = { self.tracks.lock().await.remove(track_id) };
332        if let Some((mut track, dtmf)) = track_entry {
333            let res = track.update_remote_description_force(answer).await;
334            self.tracks
335                .lock()
336                .await
337                .insert(track_id.clone(), (track, dtmf));
338            res?;
339        }
340        Ok(())
341    }
342
343    /// Apply a provisional remote description (SIP 183 early media). See
344    /// `Track::update_remote_description_provisional`.
345    pub async fn update_remote_description_provisional(
346        &self,
347        track_id: &TrackId,
348        answer: &String,
349    ) -> Result<()> {
350        let track_entry = { self.tracks.lock().await.remove(track_id) };
351        if let Some((mut track, dtmf)) = track_entry {
352            let res = track.update_remote_description_provisional(answer).await;
353            self.tracks
354                .lock()
355                .await
356                .insert(track_id.clone(), (track, dtmf));
357            res?;
358        }
359        Ok(())
360    }
361
362    pub async fn handshake(
363        &self,
364        track_id: &TrackId,
365        offer: String,
366        timeout: Option<Duration>,
367    ) -> Result<String> {
368        let track_entry = { self.tracks.lock().await.remove(track_id) };
369        if let Some((mut track, dtmf)) = track_entry {
370            let res = track.handshake(offer, timeout).await;
371            self.tracks
372                .lock()
373                .await
374                .insert(track_id.clone(), (track, dtmf));
375            res
376        } else {
377            anyhow::bail!("track not found: {}", track_id)
378        }
379    }
380
381    pub async fn update_track(&self, mut track: Box<dyn Track>, play_id: Option<String>) {
382        self.remove_track(track.id(), false).await;
383        self.attach_recorder_tap(&mut track).await;
384        match track
385            .start(self.event_sender.clone(), self.packet_sender.clone())
386            .await
387        {
388            Ok(_) => {
389                info!(session_id = self.id, track_id = track.id(), "track started");
390                let track_id = track.id().clone();
391                if track_id.as_str() == self.id.as_str() {
392                    let pending = std::mem::take(&mut *self.pending_ice_candidates.lock().await);
393                    for (candidate, sdp_mid, sdp_mline_index) in pending {
394                        if let Err(e) =
395                            track.add_ice_candidate(&candidate, sdp_mid.as_deref(), sdp_mline_index)
396                        {
397                            warn!(
398                                session_id = self.id,
399                                track_id = track.id(),
400                                "failed to apply buffered ICE candidate: {}",
401                                e
402                            );
403                        }
404                    }
405                }
406                self.tracks
407                    .lock()
408                    .await
409                    .insert(track_id.clone(), (track, DtmfDetector::new()));
410                self.event_sender
411                    .send(SessionEvent::TrackStart {
412                        track_id,
413                        timestamp: crate::media::get_timestamp(),
414                        play_id,
415                    })
416                    .ok();
417            }
418            Err(e) => {
419                warn!(
420                    session_id = self.id,
421                    track_id = track.id(),
422                    play_id = play_id.as_deref(),
423                    "Failed to start track: {}",
424                    e
425                );
426            }
427        }
428    }
429
430    pub async fn mute_track(&self, id: Option<TrackId>) {
431        if let Some(id) = id {
432            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
433                MuteProcessor::mute_track(track.as_mut());
434            }
435        } else {
436            for (track, _) in self.tracks.lock().await.values_mut() {
437                MuteProcessor::mute_track(track.as_mut());
438            }
439        }
440    }
441
442    pub async fn unmute_track(&self, id: Option<TrackId>) {
443        if let Some(id) = id {
444            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
445                MuteProcessor::unmute_track(track.as_mut());
446            }
447        } else {
448            for (track, _) in self.tracks.lock().await.values_mut() {
449                MuteProcessor::unmute_track(track.as_mut());
450            }
451        }
452    }
453
454    /// Apply a new remote offer to the session's own (WebRTC) track without
455    /// recreating it, e.g. for an ICE restart, and return the new answer.
456    pub async fn renegotiate(&self, offer: String) -> Result<String> {
457        // hold the lock across the handshake (instead of taking the track out
458        // of the map like `handshake` does), so a trickled candidate for the
459        // new ICE generation waits for it rather than landing in
460        // `pending_ice_candidates`, which is only replayed on `update_track`
461        let mut tracks = self.tracks.lock().await;
462        let Some((track, _)) = tracks.get_mut(self.id.as_str()) else {
463            anyhow::bail!("track not found: {}", self.id)
464        };
465        let answer = track.handshake(offer, None).await?;
466        if answer.is_empty() {
467            anyhow::bail!("track {} does not support renegotiation", self.id)
468        }
469        Ok(answer)
470    }
471
472    /// See `Track::on_answered`.
473    pub async fn on_answered(&self, track_id: &TrackId, rtp_timeout: Option<Duration>) {
474        if let Some((track, _)) = self.tracks.lock().await.get(track_id) {
475            track.on_answered(rtp_timeout);
476        }
477    }
478
479    /// Trickle ICE: feed a remote candidate into the ICE-backed (WebRTC)
480    /// track, if it's up yet, or buffer it for `update_track` to replay
481    /// otherwise.
482    pub async fn add_ice_candidate(
483        &self,
484        candidate: &str,
485        sdp_mid: Option<&str>,
486        sdp_mline_index: Option<u32>,
487    ) -> Result<()> {
488        let tracks = self.tracks.lock().await;
489        if let Some((track, _)) = tracks.get(self.id.as_str()) {
490            track.add_ice_candidate(candidate, sdp_mid, sdp_mline_index)?;
491            return Ok(());
492        }
493        drop(tracks);
494        self.pending_ice_candidates.lock().await.push((
495            candidate.to_string(),
496            sdp_mid.map(|s| s.to_string()),
497            sdp_mline_index,
498        ));
499        Ok(())
500    }
501
502    pub async fn pause_playback(&self, id: TrackId) -> Result<()> {
503        self.set_playback_paused(id, true).await
504    }
505
506    pub async fn resume_playback(&self, id: TrackId) -> Result<()> {
507        self.set_playback_paused(id, false).await
508    }
509
510    async fn set_playback_paused(&self, id: TrackId, paused: bool) -> Result<()> {
511        if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
512            if track.set_paused(paused) {
513                Ok(())
514            } else {
515                warn!(
516                    session_id = self.id,
517                    track_id = %id,
518                    paused,
519                    "pause state requested for track that does not support pausing"
520                );
521                Err(anyhow::anyhow!("track does not support pausing: {}", id))
522            }
523        } else {
524            warn!(
525                session_id = self.id,
526                track_id = %id,
527                paused,
528                "pause state requested for unknown track"
529            );
530            Err(anyhow::anyhow!("track not found: {}", id))
531        }
532    }
533
534    pub async fn hold_track(&self, id: Option<TrackId>) {
535        if let Some(id) = id {
536            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
537                HoldTrack::hold_track(track.as_mut());
538            }
539        } else {
540            for (track, _) in self.tracks.lock().await.values_mut() {
541                HoldTrack::hold_track(track.as_mut());
542            }
543        }
544    }
545
546    pub async fn resume_track(&self, id: Option<TrackId>) {
547        if let Some(id) = id {
548            if let Some((track, _)) = self.tracks.lock().await.get_mut(&id) {
549                HoldTrack::resume_track(track.as_mut());
550            }
551        } else {
552            for (track, _) in self.tracks.lock().await.values_mut() {
553                HoldTrack::resume_track(track.as_mut());
554            }
555        }
556    }
557
558    pub async fn suppress_forwarding(&self, track_id: &TrackId) {
559        self.suppressed_sources
560            .lock()
561            .await
562            .insert(track_id.clone());
563    }
564
565    pub async fn resume_forwarding(&self, track_id: &TrackId) {
566        self.suppressed_sources.lock().await.remove(track_id);
567    }
568
569    pub async fn remove_processor<T: 'static>(&self, track_id: &TrackId) -> Result<()> {
570        if let Some((track, _)) = self.tracks.lock().await.get_mut(track_id) {
571            track.as_mut().processor_chain().remove_processor::<T>();
572            Ok(())
573        } else {
574            Err(anyhow::anyhow!("Track {} not found", track_id))
575        }
576    }
577
578    pub async fn append_processor(
579        &self,
580        track_id: &TrackId,
581        processor: Box<dyn crate::media::processor::Processor>,
582    ) -> Result<()> {
583        if let Some((track, _)) = self.tracks.lock().await.get_mut(track_id) {
584            track.as_mut().processor_chain().append_processor(processor);
585            Ok(())
586        } else {
587            Err(anyhow::anyhow!("Track {} not found", track_id))
588        }
589    }
590}
591
592#[derive(Clone)]
593pub struct RecorderProcessor {
594    sender: mpsc::UnboundedSender<AudioFrame>,
595    /// Only frames tagged with this track id are mirrored. A track may relay
596    /// another leg's audio (e.g. the media-pass track forwards the caller's
597    /// audio to the websocket); that relayed copy is already recorded at its
598    /// origin and must not be written to the recording a second time.
599    owner: TrackId,
600}
601
602impl RecorderProcessor {
603    pub fn new(sender: mpsc::UnboundedSender<AudioFrame>, owner: TrackId) -> Self {
604        Self { sender, owner }
605    }
606}
607
608impl Processor for RecorderProcessor {
609    fn process_frame(&mut self, frame: &mut AudioFrame) -> Result<()> {
610        if frame.track_id == self.owner {
611            let _ = self.sender.send(frame.clone());
612        }
613        Ok(())
614    }
615}
616
617impl MediaStream {
618    pub async fn start_recorder(&self) -> Result<()> {
619        let recorder_option = self.recorder_option.lock().await.clone();
620        if let Some(recorder_option) = recorder_option {
621            if recorder_option.recorder_file.is_empty() {
622                warn!(
623                    session_id = self.id,
624                    "recorder file is empty, skipping recorder start"
625                );
626                return Ok(());
627            }
628            let recorder_receiver = match self.recorder_receiver.lock().await.take() {
629                Some(receiver) => receiver,
630                None => {
631                    return Ok(());
632                }
633            };
634            let cancel_token = self.cancel_token.child_token();
635            let session_id_clone = self.id.clone();
636
637            info!(
638                session_id = session_id_clone,
639                sample_rate = recorder_option.samplerate,
640                native_samplerate = recorder_option.native_samplerate.unwrap_or(false),
641                ptime = recorder_option.ptime,
642                "start recorder",
643            );
644
645            let native = recorder_option.native_samplerate.unwrap_or(false);
646            let recorder_handle = crate::spawn(async move {
647                let recorder_file = recorder_option.recorder_file.clone();
648                let recorder =
649                    Recorder::new(cancel_token, session_id_clone.clone(), recorder_option);
650                match recorder
651                    .process_recording(Path::new(&recorder_file), recorder_receiver)
652                    .await
653                {
654                    Ok(_) => {}
655                    Err(e) => {
656                        warn!(
657                            session_id = session_id_clone,
658                            "Failed to process recorder: {}", e
659                        );
660                    }
661                }
662            });
663            *self.recorder_handle.lock().await = Some(recorder_handle);
664            self.recording_active.store(true, Ordering::SeqCst);
665
666            // Inject the recorder tap into tracks that were added before the
667            // recorder started. `set_raw_tap` replaces any previous tap, so
668            // this stays idempotent.
669            for (track, _) in self.tracks.lock().await.values_mut() {
670                if native {
671                    track.set_raw_tap(Some(self.recorder_sender.clone()));
672                } else {
673                    let owner = track.id().clone();
674                    // Go through the chain directly: the media-pass track
675                    // deliberately ignores `Track::insert_processor`, but the
676                    // audio it plays into the call must still be recorded.
677                    let chain = track.processor_chain();
678                    if !chain.has_processor::<RecorderProcessor>() {
679                        chain.append_processor(Box::new(RecorderProcessor::new(
680                            self.recorder_sender.clone(),
681                            owner,
682                        )));
683                    }
684                }
685            }
686        }
687        Ok(())
688    }
689
690    /// Attach the recorder tap to a track according to the recorder mode:
691    /// native-samplerate mode mirrors pre-resample frames via the chain's
692    /// raw tap, otherwise a post-pipeline RecorderProcessor is appended to
693    /// the track's processor chain. No-op when no recorder is configured.
694    async fn attach_recorder_tap(&self, track: &mut Box<dyn Track>) {
695        let Some(option) = self.recorder_option.lock().await.clone() else {
696            return;
697        };
698        if option.native_samplerate.unwrap_or(false) {
699            track.set_raw_tap(Some(self.recorder_sender.clone()));
700        } else {
701            let owner = track.id().clone();
702            // Reach into the processor chain directly rather than calling
703            // `Track::append_processor`: the media-pass track rejects that
704            // (it ignores audio processors) yet still needs to feed the
705            // recorder with the audio it plays into the call.
706            track
707                .processor_chain()
708                .append_processor(Box::new(RecorderProcessor::new(
709                    self.recorder_sender.clone(),
710                    owner,
711                )));
712        }
713    }
714
715    pub async fn set_track_refer(&self, track_id: &TrackId, refer: Option<bool>) {
716        if let Some((_, dtmf)) = self.tracks.lock().await.get_mut(track_id) {
717            dtmf.refer = refer;
718        }
719    }
720
721    pub async fn set_track_dtmf_forward(&self, track_id: &TrackId, forward: bool) {
722        if let Some((_, dtmf)) = self.tracks.lock().await.get_mut(track_id) {
723            dtmf.suppress_dtmf_forward = !forward;
724        }
725    }
726
727    async fn handle_forward_track(&self, mut packet_receiver: TrackPacketReceiver) {
728        let event_sender = self.event_sender.clone();
729        while let Some(packet) = packet_receiver.recv().await {
730            if self
731                .ambiance_source_id
732                .lock()
733                .ok()
734                .and_then(|id| id.clone())
735                .as_ref()
736                == Some(&packet.track_id)
737            {
738                self.last_server_packet_ts
739                    .store(crate::media::get_timestamp(), Ordering::Relaxed);
740            }
741
742            let suppressed = {
743                self.suppressed_sources
744                    .lock()
745                    .await
746                    .contains(&packet.track_id)
747            };
748
749            let is_dtmf = matches!(&packet.samples,
750                Samples::RTP { payload_type, .. } if *payload_type >= 96 && *payload_type <= 127);
751
752            let mut tracks = self.tracks.lock().await;
753
754            // Check once whether the source track suppresses DTMF forwarding.
755            let source_suppresses_dtmf = is_dtmf
756                && tracks
757                    .get(&packet.track_id)
758                    .map(|(_, d)| d.suppress_dtmf_forward)
759                    .unwrap_or(false);
760
761            for (track, dtmf_detector) in tracks.values_mut() {
762                if track.id() == &packet.track_id {
763                    if let Samples::RTP {
764                        payload_type,
765                        payload,
766                        ..
767                    } = &packet.samples
768                    {
769                        if let Some(digit) = dtmf_detector.detect_rtp(*payload_type, payload) {
770                            debug!(track_id = track.id(), digit, "DTMF detected");
771                            event_sender
772                                .send(SessionEvent::Dtmf {
773                                    track_id: packet.track_id.to_string(),
774                                    timestamp: packet.timestamp,
775                                    digit,
776                                    refer: dtmf_detector.refer,
777                                })
778                                .ok();
779                        }
780                    }
781                    continue;
782                }
783                if suppressed {
784                    continue;
785                }
786                // Skip DTMF forwarding if source or destination has it suppressed.
787                if source_suppresses_dtmf || (is_dtmf && dtmf_detector.suppress_dtmf_forward) {
788                    continue;
789                }
790                if packet.track_id == QUEUE_HOLD_TRACK_ID && track.id() == CALLEE_TRACK_ID {
791                    continue;
792                }
793                if let Err(e) = track.send_packet(&packet).await {
794                    warn!(
795                        id = track.id(),
796                        "media_stream: Failed to send packet to track: {}", e
797                    );
798                }
799            }
800        }
801    }
802}
803
804pub struct MuteProcessor;
805
806impl MuteProcessor {
807    pub fn mute_track(track: &mut dyn Track) {
808        let chain = track.processor_chain();
809        if !chain.has_processor::<MuteProcessor>() {
810            chain.insert_processor(Box::new(MuteProcessor));
811        }
812    }
813
814    pub fn unmute_track(track: &mut dyn Track) {
815        let chain = track.processor_chain();
816        chain.remove_processor::<MuteProcessor>();
817    }
818}
819
820impl Processor for MuteProcessor {
821    fn process_frame(&mut self, frame: &mut AudioFrame) -> Result<()> {
822        match &mut frame.samples {
823            Samples::PCM { samples } => {
824                samples.fill(0);
825            }
826            // discard DTMF frames
827            Samples::RTP { payload_type, .. } if *payload_type >= 96 && *payload_type <= 127 => {
828                frame.samples = Samples::Empty;
829            }
830            _ => {}
831        }
832        Ok(())
833    }
834}
835
836pub struct HoldTrack;
837
838impl HoldTrack {
839    pub fn hold_track(track: &mut dyn Track) {
840        let chain = track.processor_chain();
841        // Remove existing processor if present
842        chain.remove_processor::<HoldProcessor>();
843        // Add a new processor with hold state set to true
844        let processor = HoldProcessor::new();
845        processor.set_hold(true);
846        chain.insert_processor(Box::new(processor));
847    }
848
849    pub fn resume_track(track: &mut dyn Track) {
850        let chain = track.processor_chain();
851        // Simply remove the hold processor to resume normal operation
852        chain.remove_processor::<HoldProcessor>();
853    }
854}
855
856#[cfg(test)]
857mod recorder_owner_tests {
858    use super::*;
859    use crate::media::Samples;
860
861    fn pcm_frame(track_id: &str, len: usize) -> AudioFrame {
862        AudioFrame {
863            track_id: track_id.to_string(),
864            samples: Samples::PCM {
865                samples: vec![100i16; len],
866            },
867            sample_rate: 16000,
868            channels: 1,
869            ..Default::default()
870        }
871    }
872
873    /// Regression for media-pass recordings in non-native mode: the track's own
874    /// processor chain also processes audio it relays for another leg (the
875    /// caller's audio forwarded to the websocket). `RecorderProcessor` must
876    /// mirror only the track's own frames so the relayed copy is not written to
877    /// the recording twice.
878    #[test]
879    fn recorder_processor_only_mirrors_owned_frames() {
880        let (tx, mut rx) = mpsc::unbounded_channel();
881        let mut processor = RecorderProcessor::new(tx, "server-side-track".to_string());
882
883        let mut relayed = pcm_frame("caller-leg", 160);
884        processor.process_frame(&mut relayed).unwrap();
885        assert!(
886            rx.try_recv().is_err(),
887            "relayed caller audio must not be recorded"
888        );
889
890        let mut own = pcm_frame("server-side-track", 160);
891        processor.process_frame(&mut own).unwrap();
892        let mirrored = rx
893            .try_recv()
894            .expect("the track's own audio must be recorded");
895        assert_eq!(mirrored.track_id, "server-side-track");
896    }
897
898    /// A bare `RecorderProcessor` (e.g. attached to the caller leg) records its
899    /// own frames and ignores anything else.
900    #[test]
901    fn recorder_processor_records_caller_leg_only() {
902        let (tx, mut rx) = mpsc::unbounded_channel();
903        let mut processor = RecorderProcessor::new(tx, "caller-leg".to_string());
904
905        let mut own = pcm_frame("caller-leg", 160);
906        processor.process_frame(&mut own).unwrap();
907        assert!(rx.try_recv().is_ok());
908
909        let mut foreign = pcm_frame("server-side-track", 160);
910        processor.process_frame(&mut foreign).unwrap();
911        assert!(rx.try_recv().is_err());
912    }
913}