active-call 0.3.121

A SIP/WebRTC voice agent
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
use anyhow::Result;
use rsipstack::dialog::{authenticate::Credential, invitation::InviteOption};
use serde::{Deserialize, Serialize};
use serde_with::skip_serializing_none;
use std::collections::HashMap;

use crate::{
    media::{
        agc::AGCOption, ambiance::AmbianceOption, monitor::MonitorOption,
        recorder::RecorderOption, track::media_pass::MediaPassOption, vad::VADOption,
    },
    synthesis::SynthesisOption,
    transcription::TranscriptionOption,
};

pub mod app;
pub mod call;
pub mod callrecord;
pub mod config;
pub mod event;
pub mod handler;
pub mod locator;
pub mod main_builder;
pub mod media;
pub mod net_tool;

#[cfg(feature = "offline")]
pub mod offline;

pub mod playbook;
pub mod runtime;
pub mod sip_util;
pub mod sipflow;
pub mod synthesis;
pub mod transcription;
pub mod useragent;

#[derive(Deserialize, Serialize, Default, Clone)]
#[serde(default)]
pub struct SipOption {
    pub username: Option<String>,
    #[serde(skip_serializing)]
    pub password: Option<String>,
    pub realm: Option<String>,
    pub contact: Option<String>,
    pub headers: Option<HashMap<String, String>>,
    pub hangup_headers: Option<HashMap<String, String>>,
    pub extract_headers: Option<Vec<String>>,
    pub enable_srtp: Option<bool>,
}

impl std::fmt::Debug for SipOption {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SipOption")
            .field("username", &self.username)
            .field("password", &self.password.as_ref().map(|_| "***"))
            .field("realm", &self.realm)
            .field("contact", &self.contact)
            .field("headers", &self.headers)
            .field("hangup_headers", &self.hangup_headers)
            .field("extract_headers", &self.extract_headers)
            .field("enable_srtp", &self.enable_srtp)
            .finish()
    }
}

#[skip_serializing_none]
#[derive(Debug, Deserialize, Serialize, Clone)]
#[serde(rename_all = "camelCase")]
pub struct CallOption {
    pub denoise: Option<bool>,
    pub agc: Option<AGCOption>,
    pub offer: Option<String>,
    pub callee: Option<String>,
    pub caller: Option<String>,
    pub recorder: Option<RecorderOption>,
    pub vad: Option<VADOption>,
    pub asr: Option<TranscriptionOption>,
    pub tts: Option<SynthesisOption>,
    pub media_pass: Option<MediaPassOption>,
    // handshake timeout in seconds
    pub handshake_timeout: Option<u64>,
    pub enable_ipv6: Option<bool>,
    pub inactivity_timeout: Option<u64>, // inactivity timeout in seconds
    /// Incoming RTC sample timeout in seconds; None or zero disables notifications.
    pub rtp_timeout: Option<u64>,
    /// Jitter buffer and loss concealment on this leg's inbound audio (see
    /// rustrtc's `JitterBuffer::tick`). None: `[jitter_buffer]` in the
    /// config, by default on for WebRTC, off for SIP. Worth turning on for SIP endpoints on the
    /// open internet, such as softphones, rather than carrier trunks.
    pub jitter_buffer: Option<bool>,
    pub sip: Option<SipOption>,
    pub extra: Option<HashMap<String, String>>,
    pub codec: Option<String>, // pcmu, pcma, g722, pcm, only for websocket call
    pub ambiance: Option<AmbianceOption>,
    pub eou: Option<EouOption>,
    pub realtime: Option<RealtimeOption>,
    pub subscribe: Option<bool>,
    /// Side-path audio distribution: dial out to a websocket and mirror both
    /// legs' audio (one-way tap, the media path is untouched).
    pub monitor: Option<MonitorOption>,
    pub enable_ice_lite: Option<bool>,
    pub ringback_detection: Option<RingbackDetectionOption>,
}

impl Default for CallOption {
    fn default() -> Self {
        Self {
            denoise: None,
            agc: None,
            offer: None,
            callee: None,
            caller: None,
            recorder: None,
            asr: None,
            vad: None,
            tts: None,
            media_pass: None,
            handshake_timeout: None,
            inactivity_timeout: Some(50), // default 50 seconds
            rtp_timeout: None,
            jitter_buffer: None,
            enable_ipv6: None,
            sip: None,
            extra: None,
            codec: None,
            ambiance: None,
            eou: None,
            realtime: None,
            subscribe: None,
            monitor: None,
            enable_ice_lite: None,
            ringback_detection: None,
        }
    }
}

