serve.zone/siprouter
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(call, voicemail, ivr): add voicemail and IVR call flows with DTMF handling, prompt playback, recording, and dashboard management

Browse Source
This commit is contained in:
Jürgen Kunz
2026-04-10 08:54:46 +00:00
parent 6ecd3f434c
commit e6bd64a534
25 changed files with 3892 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
ts/call/audio-recorder.ts Normal file
View File

@@ -0,0 +1,323 @@
/**
* Audio recorder — captures RTP packets from a single direction,
* decodes them to PCM, and writes a WAV file.
*
* Uses the Rust codec bridge to transcode incoming audio (G.722, Opus,
* PCMU, PCMA) to PCMU, then decodes mu-law to 16-bit PCM in TypeScript.
* Output: 8kHz 16-bit mono WAV (standard telephony quality).
*
* Supports:
* - Max recording duration limit
* - Silence detection (stop after N seconds of silence)
* - Manual stop
* - DTMF packets (PT 101) are automatically skipped
*/
import { Buffer } from 'node:buffer';
import fs from 'node:fs';
import path from 'node:path';
import { WavWriter } from './wav-writer.ts';
import type { IWavWriterResult } from './wav-writer.ts';
import { transcode, createSession, destroySession } from '../opusbridge.ts';
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
export interface IRecordingOptions {
/** Output directory for WAV files. */
outputDir: string;
/** Target sample rate for the WAV output (default 8000). */
sampleRate?: number;
/** Maximum recording duration in seconds. 0 = unlimited. Default 120. */
maxDurationSec?: number;
/** Stop after this many consecutive seconds of silence. 0 = disabled. Default 5. */
silenceTimeoutSec?: number;
/** Silence threshold: max PCM amplitude below this is "silent". Default 200. */
silenceThreshold?: number;
/** Logging function. */
log: (msg: string) => void;
}
export interface IRecordingResult {
/** Full path to the WAV file. */
filePath: string;
/** Duration in milliseconds. */
durationMs: number;
/** Sample rate of the WAV. */
sampleRate: number;
/** Size of the WAV file in bytes. */
fileSize: number;
/** Why the recording was stopped. */
stopReason: TRecordingStopReason;
}
export type TRecordingStopReason = 'manual' | 'max-duration' | 'silence' | 'cancelled';
// ---------------------------------------------------------------------------
// Mu-law decode table (ITU-T G.711)
// ---------------------------------------------------------------------------
/** Pre-computed mu-law → 16-bit linear PCM lookup table (256 entries). */
const MULAW_DECODE: Int16Array = buildMulawDecodeTable();
function buildMulawDecodeTable(): Int16Array {
const table = new Int16Array(256);
for (let i = 0; i < 256; i++) {
// Invert all bits per mu-law standard.
let mu = ~i & 0xff;
const sign = mu & 0x80;
const exponent = (mu >> 4) & 0x07;
const mantissa = mu & 0x0f;
let magnitude = ((mantissa << 1) + 33) << (exponent + 2);
magnitude -= 0x84; // Bias adjustment
table[i] = sign ? -magnitude : magnitude;
}
return table;
}
/** Decode a PCMU payload to 16-bit LE PCM. */
function decodeMulaw(mulaw: Buffer): Buffer {
const pcm = Buffer.alloc(mulaw.length * 2);
for (let i = 0; i < mulaw.length; i++) {
pcm.writeInt16LE(MULAW_DECODE[mulaw[i]], i * 2);
}
return pcm;
}
// ---------------------------------------------------------------------------
// AudioRecorder
// ---------------------------------------------------------------------------
export class AudioRecorder {
/** Current state. */
state: 'idle' | 'recording' | 'stopped' = 'idle';
/** Called when recording stops automatically (silence or max duration). */
onStopped: ((result: IRecordingResult) => void) | null = null;
private outputDir: string;
private sampleRate: number;
private maxDurationSec: number;
private silenceTimeoutSec: number;
private silenceThreshold: number;
private log: (msg: string) => void;
private wavWriter: WavWriter | null = null;
private filePath: string = '';
private codecSessionId: string | null = null;
private stopReason: TRecordingStopReason = 'manual';
// Silence detection.
private consecutiveSilentFrames = 0;
/** Number of 20ms frames that constitute silence timeout. */
private silenceFrameThreshold = 0;
// Max duration timer.
private maxDurationTimer: ReturnType<typeof setTimeout> | null = null;
// Processing queue to avoid concurrent transcodes.
private processQueue: Promise<void> = Promise.resolve();
constructor(options: IRecordingOptions) {
this.outputDir = options.outputDir;
this.sampleRate = options.sampleRate ?? 8000;
this.maxDurationSec = options.maxDurationSec ?? 120;
this.silenceTimeoutSec = options.silenceTimeoutSec ?? 5;
this.silenceThreshold = options.silenceThreshold ?? 200;
this.log = options.log;
}
/**
* Start recording. Creates the output directory, WAV file, and codec session.
* @param fileId - unique ID for the recording file name
*/
async start(fileId?: string): Promise<void> {
if (this.state !== 'idle') return;
// Ensure output directory exists.
if (!fs.existsSync(this.outputDir)) {
fs.mkdirSync(this.outputDir, { recursive: true });
}
// Generate file path.
const id = fileId ?? `rec-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
this.filePath = path.join(this.outputDir, `${id}.wav`);
// Create a codec session for isolated decoding.
this.codecSessionId = `recorder-${id}`;
await createSession(this.codecSessionId);
// Open WAV writer.
this.wavWriter = new WavWriter({
filePath: this.filePath,
sampleRate: this.sampleRate,
});
this.wavWriter.open();
// Silence detection threshold: frames in timeout period.
this.silenceFrameThreshold = this.silenceTimeoutSec > 0
? Math.ceil((this.silenceTimeoutSec * 1000) / 20)
: 0;
this.consecutiveSilentFrames = 0;
// Max duration timer.
if (this.maxDurationSec > 0) {
this.maxDurationTimer = setTimeout(() => {
if (this.state === 'recording') {
this.stopReason = 'max-duration';
this.log(`[recorder] max duration reached (${this.maxDurationSec}s)`);
this.stop().then((result) => this.onStopped?.(result));
}
}, this.maxDurationSec * 1000);
}
this.state = 'recording';
this.stopReason = 'manual';
this.log(`[recorder] started → ${this.filePath}`);
}
/**
* Feed an RTP packet. Strips the 12-byte header, transcodes the payload
* to PCMU via the Rust bridge, decodes to PCM, and writes to WAV.
* Skips telephone-event (DTMF) and comfort noise packets.
*/
processRtp(data: Buffer): void {
if (this.state !== 'recording') return;
if (data.length < 13) return; // too short
const pt = data[1] & 0x7f;
// Skip DTMF (telephone-event) and comfort noise.
if (pt === 101 || pt === 13) return;
const payload = data.subarray(12);
if (payload.length === 0) return;
// Queue processing to avoid concurrent transcodes corrupting codec state.
this.processQueue = this.processQueue.then(() => this.decodeAndWrite(payload, pt));
}
/** Decode a single RTP payload to PCM and write to WAV. */
private async decodeAndWrite(payload: Buffer, pt: number): Promise<void> {
if (this.state !== 'recording' || !this.wavWriter) return;
let pcm: Buffer;
if (pt === 0) {
// PCMU: decode directly in TypeScript (no Rust round-trip needed).
pcm = decodeMulaw(payload);
} else {
// All other codecs: transcode to PCMU via Rust, then decode mu-law.
const mulaw = await transcode(payload, pt, 0, this.codecSessionId ?? undefined);
if (!mulaw) return;
pcm = decodeMulaw(mulaw);
}
// Silence detection.
if (this.silenceFrameThreshold > 0) {
if (isSilent(pcm, this.silenceThreshold)) {
this.consecutiveSilentFrames++;
if (this.consecutiveSilentFrames >= this.silenceFrameThreshold) {
this.stopReason = 'silence';
this.log(`[recorder] silence detected (${this.silenceTimeoutSec}s)`);
this.stop().then((result) => this.onStopped?.(result));
return;
}
} else {
this.consecutiveSilentFrames = 0;
}
}
this.wavWriter.write(pcm);
}
/**
* Stop recording and finalize the WAV file.
*/
async stop(): Promise<IRecordingResult> {
if (this.state === 'stopped' || this.state === 'idle') {
return {
filePath: this.filePath,
durationMs: 0,
sampleRate: this.sampleRate,
fileSize: 0,
stopReason: this.stopReason,
};
}
this.state = 'stopped';
// Wait for pending decode operations to finish.
await this.processQueue;
// Clear timers.
if (this.maxDurationTimer) {
clearTimeout(this.maxDurationTimer);
this.maxDurationTimer = null;
}
// Finalize WAV.
let wavResult: IWavWriterResult | null = null;
if (this.wavWriter) {
wavResult = this.wavWriter.close();
this.wavWriter = null;
}
// Destroy codec session.
if (this.codecSessionId) {
await destroySession(this.codecSessionId);
this.codecSessionId = null;
}
const result: IRecordingResult = {
filePath: this.filePath,
durationMs: wavResult?.durationMs ?? 0,
sampleRate: this.sampleRate,
fileSize: wavResult?.fileSize ?? 0,
stopReason: this.stopReason,
};
this.log(`[recorder] stopped (${result.stopReason}): ${result.durationMs}ms → ${this.filePath}`);
return result;
}
/** Cancel recording — stops and deletes the WAV file. */
async cancel(): Promise<void> {
this.stopReason = 'cancelled';
await this.stop();
// Delete the incomplete file.
try {
if (fs.existsSync(this.filePath)) {
fs.unlinkSync(this.filePath);
this.log(`[recorder] cancelled — deleted ${this.filePath}`);
}
} catch { /* best effort */ }
}
/** Clean up all resources. */
destroy(): void {
if (this.state === 'recording') {
this.cancel();
}
this.onStopped = null;
}
}
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
/** Check if a PCM buffer is "silent" (max amplitude below threshold). */
function isSilent(pcm: Buffer, threshold: number): boolean {
let maxAmp = 0;
for (let i = 0; i < pcm.length - 1; i += 2) {
const sample = pcm.readInt16LE(i);
const abs = sample < 0 ? -sample : sample;
if (abs > maxAmp) maxAmp = abs;
// Early exit: already above threshold.
if (maxAmp >= threshold) return false;
}
return true;
}

455
ts/call/call-manager.ts
View File

@@ -22,6 +22,7 @@ import {
rewriteSdp,
rewriteSipUri,
generateTag,
buildMwiBody,
} from '../sip/index.ts';
import type { IEndpoint } from '../sip/index.ts';
import type { IAppConfig, IProviderConfig } from '../config.ts';
@@ -39,6 +40,13 @@ import {
isKnownDeviceAddress,
} from '../registrar.ts';
import { WebSocket } from 'ws';
import { SystemLeg } from './system-leg.ts';
import type { ISystemLegConfig } from './system-leg.ts';
import { PromptCache } from './prompt-cache.ts';
import { VoiceboxManager } from '../voicebox.ts';
import type { IVoicemailMessage } from '../voicebox.ts';
import { IvrEngine } from '../ivr.ts';
import type { IIvrConfig, TIvrAction, IVoiceboxConfig as IVoiceboxCfg } from '../config.ts';
// ---------------------------------------------------------------------------
// CallManager config
@@ -53,6 +61,10 @@ export interface ICallManagerConfig {
getAllBrowserDeviceIds: () => string[];
sendToBrowserDevice: (deviceId: string, data: unknown) => boolean;
getBrowserDeviceWs: (deviceId: string) => WebSocket | null;
/** Prompt cache for IVR/voicemail audio playback. */
promptCache?: PromptCache;
/** Voicebox manager for voicemail storage and retrieval. */
voiceboxManager?: VoiceboxManager;
}
// ---------------------------------------------------------------------------
@@ -179,6 +191,41 @@ export class CallManager {
return;
}
}
// Intercept busy/unavailable responses — route to voicemail if configured.
// When the device rejects the call (486 Busy, 480 Unavailable, 600/603 Decline),
// answer the provider's INVITE with our own SDP and start voicemail.
if (msg.isResponse && msg.cseqMethod?.toUpperCase() === 'INVITE') {
const code = msg.statusCode;
if (code === 486 || code === 480 || code === 600 || code === 603) {
const callId = pt.call.id;
const boxId = this.findVoiceboxForCall(pt.call);
if (boxId) {
this.config.log(`[call-mgr] device responded ${code} — routing to voicemail box "${boxId}"`);
// Build a 200 OK with our own SDP to answer the provider's INVITE.
const sdpBody = buildSdp({
address: pub,
port: pt.rtpPort,
payloadTypes: pt.providerConfig.codecs || [9, 0, 8, 101],
});
// We need to construct the 200 OK as if *we* are answering the provider.
// The original INVITE from the provider used the passthrough SIP Call-ID.
// Build a response using the forwarded INVITE's headers.
const ok200 = SipMessage.createResponse(200, 'OK', msg, {
body: sdpBody,
contentType: 'application/sdp',
contact: `<sip:${lanIp}:${lanPort}>`,
});
this.config.sendSip(ok200.serialize(), pt.providerConfig.outboundProxy);
// Now route to voicemail.
this.routeToVoicemail(callId, boxId);
return;
}
}
}
// Rewrite Contact.
const contact = msg.getHeader('Contact');
if (contact) {
@@ -601,6 +648,49 @@ export class CallManager {
}
call.state = 'ringing';
// --- IVR / Voicemail routing ---
if (routeResult.ivrMenuId && this.config.appConfig.ivr?.enabled) {
// Route directly to IVR — don't ring devices.
this.config.log(`[call-mgr] inbound call ${callId} routed to IVR menu "${routeResult.ivrMenuId}"`);
// Respond 200 OK to the provider INVITE first.
const okForProvider = SipMessage.createResponse(200, 'OK', invite, {
body: fwdInvite.body, // rewritten SDP
contentType: 'application/sdp',
});
this.config.sendSip(okForProvider.serialize(), rinfo);
this.routeToIvr(callId, this.config.appConfig.ivr);
} else if (routeResult.voicemailBox) {
// Route directly to voicemail — don't ring devices.
this.config.log(`[call-mgr] inbound call ${callId} routed directly to voicemail box "${routeResult.voicemailBox}"`);
const okForProvider = SipMessage.createResponse(200, 'OK', invite, {
body: fwdInvite.body,
contentType: 'application/sdp',
});
this.config.sendSip(okForProvider.serialize(), rinfo);
this.routeToVoicemail(callId, routeResult.voicemailBox);
} else {
// Normal ringing — start voicemail no-answer timer if applicable.
const vm = this.config.voiceboxManager;
if (vm) {
// Find first voicebox for the target devices.
const boxId = this.findVoiceboxForDevices(targetDeviceIds);
if (boxId) {
const box = vm.getBox(boxId);
if (box?.enabled) {
const timeoutSec = routeResult.noAnswerTimeout ?? box.noAnswerTimeoutSec ?? 25;
setTimeout(() => {
const c = this.calls.get(callId);
if (c && c.state === 'ringing') {
this.config.log(`[call-mgr] no answer after ${timeoutSec}s — routing to voicemail box "${boxId}"`);
this.routeToVoicemail(callId, boxId);
}
}, timeoutSec * 1000);
}
}
}
}
return call;
}
@@ -1092,6 +1182,371 @@ export class CallManager {
}
}
// -------------------------------------------------------------------------
// Voicemail routing
// -------------------------------------------------------------------------
/**
* Route a call to voicemail. Cancels ringing devices, creates a SystemLeg,
* plays the greeting, then starts recording.
*/
routeToVoicemail(callId: string, boxId: string): void {
const call = this.calls.get(callId);
if (!call) return;
const vm = this.config.voiceboxManager;
const pc = this.config.promptCache;
if (!vm || !pc) {
this.config.log(`[call-mgr] voicemail not available (manager or prompt cache missing)`);
return;
}
const box = vm.getBox(boxId);
if (!box) {
this.config.log(`[call-mgr] voicebox "${boxId}" not found`);
return;
}
// Cancel all ringing/device legs — keep only provider leg(s).
const legsToRemove: string[] = [];
for (const leg of call.getLegs()) {
if (leg.type === 'sip-device' || leg.type === 'webrtc') {
legsToRemove.push(leg.id);
}
}
for (const legId of legsToRemove) {
const leg = call.getLeg(legId);
if (leg && (leg.type === 'sip-device' || leg.type === 'sip-provider')) {
(leg as SipLeg).sendHangup(); // CANCEL ringing devices
}
call.removeLeg(legId);
}
// Cancel passthrough tracking for this call (if applicable).
for (const [sipCallId, pt] of this.passthroughCalls) {
if (pt.call === call) {
// Keep the RTP socket — the SystemLeg will use it indirectly through the hub.
this.passthroughCalls.delete(sipCallId);
break;
}
}
// Create a SystemLeg.
const systemLegId = `${callId}-vm`;
const systemLeg = new SystemLeg(systemLegId, {
log: this.config.log,
promptCache: pc,
callerCodecPt: 9, // SIP callers use G.722 by default
onDtmfDigit: (digit) => {
// '#' during recording = stop and save.
if (digit.digit === '#' && systemLeg.mode === 'voicemail-recording') {
this.config.log(`[call-mgr] voicemail: caller pressed # — stopping recording`);
systemLeg.stopRecording().then((result) => {
if (result && result.durationMs > 500) {
this.saveVoicemailMessage(boxId, call, result);
}
call.hangup();
});
}
},
onRecordingComplete: (result) => {
if (result.durationMs > 500) {
this.saveVoicemailMessage(boxId, call, result);
}
},
});
call.addLeg(systemLeg);
call.state = 'voicemail';
// Determine greeting prompt ID.
const greetingPromptId = `voicemail-greeting-${boxId}`;
const beepPromptId = 'voicemail-beep';
// Play greeting, then beep, then start recording.
systemLeg.mode = 'voicemail-greeting';
const startSequence = () => {
systemLeg.playPrompt(greetingPromptId, () => {
// Greeting done — play beep.
systemLeg.playPrompt(beepPromptId, () => {
// Beep done — start recording.
const recordDir = vm.getBoxDir(boxId);
const fileId = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
systemLeg.startRecording(recordDir, fileId);
this.config.log(`[call-mgr] voicemail recording started for box "${boxId}"`);
});
});
};
// Check if the greeting prompt is already cached; if not, generate it.
if (pc.has(greetingPromptId)) {
startSequence();
} else {
// Generate the greeting on-the-fly.
const wavPath = vm.getCustomGreetingWavPath(boxId);
const generatePromise = wavPath
? pc.loadWavPrompt(greetingPromptId, wavPath)
: pc.generatePrompt(greetingPromptId, vm.getGreetingText(boxId), vm.getGreetingVoice(boxId));
generatePromise.then(() => {
if (call.state !== 'terminated') startSequence();
});
}
}
/** Save a voicemail message after recording completes. */
private saveVoicemailMessage(boxId: string, call: Call, result: import('./audio-recorder.ts').IRecordingResult): void {
const vm = this.config.voiceboxManager;
if (!vm) return;
const fileName = result.filePath.split('/').pop() || 'unknown.wav';
const msg: IVoicemailMessage = {
id: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
boxId,
callerNumber: call.callerNumber || 'Unknown',
timestamp: Date.now(),
durationMs: result.durationMs,
fileName,
heard: false,
};
vm.saveMessage(msg);
this.config.log(`[call-mgr] voicemail saved: ${msg.id} (${result.durationMs}ms) in box "${boxId}"`);
// Send MWI NOTIFY to the associated device.
this.sendMwiNotify(boxId);
}
/** Send MWI (Message Waiting Indicator) NOTIFY to a device for a voicebox. */
private sendMwiNotify(boxId: string): void {
const vm = this.config.voiceboxManager;
if (!vm) return;
const reg = getRegisteredDevice(boxId);
if (!reg?.contact) return; // Device not registered — skip.
const newCount = vm.getUnheardCount(boxId);
const totalCount = vm.getTotalCount(boxId);
const oldCount = totalCount - newCount;
const lanIp = this.config.appConfig.proxy.lanIp;
const lanPort = this.config.appConfig.proxy.lanPort;
const accountUri = `sip:${boxId}@${lanIp}`;
const targetUri = `sip:${reg.aor || boxId}@${reg.contact.address}:${reg.contact.port}`;
const mwi = buildMwiBody(newCount, oldCount, accountUri);
const notify = SipMessage.createRequest('NOTIFY', targetUri, {
via: { host: lanIp, port: lanPort },
from: { uri: accountUri },
to: { uri: targetUri },
contact: `<sip:${lanIp}:${lanPort}>`,
body: mwi.body,
contentType: mwi.contentType,
extraHeaders: mwi.extraHeaders,
});
this.config.sendSip(notify.serialize(), reg.contact);
this.config.log(`[call-mgr] MWI NOTIFY sent to ${boxId}: ${newCount} new, ${oldCount} old`);
}
// -------------------------------------------------------------------------
// IVR routing
// -------------------------------------------------------------------------
/**
* Route a call to IVR. Creates a SystemLeg and starts the IVR engine.
*/
routeToIvr(callId: string, ivrConfig: IIvrConfig): void {
const call = this.calls.get(callId);
if (!call) return;
const pc = this.config.promptCache;
if (!pc) {
this.config.log(`[call-mgr] IVR not available (prompt cache missing)`);
return;
}
// Cancel all ringing device legs.
const legsToRemove: string[] = [];
for (const leg of call.getLegs()) {
if (leg.type === 'sip-device' || leg.type === 'webrtc') {
legsToRemove.push(leg.id);
}
}
for (const legId of legsToRemove) {
const leg = call.getLeg(legId);
if (leg && (leg.type === 'sip-device' || leg.type === 'sip-provider')) {
(leg as SipLeg).sendHangup();
}
call.removeLeg(legId);
}
// Remove passthrough tracking.
for (const [sipCallId, pt] of this.passthroughCalls) {
if (pt.call === call) {
this.passthroughCalls.delete(sipCallId);
break;
}
}
// Create SystemLeg for IVR.
const systemLegId = `${callId}-ivr`;
const systemLeg = new SystemLeg(systemLegId, {
log: this.config.log,
promptCache: pc,
callerCodecPt: 9,
});
call.addLeg(systemLeg);
call.state = 'ivr';
systemLeg.mode = 'ivr';
// Create IVR engine.
const ivrEngine = new IvrEngine(
ivrConfig,
systemLeg,
(action: TIvrAction) => this.handleIvrAction(callId, action, ivrEngine, systemLeg),
this.config.log,
);
// Wire DTMF digits to the IVR engine.
systemLeg.config.onDtmfDigit = (digit) => {
ivrEngine.handleDigit(digit.digit);
};
// Start the IVR.
ivrEngine.start();
}
/** Handle an action from the IVR engine. */
private handleIvrAction(
callId: string,
action: TIvrAction,
ivrEngine: IvrEngine,
systemLeg: SystemLeg,
): void {
const call = this.calls.get(callId);
if (!call) return;
switch (action.type) {
case 'route-extension': {
// Tear down IVR and ring the target device.
ivrEngine.destroy();
call.removeLeg(systemLeg.id);
const extTarget = this.resolveDeviceTarget(action.extensionId);
if (!extTarget) {
this.config.log(`[call-mgr] IVR: extension "${action.extensionId}" not found — hanging up`);
call.hangup();
break;
}
const rtpExt = this.portPool.allocate();
if (!rtpExt) {
this.config.log(`[call-mgr] IVR: port pool exhausted — hanging up`);
call.hangup();
break;
}
const ps = [...this.config.appConfig.providers]
.map((p) => this.config.getProviderState(p.id))
.find((s) => s?.publicIp);
const extLegConfig: ISipLegConfig = {
role: 'device',
lanIp: this.config.appConfig.proxy.lanIp,
lanPort: this.config.appConfig.proxy.lanPort,
getPublicIp: () => ps?.publicIp ?? null,
sendSip: this.config.sendSip,
log: this.config.log,
sipTarget: extTarget,
rtpPort: rtpExt.port,
rtpSock: rtpExt.sock,
};
const extLeg = new SipLeg(`${callId}-ext`, extLegConfig);
extLeg.onTerminated = (leg) => call.handleLegTerminated(leg.id);
extLeg.onStateChange = () => call.notifyLegStateChange(extLeg);
call.addLeg(extLeg);
call.state = 'ringing';
const sipCallIdExt = `${callId}-ext-${Date.now()}`;
extLeg.sendInvite({
fromUri: `sip:${call.callerNumber || 'unknown'}@${this.config.appConfig.proxy.lanIp}`,
fromDisplayName: call.callerNumber || 'Unknown',
toUri: `sip:user@${extTarget.address}`,
callId: sipCallIdExt,
});
this.sipCallIdIndex.set(sipCallIdExt, call);
this.config.log(`[call-mgr] IVR: ringing extension "${action.extensionId}"`);
break;
}
case 'route-voicemail': {
ivrEngine.destroy();
call.removeLeg(systemLeg.id);
this.routeToVoicemail(callId, action.boxId);
break;
}
case 'transfer': {
ivrEngine.destroy();
call.removeLeg(systemLeg.id);
// Resolve provider for outbound dial.
const xferRoute = resolveOutboundRoute(
this.config.appConfig,
action.number,
undefined,
(pid) => !!this.config.getProviderState(pid)?.registeredAor,
);
if (!xferRoute) {
this.config.log(`[call-mgr] IVR: no provider for transfer to ${action.number} — hanging up`);
call.hangup();
break;
}
const xferPs = this.config.getProviderState(xferRoute.provider.id);
if (!xferPs) {
call.hangup();
break;
}
this.startProviderLeg(call, xferRoute.provider, xferRoute.transformedNumber, xferPs);
this.config.log(`[call-mgr] IVR: transferring to ${action.number} via ${xferRoute.provider.displayName}`);
break;
}
case 'hangup': {
ivrEngine.destroy();
call.hangup();
break;
}
default:
break;
}
}
/** Find the voicebox for a call (uses all device IDs or fallback to first enabled). */
private findVoiceboxForCall(call: Call): string | null {
const allDeviceIds = this.config.appConfig.devices.map((d) => d.id);
return this.findVoiceboxForDevices(allDeviceIds);
}
/** Find the first voicebox ID associated with a set of target device IDs. */
private findVoiceboxForDevices(deviceIds: string[]): string | null {
const voiceboxes = this.config.appConfig.voiceboxes ?? [];
for (const deviceId of deviceIds) {
const box = voiceboxes.find((vb) => vb.id === deviceId);
if (box?.enabled) return box.id;
}
// Fallback: first enabled voicebox.
const first = voiceboxes.find((vb) => vb.enabled);
return first?.id ?? null;
}
// -------------------------------------------------------------------------
// Status
// -------------------------------------------------------------------------

