pjsip DTMF信号发送与接收：功能实现完整示例

pjsip 中的 DTMF 信号：从原理到实战的完整实现指南

你有没有遇到过这样的场景？用户正在通过 VoIP 客户端拨打银行客服，输入密码时系统却“听不清”按键音；或者在远程控制门禁系统时，明明按了#，对方却毫无反应。问题很可能出在DTMF 传输机制上。

在 SIP 软终端开发中，DTMF（双音多频）看似简单，实则暗藏玄机。尤其是在使用像pjsip这类底层通信库时，若不了解其内部机制，很容易掉进“发得出、收不到”或“识别错乱”的坑里。

本文不讲空泛理论，而是带你一步步打通 pjsip 中 DTMF 的发送与接收全流程——从协议选择、媒体协商，到代码实现和调试技巧，全部基于真实可用的工程实践展开。

DTMF 在 VoIP 中的三种传输方式，为什么 RFC2833 是首选？

先搞清楚一件事：DTMF 并不是简单地把“嘀”一声录下来发过去就行。VoIP 环境下有三种主流方式来传递按键信息：

1. In-band audio（带内音频）
   把 DTMF 音调当作普通语音编码（如 G.711）发送。听起来最直观，但实际问题很多：编码压缩会失真、背景噪声干扰、VAD（语音活动检测）可能直接过滤掉短促的按键音。

2. SIP INFO method（信令方式）
   每次按键都发起一个INFO请求，携带 DTMF 字符。优点是逻辑清晰，缺点也很明显：依赖 SIP 事务完成，延迟高，网络差时容易丢包重传失败。

3. RFC2833 / RFC4733（RTP 事件载荷）
   使用专用 RTP 载荷类型（payload type）发送结构化事件包。每个按键被拆分为start、continue、end多个 RTP 包，独立于语音流传输。

✅pjsip 默认优先使用 RFC2833，正是因为它具备低延迟、抗丢包、不受编解码影响等优势，成为工业级系统的首选方案。

发送 DTMF：不只是调个 API 那么简单

我们来看一段常见的发送代码：

pj_status_t send_dtmf(pjsua_call_id call_id, char digit) { pj_str_t dtmf_str; dtmf_str.ptr = &digit; dtmf_str.slen = 1; return pjsua_call_dial_dtmf(call_id, &dtmf_str); }

表面看只是封装了一个 API 调用，但背后发生了什么？

当你按下“1”，pjsip 做了哪些事？

1. 检查当前通话是否有活跃的媒体流；
2. 查询 SDP 协商结果中是否包含telephone-event载荷支持；
3. 若支持，则查找对应的 payload type（通常是 101）；
4. 构造符合 RFC2833 标准的 RTP 包：
   - Event Code:'1'→ 编号 1
   - End Flag: 初始为 0，持续约 100ms 后置 1
   - Volume: -35dBm（ITU-T Q.23 规定）
   - Duration: 按 8kHz 采样率计算时间戳增量

这些数据不会走语音编码器，而是直接注入 RTP 发送队列，确保即使在静音期间也能准确送达。

批量发送注意事项：别让按键“粘连”

很多开发者习惯这样写：

send_dtmf_sequence(call_id, "1234");

但如果中间没有延时，远端可能会收到"12"被识别成一个操作。正确的做法是模拟真实拨号节奏：