impl CallOption {
    pub fn check_default(&mut self) {
        if let Some(tts) = &mut self.tts {
            tts.check_default();
        }
        if let Some(asr) = &mut self.asr {
            asr.check_default();
        }
        if let Some(realtime) = &mut self.realtime {
            realtime.check_default();
        }
    }

    pub fn build_invite_option(&self) -> Result<InviteOption> {
        let mut invite_option = InviteOption::default();
        if let Some(offer) = &self.offer {
            invite_option.offer = Some(offer.clone().into());
        }
        if let Some(callee) = &self.callee {
            invite_option.callee = callee.clone().try_into()?;
        }
        let caller_uri = if let Some(caller) = &self.caller {
            // Ensure caller URI has proper sip: scheme
            crate::sip_util::ensure_sip_scheme(caller.clone())
        } else if let Some(username) = self.sip.as_ref().and_then(|sip| sip.username.as_ref()) {
            // If caller is not specified but we have SIP credentials, use username as caller
            // If realm is available, use it, otherwise use local IP
            let domain = self
                .sip
                .as_ref()
                .and_then(|sip| sip.realm.as_ref())
                .map(|s| s.as_str())
                .unwrap_or("127.0.0.1");
            format!("sip:{}@{}", username, domain)
        } else {
            // Default to a valid SIP URI if nothing is specified
            "sip:active-call@127.0.0.1".to_string()
        };
        invite_option.caller = caller_uri.try_into()?;

        if let Some(sip) = &self.sip {
            invite_option.credential = Some(Credential {
                username: sip.username.clone().unwrap_or_default(),
                auth_username: None,
                password: sip.password.clone().unwrap_or_default(),
                realm: sip.realm.clone(),
            });
            invite_option.headers = sip
                .headers
                .as_ref()
                .map(crate::sip_util::sip_headers_from_map);
            sip.contact.as_ref().map(|c| match c.clone().try_into() {
                Ok(u) => {
                    invite_option.contact = u;
                }
                Err(_) => {}
            });
        }
        Ok(invite_option)
    }
}

#[skip_serializing_none]
#[derive(Debug, Deserialize, Serialize, Clone)]
#[serde(rename_all = "camelCase")]
pub struct ReferOption {
    pub denoise: Option<bool>,
    pub agc: Option<AGCOption>,
    pub timeout: Option<u32>,
    pub moh: Option<String>,
    pub vad: Option<VADOption>,
    pub asr: Option<TranscriptionOption>,
    /// hangup after the call is ended
    pub auto_hangup: Option<bool>,
    pub sip: Option<SipOption>,
    pub call_id: Option<String>,
    /// Pause parent call's ASR during refer call, will resume after refer ends (if auto_hangup is false)
    pub pause_parent_asr: Option<bool>,
    /// If false, DTMF RTP packets are not forwarded between the main call and the refer call
    pub forward_dtmf: Option<bool>,
    /// Custom headers blindly forwarded onto the transfer INVITE (e.g.
    /// `User-to-User`, `X-ACC-Bizdata` received on an incoming REFER).
    pub extra_headers: Option<HashMap<String, String>>,
    /// Inactivity timeout (seconds) for the refer/bridge legs. When the leg
    /// receives no media frames for this long it fires
    /// `SessionEvent::Inactivity`, which ends the call. Defaults to
    /// `CallOption::default()` (50s); `0` disables the watchdog.
    pub inactivity_timeout: Option<u64>,
}

#[skip_serializing_none]
#[derive(Clone, Debug, Deserialize, Serialize, Default)]
#[serde(rename_all = "camelCase")]
pub struct EouOption {
    pub r#type: Option<String>,
    pub endpoint: Option<String>,
    #[serde(alias = "apiKey")]
    pub secret_key: Option<String>,
    pub secret_id: Option<String>,
    /// max timeout in milliseconds
    pub timeout: Option<u32>,
    pub extra: Option<HashMap<String, String>>,
}

#[skip_serializing_none]
#[derive(Clone, Debug, Deserialize, Serialize, Default)]
#[serde(rename_all = "camelCase")]
pub struct RingbackDetectionOption {
    pub enabled: Option<bool>,
    /// Path to telcoclassifier_weights.bin (default: "./telcoclassifier_weights.bin")
    pub model_weights_path: Option<String>,
    /// Minimum audio accumulation (seconds) before first inference
    pub min_buffer_secs: Option<f32>,
    /// Seconds between consecutive inferences
    pub detection_interval_secs: Option<f32>,
    /// Confidence threshold for reporting a state
    pub confidence_threshold: Option<f32>,
    /// Only emit events on state change (ringing→human_voice etc.)
    pub on_state_change_only: Option<bool>,
    /// Sliding window size for result accumulation (default: 6, i.e. 4+2)
    pub sliding_window_size: Option<usize>,
    /// Confidence threshold for immediate finalization (default: 0.9)
    pub final_confidence_threshold: Option<f32>,
    /// Upper bound for inference worker threads (process-wide, first
    /// initialization wins).
    pub inference_threads: Option<usize>,
}