14
ts/call/call.ts
View File

@@ -138,7 +138,16 @@ export class Call {
} else if (legs.every((l) => l.state === 'terminated')) {
this.state = 'terminated';
} else if (legs.some((l) => l.state === 'connected') && legs.filter((l) => l.state !== 'terminated').length >= 2) {
this.state = 'connected';
// If a system leg is connected, report voicemail/ivr state for the dashboard.
const systemLeg = legs.find((l) => l.type === 'system');
if (systemLeg) {
// Keep voicemail/ivr state if already set; otherwise set connected.
if (this.state !== 'voicemail' && this.state !== 'ivr') {
this.state = 'connected';
}
} else {
this.state = 'connected';
}
} else if (legs.some((l) => l.state === 'ringing')) {
this.state = 'ringing';
} else {
@@ -164,7 +173,7 @@ export class Call {
this.log(`[call:${this.id}] hanging up (${this.legs.size} legs)`);
for (const [id, leg] of this.legs) {
// Send BYE/CANCEL for SIP legs.
// Send BYE/CANCEL for SIP legs (system legs have no SIP signaling).
if (leg.type === 'sip-device' || leg.type === 'sip-provider') {
(leg as SipLeg).sendHangup();
}
@@ -197,6 +206,7 @@ export class Call {
// If this is a 2-party call, hang up the other leg too.
if (this.legs.size <= 1) {
for (const [id, leg] of this.legs) {
// Send BYE/CANCEL for SIP legs (system legs just get torn down).
if (leg.type === 'sip-device' || leg.type === 'sip-provider') {
(leg as SipLeg).sendHangup();
}

272
ts/call/dtmf-detector.ts Normal file
View File

@@ -0,0 +1,272 @@
/**
* DTMF detection — parses RFC 2833 telephone-event RTP packets
* and SIP INFO (application/dtmf-relay) messages.
*
* Designed to be attached to any leg or RTP stream. The detector
* deduplicates repeated telephone-event packets (same digit is sent
* multiple times with increasing duration) and fires a callback
* once per detected digit.
*/
import { Buffer } from 'node:buffer';
import type { SipMessage } from '../sip/index.ts';
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
/** A single detected DTMF digit. */
export interface IDtmfDigit {
/** The digit character: '0'-'9', '*', '#', 'A'-'D'. */
digit: string;
/** Duration in milliseconds. */
durationMs: number;
/** Detection source. */
source: 'rfc2833' | 'sip-info';
/** Wall-clock timestamp when the digit was detected. */
timestamp: number;
}
/** Callback fired once per detected DTMF digit. */
export type TDtmfCallback = (digit: IDtmfDigit) => void;
// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------
/** RFC 2833 event ID → character mapping. */
const EVENT_CHARS: string[] = [
'0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
'*', '#', 'A', 'B', 'C', 'D',
];
/** Safety timeout: report digit if no End packet arrives within this many ms. */
const SAFETY_TIMEOUT_MS = 200;
// ---------------------------------------------------------------------------
// DtmfDetector
// ---------------------------------------------------------------------------
/**
* Detects DTMF digits from RFC 2833 RTP packets and SIP INFO messages.
*
* Usage:
* ```
* const detector = new DtmfDetector(log);
* detector.onDigit = (d) => console.log('DTMF:', d.digit);
* // Feed every RTP packet (detector checks PT internally):
* detector.processRtp(rtpPacket);
* // Or feed a SIP INFO message:
* detector.processSipInfo(sipMsg);
* ```
*/
export class DtmfDetector {
/** Callback fired once per detected digit. */
onDigit: TDtmfCallback | null = null;
/** Negotiated telephone-event payload type (default 101). */
private telephoneEventPt: number;
/** Clock rate for duration calculation (default 8000 Hz). */
private clockRate: number;
// -- Deduplication state for RFC 2833 --
/** Event ID of the digit currently being received. */
private currentEventId: number | null = null;
/** RTP timestamp of the first packet for the current event. */
private currentEventTs: number | null = null;
/** Whether the current event has already been reported. */
private currentEventReported = false;
/** Latest duration value seen (in clock ticks). */
private currentEventDuration = 0;
/** Latest volume value seen (dBm0, 0 = loudest). */
private currentEventVolume = 0;
/** Safety timer: fires if no End packet arrives. */
private safetyTimer: ReturnType<typeof setTimeout> | null = null;
private log: (msg: string) => void;
constructor(
log: (msg: string) => void,
telephoneEventPt = 101,
clockRate = 8000,
) {
this.log = log;
this.telephoneEventPt = telephoneEventPt;
this.clockRate = clockRate;
}
// -------------------------------------------------------------------------
// RFC 2833 RTP processing
// -------------------------------------------------------------------------
/**
* Feed an RTP packet. Checks PT; ignores non-DTMF packets.
* Expects the full RTP packet (12-byte header + payload).
*/
processRtp(data: Buffer): void {
if (data.length < 16) return; // 12-byte header + 4-byte telephone-event payload minimum
const pt = data[1] & 0x7f;
if (pt !== this.telephoneEventPt) return;
// Parse RTP header fields we need.
const marker = (data[1] & 0x80) !== 0;
const rtpTimestamp = data.readUInt32BE(4);
// Parse telephone-event payload (4 bytes starting at offset 12).
const eventId = data[12];
const endBit = (data[13] & 0x80) !== 0;
const volume = data[13] & 0x3f;
const duration = data.readUInt16BE(14);
// Validate event ID.
if (eventId >= EVENT_CHARS.length) return;
// Detect new event: marker bit, different event ID, or different RTP timestamp.
const isNewEvent =
marker ||
eventId !== this.currentEventId ||
rtpTimestamp !== this.currentEventTs;
if (isNewEvent) {
// If there was an unreported previous event, report it now (fallback).
this.reportPendingEvent();
// Start tracking the new event.
this.currentEventId = eventId;
this.currentEventTs = rtpTimestamp;
this.currentEventReported = false;
this.currentEventDuration = duration;
this.currentEventVolume = volume;
// Start safety timer.
this.clearSafetyTimer();
this.safetyTimer = setTimeout(() => {
this.reportPendingEvent();
}, SAFETY_TIMEOUT_MS);
}
// Update duration (it increases with each retransmission).
if (duration > this.currentEventDuration) {
this.currentEventDuration = duration;
}
// Report on End bit (first time only).
if (endBit && !this.currentEventReported) {
this.currentEventReported = true;
this.clearSafetyTimer();
const digit = EVENT_CHARS[eventId];
const durationMs = (this.currentEventDuration / this.clockRate) * 1000;
this.log(`[dtmf] RFC 2833 digit '${digit}' (${Math.round(durationMs)}ms)`);
this.onDigit?.({
digit,
durationMs,
source: 'rfc2833',
timestamp: Date.now(),
});
}
}
/** Report a pending (unreported) event — called by safety timer or on new event start. */
private reportPendingEvent(): void {
if (
this.currentEventId !== null &&
!this.currentEventReported &&
this.currentEventId < EVENT_CHARS.length
) {
this.currentEventReported = true;
this.clearSafetyTimer();
const digit = EVENT_CHARS[this.currentEventId];
const durationMs = (this.currentEventDuration / this.clockRate) * 1000;
this.log(`[dtmf] RFC 2833 digit '${digit}' (${Math.round(durationMs)}ms, safety timeout)`);
this.onDigit?.({
digit,
durationMs,
source: 'rfc2833',
timestamp: Date.now(),
});
}
}
private clearSafetyTimer(): void {
if (this.safetyTimer) {
clearTimeout(this.safetyTimer);
this.safetyTimer = null;
}
}
// -------------------------------------------------------------------------
// SIP INFO processing
// -------------------------------------------------------------------------
/**
* Parse a SIP INFO message carrying DTMF.
* Supports Content-Type: application/dtmf-relay (Signal=X / Duration=Y).
*/
processSipInfo(msg: SipMessage): void {
const ct = (msg.getHeader('Content-Type') || '').toLowerCase();
if (!ct.includes('application/dtmf-relay') && !ct.includes('application/dtmf')) return;
const body = msg.body || '';
if (ct.includes('application/dtmf-relay')) {
// Format: "Signal= 5\r\nDuration= 160\r\n"
const signalMatch = body.match(/Signal\s*=\s*(\S+)/i);
const durationMatch = body.match(/Duration\s*=\s*(\d+)/i);
if (!signalMatch) return;
const signal = signalMatch[1];
const durationTicks = durationMatch ? parseInt(durationMatch[1], 10) : 160;
// Validate digit.
if (signal.length !== 1 || !/[0-9*#A-Da-d]/.test(signal)) return;
const digit = signal.toUpperCase();
const durationMs = (durationTicks / this.clockRate) * 1000;
this.log(`[dtmf] SIP INFO digit '${digit}' (${Math.round(durationMs)}ms)`);
this.onDigit?.({
digit,
durationMs,
source: 'sip-info',
timestamp: Date.now(),
});
} else if (ct.includes('application/dtmf')) {
// Simple format: just the digit character in the body.
const digit = body.trim().toUpperCase();
if (digit.length !== 1 || !/[0-9*#A-D]/.test(digit)) return;
this.log(`[dtmf] SIP INFO digit '${digit}' (application/dtmf)`);
this.onDigit?.({
digit,
durationMs: 250, // default duration
source: 'sip-info',
timestamp: Date.now(),
});
}
}
// -------------------------------------------------------------------------
// Lifecycle
// -------------------------------------------------------------------------
/** Reset detection state (e.g., between calls). */
reset(): void {
this.currentEventId = null;
this.currentEventTs = null;
this.currentEventReported = false;
this.currentEventDuration = 0;
this.currentEventVolume = 0;
this.clearSafetyTimer();
}
/** Clean up timers and references. */
destroy(): void {
this.clearSafetyTimer();
this.onDigit = null;
}
}

404
ts/call/prompt-cache.ts Normal file
View File

@@ -0,0 +1,404 @@
/**
* PromptCache — manages multiple named audio prompts for IVR and voicemail.
*
* Each prompt is pre-encoded as both G.722 frames (for SIP legs) and Opus
* frames (for WebRTC legs), ready for 20ms RTP playback.
*
* Supports three sources:
* 1. TTS generation via espeak-ng (primary) or Kokoro (fallback)
* 2. Loading from a pre-existing WAV file
* 3. Programmatic tone generation (beep, etc.)
*
* The existing announcement.ts system continues to work independently;
* this module provides generalized prompt management for IVR/voicemail.
*/
import { execSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import { Buffer } from 'node:buffer';
import { buildRtpHeader, rtpClockIncrement } from './leg.ts';
import { encodePcm, isCodecReady } from '../opusbridge.ts';
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
/** A pre-encoded prompt ready for RTP playback. */
export interface ICachedPrompt {
/** Unique prompt identifier. */
id: string;
/** G.722 encoded frames (20ms each, no RTP header). */
g722Frames: Buffer[];
/** Opus encoded frames (20ms each, no RTP header). */
opusFrames: Buffer[];
/** Total duration in milliseconds. */
durationMs: number;
}
// ---------------------------------------------------------------------------
// TTS helpers
// ---------------------------------------------------------------------------
const TTS_DIR = path.join(process.cwd(), '.nogit', 'tts');
/** Check if espeak-ng is available. */
function isEspeakAvailable(): boolean {
try {
execSync('which espeak-ng', { stdio: 'pipe' });
return true;
} catch {
return false;
}
}
/** Generate WAV via espeak-ng. */
function generateViaEspeak(wavPath: string, text: string): boolean {
try {
execSync(
`espeak-ng -v en-us -s 150 -w "${wavPath}" "${text}"`,
{ timeout: 10000, stdio: 'pipe' },
);
return true;
} catch {
return false;
}
}
/** Generate WAV via Kokoro TTS. */
function generateViaKokoro(wavPath: string, text: string, voice: string): boolean {
const modelPath = path.join(TTS_DIR, 'kokoro-v1.0.onnx');
const voicesPath = path.join(TTS_DIR, 'voices.bin');
if (!fs.existsSync(modelPath) || !fs.existsSync(voicesPath)) return false;
const root = process.cwd();
const ttsBin = [
path.join(root, 'dist_rust', 'tts-engine'),
path.join(root, 'rust', 'target', 'release', 'tts-engine'),
path.join(root, 'rust', 'target', 'debug', 'tts-engine'),
].find((p) => fs.existsSync(p));
if (!ttsBin) return false;
try {
execSync(
`"${ttsBin}" --model "${modelPath}" --voices "${voicesPath}" --voice "${voice}" --output "${wavPath}" --text "${text}"`,
{ timeout: 120000, stdio: 'pipe' },
);
return true;
} catch {
return false;
}
}
/** Read a WAV file and return raw PCM + sample rate. */
function readWavWithRate(wavPath: string): { pcm: Buffer; sampleRate: number } | null {
const wav = fs.readFileSync(wavPath);
if (wav.length < 44) return null;
if (wav.toString('ascii', 0, 4) !== 'RIFF') return null;
if (wav.toString('ascii', 8, 12) !== 'WAVE') return null;
let sampleRate = 22050;
let pcm: Buffer | null = null;
let offset = 12;
while (offset < wav.length - 8) {
const chunkId = wav.toString('ascii', offset, offset + 4);
const chunkSize = wav.readUInt32LE(offset + 4);
if (chunkId === 'fmt ') {
sampleRate = wav.readUInt32LE(offset + 12);
}
if (chunkId === 'data') {
pcm = wav.subarray(offset + 8, offset + 8 + chunkSize);
}
offset += 8 + chunkSize;
if (offset % 2 !== 0) offset++;
}
return pcm ? { pcm, sampleRate } : null;
}
/** Encode raw PCM frames to G.722 + Opus. */
async function encodePcmFrames(
pcm: Buffer,
sampleRate: number,
log: (msg: string) => void,
): Promise<{ g722Frames: Buffer[]; opusFrames: Buffer[] } | null> {
if (!isCodecReady()) return null;
const frameSamples = Math.floor(sampleRate * 0.02); // 20ms
const frameBytes = frameSamples * 2; // 16-bit
const totalFrames = Math.floor(pcm.length / frameBytes);
const g722Frames: Buffer[] = [];
const opusFrames: Buffer[] = [];
for (let i = 0; i < totalFrames; i++) {
const framePcm = Buffer.from(pcm.subarray(i * frameBytes, (i + 1) * frameBytes));
const [g722, opus] = await Promise.all([
encodePcm(framePcm, sampleRate, 9), // G.722
encodePcm(framePcm, sampleRate, 111), // Opus
]);
if (g722) g722Frames.push(g722);
if (opus) opusFrames.push(opus);
}
return { g722Frames, opusFrames };
}
// ---------------------------------------------------------------------------
// PromptCache
// ---------------------------------------------------------------------------
export class PromptCache {
private prompts = new Map<string, ICachedPrompt>();
private log: (msg: string) => void;
private espeakAvailable: boolean | null = null;
constructor(log: (msg: string) => void) {
this.log = log;
}
// -------------------------------------------------------------------------
// Public API
// -------------------------------------------------------------------------
/** Get a cached prompt by ID. */
get(id: string): ICachedPrompt | null {
return this.prompts.get(id) ?? null;
}
/** Check if a prompt is cached. */
has(id: string): boolean {
return this.prompts.has(id);
}
/** List all cached prompt IDs. */
listIds(): string[] {
return [...this.prompts.keys()];
}
/**
* Generate a TTS prompt and cache it.
* Uses espeak-ng (primary) or Kokoro (fallback).
*/
async generatePrompt(id: string, text: string, voice = 'af_bella'): Promise<ICachedPrompt | null> {
fs.mkdirSync(TTS_DIR, { recursive: true });
const wavPath = path.join(TTS_DIR, `prompt-${id}.wav`);
// Check espeak availability once.
if (this.espeakAvailable === null) {
this.espeakAvailable = isEspeakAvailable();
}
// Generate WAV.
let generated = false;
if (!fs.existsSync(wavPath)) {
if (this.espeakAvailable) {
generated = generateViaEspeak(wavPath, text);
}
if (!generated) {
generated = generateViaKokoro(wavPath, text, voice);
}
if (!generated) {
this.log(`[prompt-cache] failed to generate TTS for "${id}"`);
return null;
}
this.log(`[prompt-cache] generated WAV for "${id}"`);
}
return this.loadWavPrompt(id, wavPath);
}
/**
* Load a WAV file as a prompt and cache it.
*/
async loadWavPrompt(id: string, wavPath: string): Promise<ICachedPrompt | null> {
if (!fs.existsSync(wavPath)) {
this.log(`[prompt-cache] WAV not found: ${wavPath}`);
return null;
}
const result = readWavWithRate(wavPath);
if (!result) {
this.log(`[prompt-cache] failed to parse WAV: ${wavPath}`);
return null;
}
const encoded = await encodePcmFrames(result.pcm, result.sampleRate, this.log);
if (!encoded) {
this.log(`[prompt-cache] encoding failed for "${id}" (codec bridge not ready?)`);
return null;
}
const durationMs = encoded.g722Frames.length * 20;
const prompt: ICachedPrompt = {
id,
g722Frames: encoded.g722Frames,
opusFrames: encoded.opusFrames,
durationMs,
};
this.prompts.set(id, prompt);
this.log(`[prompt-cache] cached "${id}": ${encoded.g722Frames.length} frames (${(durationMs / 1000).toFixed(1)}s)`);
return prompt;
}
/**
* Generate a beep tone prompt (sine wave).
* @param id - prompt ID
* @param freqHz - tone frequency (default 1000 Hz)
* @param durationMs - tone duration (default 500ms)
* @param amplitude - 16-bit amplitude (default 8000)
*/
async generateBeep(
id: string,
freqHz = 1000,
durationMs = 500,
amplitude = 8000,
): Promise<ICachedPrompt | null> {
// Generate at 16kHz for decent quality.
const sampleRate = 16000;
const totalSamples = Math.floor((sampleRate * durationMs) / 1000);
const pcm = Buffer.alloc(totalSamples * 2);
for (let i = 0; i < totalSamples; i++) {
const t = i / sampleRate;
// Apply a short fade-in/fade-out to avoid click artifacts.
const fadeLen = Math.floor(sampleRate * 0.01); // 10ms fade
let envelope = 1.0;
if (i < fadeLen) envelope = i / fadeLen;
else if (i > totalSamples - fadeLen) envelope = (totalSamples - i) / fadeLen;
const sample = Math.round(Math.sin(2 * Math.PI * freqHz * t) * amplitude * envelope);
pcm.writeInt16LE(Math.max(-32768, Math.min(32767, sample)), i * 2);
}
const encoded = await encodePcmFrames(pcm, sampleRate, this.log);
if (!encoded) {
this.log(`[prompt-cache] beep encoding failed for "${id}"`);
return null;
}
const actualDuration = encoded.g722Frames.length * 20;
const prompt: ICachedPrompt = {
id,
g722Frames: encoded.g722Frames,
opusFrames: encoded.opusFrames,
durationMs: actualDuration,
};
this.prompts.set(id, prompt);
this.log(`[prompt-cache] beep "${id}" cached: ${actualDuration}ms @ ${freqHz}Hz`);
return prompt;
}
/**
* Remove a prompt from the cache.
*/
remove(id: string): void {
this.prompts.delete(id);
}
/**
* Clear all cached prompts.
*/
clear(): void {
this.prompts.clear();
}
}
// ---------------------------------------------------------------------------
// Standalone playback helpers (for use by SystemLeg)
// ---------------------------------------------------------------------------
/**
* Play a cached prompt's G.722 frames as RTP packets at 20ms intervals.
*
* @param prompt - the cached prompt to play
* @param sendPacket - function to send a raw RTP packet (12-byte header + payload)
* @param ssrc - SSRC for RTP headers
* @param onDone - called when playback finishes
* @returns cancel function, or null if prompt has no G.722 frames
*/
export function playPromptG722(
prompt: ICachedPrompt,
sendPacket: (pkt: Buffer) => void,
ssrc: number,
onDone?: () => void,
): (() => void) | null {
if (prompt.g722Frames.length === 0) {
onDone?.();
return null;
}
const frames = prompt.g722Frames;
const PT = 9;
let frameIdx = 0;
let seq = Math.floor(Math.random() * 0xffff);
let rtpTs = Math.floor(Math.random() * 0xffffffff);
const timer = setInterval(() => {
if (frameIdx >= frames.length) {
clearInterval(timer);
onDone?.();
return;
}
const payload = frames[frameIdx];
const hdr = buildRtpHeader(PT, seq & 0xffff, rtpTs >>> 0, ssrc >>> 0, frameIdx === 0);
const pkt = Buffer.concat([hdr, payload]);
sendPacket(pkt);
seq++;
rtpTs += rtpClockIncrement(PT);
frameIdx++;
}, 20);
return () => clearInterval(timer);
}
/**
* Play a cached prompt's Opus frames as RTP packets at 20ms intervals.
*
* @param prompt - the cached prompt to play
* @param sendPacket - function to send a raw RTP packet
* @param ssrc - SSRC for RTP headers
* @param counters - shared seq/ts counters (mutated in place for seamless transitions)
* @param onDone - called when playback finishes
* @returns cancel function, or null if prompt has no Opus frames
*/
export function playPromptOpus(
prompt: ICachedPrompt,
sendPacket: (pkt: Buffer) => void,
ssrc: number,
counters: { seq: number; ts: number },
onDone?: () => void,
): (() => void) | null {
if (prompt.opusFrames.length === 0) {
onDone?.();
return null;
}
const frames = prompt.opusFrames;
const PT = 111;
let frameIdx = 0;
const timer = setInterval(() => {
if (frameIdx >= frames.length) {
clearInterval(timer);
onDone?.();
return;
}
const payload = frames[frameIdx];
const hdr = buildRtpHeader(PT, counters.seq & 0xffff, counters.ts >>> 0, ssrc >>> 0, frameIdx === 0);
const pkt = Buffer.concat([hdr, payload]);
sendPacket(pkt);
counters.seq++;
counters.ts += 960; // Opus 48kHz: 960 samples per 20ms
frameIdx++;
}, 20);
return () => clearInterval(timer);
}

13
ts/call/sip-leg.ts
View File

@@ -122,6 +122,9 @@ export class SipLeg implements ILeg {
onConnected: ((leg: SipLeg) => void) | null = null;
onTerminated: ((leg: SipLeg) => void) | null = null;
/** Callback for SIP INFO messages (used for DTMF relay). */
onInfoReceived: ((msg: SipMessage) => void) | null = null;
constructor(id: string, config: ISipLegConfig) {
this.id = id;
this.type = config.role === 'device' ? 'sip-device' : 'sip-provider';
@@ -464,7 +467,15 @@ export class SipLeg implements ILeg {
this.onTerminated?.(this);
this.onStateChange?.(this);
}
// Other in-dialog requests (re-INVITE, INFO, etc.) can be handled here in the future.
if (method === 'INFO') {
// Respond 200 OK to the INFO request.
const ok = SipMessage.createResponse(200, 'OK', msg);
this.config.sendSip(ok.serialize(), { address: rinfo.address, port: rinfo.port });
// Forward to DTMF handler (if attached).
this.onInfoReceived?.(msg);
}
// Other in-dialog requests (re-INVITE, etc.) can be handled here in the future.
}
// -------------------------------------------------------------------------

336
ts/call/system-leg.ts Normal file
View File

@@ -0,0 +1,336 @@
/**
* SystemLeg — virtual ILeg for IVR menus and voicemail.
*
* Plugs into the Call hub exactly like SipLeg or WebRtcLeg:
* - Receives caller audio via sendRtp() (called by Call.forwardRtp)
* - Plays prompts by firing onRtpReceived (picked up by Call.forwardRtp → caller's leg)
* - Detects DTMF from caller's audio (RFC 2833 telephone-event)
* - Records caller's audio to WAV files (for voicemail)
*
* No UDP socket or SIP dialog needed — purely virtual.
*/
import { Buffer } from 'node:buffer';
import type dgram from 'node:dgram';
import type { IEndpoint } from '../sip/index.ts';
import type { SipMessage } from '../sip/index.ts';
import type { SipDialog } from '../sip/index.ts';
import type { IRtpTranscoder } from '../codec.ts';
import type { ILeg } from './leg.ts';
import type { TLegState, TLegType, ILegStatus } from './types.ts';
import { DtmfDetector } from './dtmf-detector.ts';
import type { IDtmfDigit } from './dtmf-detector.ts';
import { AudioRecorder } from './audio-recorder.ts';
import type { IRecordingResult } from './audio-recorder.ts';
import { PromptCache, playPromptG722, playPromptOpus } from './prompt-cache.ts';
import type { ICachedPrompt } from './prompt-cache.ts';
import { buildRtpHeader, rtpClockIncrement } from './leg.ts';
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
export type TSystemLegMode = 'ivr' | 'voicemail-greeting' | 'voicemail-recording' | 'idle';
export interface ISystemLegConfig {
/** Logging function. */
log: (msg: string) => void;
/** The prompt cache for TTS playback. */
promptCache: PromptCache;
/**
* Codec payload type used by the caller's leg.
* Determines whether G.722 (9) or Opus (111) frames are played.
* Default: 9 (G.722, typical for SIP callers).
*/
callerCodecPt?: number;
/** Called when a DTMF digit is detected. */
onDtmfDigit?: (digit: IDtmfDigit) => void;
/** Called when a voicemail recording is complete. */
onRecordingComplete?: (result: IRecordingResult) => void;
/** Called when the SystemLeg wants to signal an IVR action. */
onAction?: (action: string, data?: any) => void;
}
// ---------------------------------------------------------------------------
// SystemLeg
// ---------------------------------------------------------------------------
export class SystemLeg implements ILeg {
readonly id: string;
readonly type: TLegType = 'system';
state: TLegState = 'connected'; // Immediately "connected" — no setup phase.
/** Current operating mode. */
mode: TSystemLegMode = 'idle';
// --- ILeg required fields (virtual — no real network resources) ---
readonly sipCallId: string;
readonly rtpPort: number | null = null;
readonly rtpSock: dgram.Socket | null = null;
remoteMedia: IEndpoint | null = null;
codec: number | null = null;
transcoder: IRtpTranscoder | null = null;
pktSent = 0;
pktReceived = 0;
readonly dialog: SipDialog | null = null;
/**
* Set by Call.addLeg() — firing this injects audio into the Call hub,
* which forwards it to the caller's leg.
*/
onRtpReceived: ((data: Buffer) => void) | null = null;
// --- Internal components ---
private dtmfDetector: DtmfDetector;
private recorder: AudioRecorder | null = null;
private promptCache: PromptCache;
private promptCancel: (() => void) | null = null;
private callerCodecPt: number;
private log: (msg: string) => void;
readonly config: ISystemLegConfig;
/** Stable SSRC for all prompt playback (random, stays constant for the leg's lifetime). */
private ssrc: number;
/** Sequence/timestamp counters for Opus prompt playback (shared for seamless transitions). */
private opusCounters = { seq: 0, ts: 0 };
constructor(id: string, config: ISystemLegConfig) {
this.id = id;
this.sipCallId = `system-${id}`; // Virtual Call-ID — not a real SIP dialog.
this.config = config;
this.log = config.log;
this.promptCache = config.promptCache;
this.callerCodecPt = config.callerCodecPt ?? 9; // Default G.722
this.ssrc = (Math.random() * 0xffffffff) >>> 0;
this.opusCounters.seq = Math.floor(Math.random() * 0xffff);
this.opusCounters.ts = Math.floor(Math.random() * 0xffffffff);
// Initialize DTMF detector.
this.dtmfDetector = new DtmfDetector(this.log);
this.dtmfDetector.onDigit = (digit) => {
this.log(`[system-leg:${this.id}] DTMF '${digit.digit}' (${digit.source})`);
this.config.onDtmfDigit?.(digit);
};
}
// -------------------------------------------------------------------------
// ILeg: sendRtp — receives caller's audio from the Call hub
// -------------------------------------------------------------------------
/**
* Called by the Call hub (via forwardRtp) to deliver the caller's audio
* to this leg. We use this for DTMF detection and recording.
*/
sendRtp(data: Buffer): void {
this.pktReceived++;
// Feed DTMF detector (it checks PT internally, ignores non-101 packets).
this.dtmfDetector.processRtp(data);
// Feed recorder if active.
if (this.mode === 'voicemail-recording' && this.recorder) {
this.recorder.processRtp(data);
}
}
// -------------------------------------------------------------------------
// ILeg: handleSipMessage — handles SIP INFO for DTMF
// -------------------------------------------------------------------------
/**
* Handle a SIP message routed to this leg. Only SIP INFO (DTMF) is relevant.
*/
handleSipMessage(msg: SipMessage, _rinfo: IEndpoint): void {
if (msg.method === 'INFO') {
this.dtmfDetector.processSipInfo(msg);
}
}
// -------------------------------------------------------------------------
// Prompt playback
// -------------------------------------------------------------------------
/**
* Play a cached prompt by ID.
* The audio is injected into the Call hub via onRtpReceived.
*
* @param promptId - ID of the prompt in the PromptCache
* @param onDone - called when playback completes (not on cancel)
* @returns true if playback started, false if prompt not found
*/
playPrompt(promptId: string, onDone?: () => void): boolean {
const prompt = this.promptCache.get(promptId);
if (!prompt) {
this.log(`[system-leg:${this.id}] prompt "${promptId}" not found`);
onDone?.();
return false;
}
// Cancel any in-progress playback.
this.cancelPrompt();
this.log(`[system-leg:${this.id}] playing prompt "${promptId}" (${prompt.durationMs}ms)`);
// Select G.722 or Opus frames based on caller codec.
if (this.callerCodecPt === 111) {
// WebRTC caller: play Opus frames.
this.promptCancel = playPromptOpus(
prompt,
(pkt) => this.injectPacket(pkt),
this.ssrc,
this.opusCounters,
() => {
this.promptCancel = null;
onDone?.();
},
);
} else {
// SIP caller: play G.722 frames (works for all SIP codecs since the
// SipLeg's RTP socket sends whatever we give it — the provider's
// media endpoint accepts the codec negotiated in the SDP).
this.promptCancel = playPromptG722(
prompt,
(pkt) => this.injectPacket(pkt),
this.ssrc,
() => {
this.promptCancel = null;
onDone?.();
},
);
}
return this.promptCancel !== null;
}
/**
* Play a sequence of prompts, one after another.
*/
playPromptSequence(promptIds: string[], onDone?: () => void): void {
let index = 0;
const playNext = () => {
if (index >= promptIds.length) {
onDone?.();
return;
}
const id = promptIds[index++];
if (!this.playPrompt(id, playNext)) {
// Prompt not found — skip and play next.
playNext();
}
};
playNext();
}
/** Cancel any in-progress prompt playback. */
cancelPrompt(): void {
if (this.promptCancel) {
this.promptCancel();
this.promptCancel = null;
}
}
/** Whether a prompt is currently playing. */
get isPlaying(): boolean {
return this.promptCancel !== null;
}
/**
* Inject an RTP packet into the Call hub.
* This simulates "receiving" audio on this leg — the hub
* will forward it to the caller's leg.
*/
private injectPacket(pkt: Buffer): void {
this.pktSent++;
this.onRtpReceived?.(pkt);
}
// -------------------------------------------------------------------------
// Recording
// -------------------------------------------------------------------------
/**
* Start recording the caller's audio.
* @param outputDir - directory to write the WAV file
* @param fileId - unique ID for the file name
*/
async startRecording(outputDir: string, fileId?: string): Promise<void> {
if (this.recorder) {
await this.recorder.stop();
}
this.recorder = new AudioRecorder({
outputDir,
log: this.log,
maxDurationSec: 120,
silenceTimeoutSec: 5,
});
this.recorder.onStopped = (result) => {
this.log(`[system-leg:${this.id}] recording auto-stopped (${result.stopReason})`);
this.config.onRecordingComplete?.(result);
};
this.mode = 'voicemail-recording';
await this.recorder.start(fileId);
}
/**
* Stop recording and finalize the WAV file.
*/
async stopRecording(): Promise<IRecordingResult | null> {
if (!this.recorder) return null;
const result = await this.recorder.stop();
this.recorder = null;
return result;
}
/** Cancel recording — stops and deletes the file. */
async cancelRecording(): Promise<void> {
if (this.recorder) {
await this.recorder.cancel();
this.recorder = null;
}
}
// -------------------------------------------------------------------------
// Lifecycle
// -------------------------------------------------------------------------
/** Release all resources. */
teardown(): void {
this.cancelPrompt();
// Stop recording gracefully.
if (this.recorder && this.recorder.state === 'recording') {
this.recorder.stop().then((result) => {
this.config.onRecordingComplete?.(result);
});
this.recorder = null;
}
this.dtmfDetector.destroy();
this.state = 'terminated';
this.mode = 'idle';
this.onRtpReceived = null;
this.log(`[system-leg:${this.id}] torn down`);
}
/** Status snapshot for the dashboard. */
getStatus(): ILegStatus {
return {
id: this.id,
type: this.type,
state: this.state,
remoteMedia: null,
rtpPort: null,
pktSent: this.pktSent,
pktReceived: this.pktReceived,
codec: this.callerCodecPt === 111 ? 'Opus' : 'G.722',
transcoding: false,
};
}
}

4
ts/call/types.ts
View File

@@ -13,6 +13,8 @@ export type TCallState =
| 'ringing'
| 'connected'
| 'on-hold'
| 'voicemail'
| 'ivr'
| 'transferring'
| 'terminating'
| 'terminated';
@@ -25,7 +27,7 @@ export type TLegState =
| 'terminating'
| 'terminated';
export type TLegType = 'sip-device' | 'sip-provider' | 'webrtc';
export type TLegType = 'sip-device' | 'sip-provider' | 'webrtc' | 'system';
export type TCallDirection = 'inbound' | 'outbound' | 'internal';

163
ts/call/wav-writer.ts Normal file
View File

@@ -0,0 +1,163 @@
/**
* Streaming WAV file writer — opens a file, writes a placeholder header,
* appends raw PCM data in chunks, and finalizes (patches sizes) on close.
*
* Produces standard RIFF/WAVE format compatible with the WAV parser
* in announcement.ts (extractPcmFromWav).
*/
import fs from 'node:fs';
import { Buffer } from 'node:buffer';
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
export interface IWavWriterOptions {
/** Full path to the output WAV file. */
filePath: string;
/** Sample rate in Hz (e.g. 16000). */
sampleRate: number;
/** Number of channels (default 1 = mono). */
channels?: number;
/** Bits per sample (default 16). */
bitsPerSample?: number;
}
export interface IWavWriterResult {
/** Full path to the WAV file. */
filePath: string;
/** Total duration in milliseconds. */
durationMs: number;
/** Sample rate of the output file. */
sampleRate: number;
/** Total number of audio samples written. */
totalSamples: number;
/** File size in bytes. */
fileSize: number;
}
// ---------------------------------------------------------------------------
// WAV header constants
// ---------------------------------------------------------------------------
/** Standard WAV header size: RIFF(12) + fmt(24) + data-header(8) = 44 bytes. */
const HEADER_SIZE = 44;
// ---------------------------------------------------------------------------
// WavWriter
// ---------------------------------------------------------------------------
export class WavWriter {
private fd: number | null = null;
private totalDataBytes = 0;
private closed = false;
private filePath: string;
private sampleRate: number;
private channels: number;
private bitsPerSample: number;
constructor(options: IWavWriterOptions) {
this.filePath = options.filePath;
this.sampleRate = options.sampleRate;
this.channels = options.channels ?? 1;
this.bitsPerSample = options.bitsPerSample ?? 16;
}
/** Open the file and write a placeholder 44-byte WAV header. */
open(): void {
if (this.fd !== null) throw new Error('WavWriter already open');
this.fd = fs.openSync(this.filePath, 'w');
this.totalDataBytes = 0;
this.closed = false;
// Write 44 bytes of zeros as placeholder — patched in close().
const placeholder = Buffer.alloc(HEADER_SIZE);
fs.writeSync(this.fd, placeholder, 0, HEADER_SIZE, 0);
}
/** Append raw 16-bit little-endian PCM samples. */
write(pcm: Buffer): void {
if (this.fd === null || this.closed) return;
if (pcm.length === 0) return;
fs.writeSync(this.fd, pcm, 0, pcm.length);
this.totalDataBytes += pcm.length;
}
/**
* Finalize: rewrite the RIFF and data chunk sizes in the header, close the file.
* Returns metadata about the written WAV.
*/
close(): IWavWriterResult {
if (this.fd === null || this.closed) {
return {
filePath: this.filePath,
durationMs: 0,
sampleRate: this.sampleRate,
totalSamples: 0,
fileSize: HEADER_SIZE,
};
}
this.closed = true;
const blockAlign = this.channels * (this.bitsPerSample / 8);
const byteRate = this.sampleRate * blockAlign;
const fileSize = HEADER_SIZE + this.totalDataBytes;
// Build the complete 44-byte header.
const hdr = Buffer.alloc(HEADER_SIZE);
let offset = 0;
// RIFF chunk descriptor.
hdr.write('RIFF', offset); offset += 4;
hdr.writeUInt32LE(fileSize - 8, offset); offset += 4; // ChunkSize = fileSize - 8
hdr.write('WAVE', offset); offset += 4;
// fmt sub-chunk.
hdr.write('fmt ', offset); offset += 4;
hdr.writeUInt32LE(16, offset); offset += 4; // Subchunk1Size (PCM = 16)
hdr.writeUInt16LE(1, offset); offset += 2; // AudioFormat (1 = PCM)
hdr.writeUInt16LE(this.channels, offset); offset += 2;
hdr.writeUInt32LE(this.sampleRate, offset); offset += 4;
hdr.writeUInt32LE(byteRate, offset); offset += 4;
hdr.writeUInt16LE(blockAlign, offset); offset += 2;
hdr.writeUInt16LE(this.bitsPerSample, offset); offset += 2;
// data sub-chunk.
hdr.write('data', offset); offset += 4;
hdr.writeUInt32LE(this.totalDataBytes, offset); offset += 4;
// Patch the header at the beginning of the file.
fs.writeSync(this.fd, hdr, 0, HEADER_SIZE, 0);
fs.closeSync(this.fd);
this.fd = null;
const bytesPerSample = this.bitsPerSample / 8;
const totalSamples = Math.floor(this.totalDataBytes / (bytesPerSample * this.channels));
const durationMs = (totalSamples / this.sampleRate) * 1000;
return {
filePath: this.filePath,
durationMs: Math.round(durationMs),
sampleRate: this.sampleRate,
totalSamples,
fileSize,
};
}
/** Current recording duration in milliseconds. */
get durationMs(): number {
const bytesPerSample = this.bitsPerSample / 8;
const totalSamples = Math.floor(this.totalDataBytes / (bytesPerSample * this.channels));
return (totalSamples / this.sampleRate) * 1000;
}
/** Whether the writer is still open and accepting data. */
get isOpen(): boolean {
return this.fd !== null && !this.closed;
}
}