pj_status_t send_dtmf_sequence(pjsua_call_id call_id, const char *digits) { int len = strlen(digits); for (int i = 0; i < len; ++i) { pj_thread_sleep(200); // 至少 200ms 间隔 pj_status_t status = send_dtmf(call_id, digits[i]); if (status != PJ_SUCCESS) { PJ_LOG(1, ("DTMF", "Failed to send digit %c", digits[i])); return status; } } return PJ_SUCCESS; }

这个小小的sleep很关键——它避免了事件重叠，也给了对端处理时间。

接收 DTMF：如何确保每一个按键都不丢失？

发送解决了“我能发”，接收才是“你能听清”的关键。

回调函数注册：事件驱动的核心入口

pjsip 提供了标准回调接口，用于通知应用层收到 DTMF：

static void on_dtmf_digit(pjsua_call_id call_id, int digit) { char d = (char)digit; PJ_LOG(3, ("DTMF_RX", "Received DTMF digit: %c from call %d", d, call_id)); switch(d) { case '1': play_welcome_message(); break; case '*': enter_menu_mode(); break; default: break; } }

这个函数会在一个完整的 DTMF 事件结束后被触发（即收到end=1的包），保证不会误报中途状态。

初始化时别忘了注册回调！

void initialize_pjsua() { pjsua_config cfg; pjsua_logging_config log_cfg; pjsua_config_default(&cfg); pjsua_logging_config_default(&log_cfg); cfg.cb.on_dtmf_digit = &on_dtmf_digit; // 关键！必须设置 pjsua_init(&cfg, &log_cfg, NULL); // ... 其他初始化 }

如果你发现发出去的 DTMF 对方收不到日志，第一反应应该是检查这个回调是否注册成功。

SDP 协商细节决定成败：让对端知道你能听懂“事件语言”

再强大的功能，如果双方“说的不是一种话”，也无法通信。

RFC2833 能否启用，取决于 SDP 协商过程中是否声明了对telephone-event的支持。典型的 SDP 片段如下：

a=rtpmap:101 telephone-event/8000 a=fmtp:101 0-15

其中：
-101是动态分配的 payload type；
-telephone-event/8000表示这是运行在 8kHz 采样率下的事件流；
-0-15表示支持所有标准 DTMF 字符（0~9, *, #, A~D）

🔍pjsip 默认自动添加这些字段，前提是你要在创建媒体流时正确配置。

如何确认协商成功？

抓包工具 Wireshark 是你的最佳伙伴。过滤 RTP 流后，查看是否有 payload type 为 101 的包，并观察其格式是否为 “Event: X”。

如果看不到这类包，说明要么本端未开启支持，要么对端拒绝使用 RFC2833。

自动降级机制：当对方不懂 RFC2833 怎么办？

现实世界很复杂，并非所有设备都支持 RFC2833。幸运的是，pjsip 内建了智能降级策略：

1. 首选尝试 RFC2833 发送；
2. 如果 SDP 协商中未发现telephone-event支持；
3. 则退而求其次，改用SIP INFO方法发送 DTMF。

但这需要你在配置中显式启用：

pjsua_transport_config sip_cfg; pjsua_transport_config_default(&sip_cfg); sip_cfg.protocol = PJSIP_TRANSPORT_UDP; // 启用 SIP INFO 作为 fallback pjsua_var.ua_cfg.use_info_in_dtmf = PJ_TRUE;

否则，一旦 RFC2833 不可用，DTMF 就彻底失效。

实战避坑指南：那些文档没写的“潜规则”

❌ 坑点一：误启 In-band DTMF 检测导致误识别

有些开发者为了“保险起见”，同时开启 in-band 音频检测，结果导致语音中的类似频率被误判为按键。

✅ 正确做法是在创建音频流时明确关闭：

pjmedia_audio_stream_info aud_info; pjmedia_audio_stream_info_default(&aud_info); aud_info.param.enc_fmt_id = PJMEDIA_FORMAT_AUDIO; // 禁用 TONE detection

只信任结构化事件，不依赖音频分析。

❌ 坑点二：忽略安全风险，明文传输敏感信息

如果你用 SIP INFO 发送银行密码，而没有启用 TLS 和 SRTP，那相当于把密码贴在网上广播。

✅ 安全建议：
- 使用sips:替代sip:；
- 启用 SRTP 加密媒体流；
- 敏感操作增加二次确认机制。

❌ 坑点三：移动端功耗异常升高

频繁发送 DTMF 可能导致录音通道反复激活，增加 CPU 占用和电量消耗。

✅ 优化思路：
- RFC2833 不经过音频采集路径，天然节能；
- 避免使用 in-band 方式；
- 控制发送频率，避免连续快速按键。

架构视角：DTMF 在 pjsip 系统中的协同流程

在一个完整的 VoIP 客户端中，DTMF 功能涉及多个模块联动：

+------------------+ +---------------------+ | Application |<----->| pjsua (SIP UA) | | (Business Logic) | | - Call Management | +------------------+ | - DTMF Input Handler| +----------+----------+ | +------------------v-------------------+ | pjsip Media Stack | | - Audio Stream | | - RTP Session | | - RFC2833 Decoder / Encoder | +------------------+--------------------+ | +---------------v------------------+ | Network Layer (UDP/SRTP) | +-----------------------------------+

• 应用层负责业务响应（如播放提示音）；
• pjsua 层统一调度 API 和回调；
• 媒体引擎处理编解码与事件打包；
• 网络层保障传输可靠性。

理解这一链条，有助于定位问题是出在“没发出去”还是“没处理好”。

结语：掌握 DTMF，你就掌握了与语音系统对话的钥匙

DTMF 看似只是几个数字键的传输，实则是连接人机交互的桥梁。无论你是开发 IVR 系统、远程控制系统，还是构建智能客服机器人，掌握 pjsip 中 DTMF 的完整实现机制，都能让你的应用更加稳定可靠。

记住几个核心要点：

• 优先使用 RFC2833，它是高效可靠的基石；
• 正确注册on_dtmf_digit回调，才能感知远端输入；
• 确保 SDP 协商包含telephone-event，否则一切归零；
• 合理配置 fallback 和安全策略，适应复杂网络环境。

下次当你看到用户顺利输入密码进入菜单时，你会知道，那一声声精准识别的背后，是你亲手搭建的通信逻辑在默默运行。

如果你在集成过程中遇到了具体问题，比如“Wireshark 看到 event 包但回调没触发”，欢迎留言讨论，我们一起排查到底。