#[derive(Debug, Clone, Serialize, Hash, Eq, PartialEq)]
pub enum RealtimeType {
    #[serde(rename = "openai")]
    OpenAI,
    #[serde(rename = "azure")]
    Azure,
    Other(String),
}

impl<'de> Deserialize<'de> for RealtimeType {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let value = String::deserialize(deserializer)?;
        match value.as_str() {
            "openai" => Ok(RealtimeType::OpenAI),
            "azure" => Ok(RealtimeType::Azure),
            _ => Ok(RealtimeType::Other(value)),
        }
    }
}

#[skip_serializing_none]
#[derive(Clone, Deserialize, Serialize, Default)]
#[serde(rename_all = "camelCase")]
pub struct RealtimeOption {
    pub provider: Option<RealtimeType>,
    pub model: Option<String>,
    #[serde(alias = "apiKey")]
    pub secret_key: Option<String>,
    pub secret_id: Option<String>,
    pub endpoint: Option<String>,
    pub turn_detection: Option<serde_json::Value>,
    pub tools: Option<Vec<serde_json::Value>>,
    pub extra: Option<HashMap<String, String>>,
}

impl std::fmt::Debug for RealtimeOption {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RealtimeOption")
            .field("provider", &self.provider)
            .field("model", &self.model)
            .field("secret_key", &self.secret_key.as_ref().map(|_| "***"))
            .field("secret_id", &self.secret_id)
            .field("endpoint", &self.endpoint)
            .field("turn_detection", &self.turn_detection)
            .field("tools", &self.tools)
            .field("extra", &self.extra)
            .finish()
    }
}

impl RealtimeOption {
    pub fn check_default(&mut self) {
        if self.secret_key.is_none() {
            self.secret_key = std::env::var("OPENAI_API_KEY").ok();
        }
    }
}

pub type Spawner = fn(
    std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send>>,
) -> tokio::task::JoinHandle<()>;
static EXTERNAL_SPAWNER: std::sync::OnceLock<Spawner> = std::sync::OnceLock::new();

pub fn set_spawner(spawner: Spawner) -> Result<(), Spawner> {
    EXTERNAL_SPAWNER.set(spawner)
}

pub fn spawn<F>(future: F) -> tokio::task::JoinHandle<()>
where
    F: std::future::Future<Output = ()> + Send + 'static,
{
    if let Some(spawner) = EXTERNAL_SPAWNER.get() {
        spawner(Box::pin(future))
    } else {
        tokio::spawn(future)
    }
}

#[cfg(test)]
mod rtp_timeout_tests {
    use super::CallOption;
    use crate::call::Command;

    #[test]
    fn rtp_timeout_is_optional_and_shared_by_invite_and_accept() {
        assert_eq!(CallOption::default().rtp_timeout, None);
        assert!(
            serde_json::to_value(CallOption::default())
                .unwrap()
                .get("rtpTimeout")
                .is_none()
        );
        for command in ["invite", "accept"] {
            for (option, expected) in [
                (serde_json::json!({}), None),
                (serde_json::json!({"rtpTimeout": null}), None),
                (serde_json::json!({"rtpTimeout": 0}), Some(0)),
                (serde_json::json!({"rtpTimeout": 30}), Some(30)),
            ] {
                let parsed: Command = serde_json::from_value(serde_json::json!({
                    "command": command, "option": option,
                }))
                .unwrap();
                match parsed {
                    Command::Invite { option } | Command::Accept { option } => {
                        assert_eq!(option.rtp_timeout, expected);
                    }
                    _ => unreachable!(),
                }
            }
        }
    }
}

#[cfg(test)]
mod jitter_buffer_option_tests {
    use crate::call::Command;

    #[test]
    fn jitter_buffer_is_set_per_call_by_invite_and_accept() {
        for command in ["invite", "accept"] {
            for (option, expected) in [
                (serde_json::json!({}), None),
                (serde_json::json!({"jitterBuffer": true}), Some(true)),
                (serde_json::json!({"jitterBuffer": false}), Some(false)),
            ] {
                let parsed: Command = serde_json::from_value(serde_json::json!({
                    "command": command, "option": option,
                }))
                .unwrap();
                match parsed {
                    Command::Invite { option } | Command::Accept { option } => {
                        assert_eq!(option.jitter_buffer, expected);
                    }
                    _ => unreachable!(),
                }
            }
        }
    }
}