VVOTT SIP SDK

一个基于 sip.js 的轻量级 Web SIP 通信 SDK，为现代浏览器提供完整的 VoIP 功能。

✨ 特性

• 🚀 开箱即用: 简单的 API 设计，5 分钟快速集成
• 🔧 TypeScript 支持: 完整的类型定义，优秀的开发体验
• 📱 框架无关: 零 React 依赖，支持任何前端框架
• 🔄 自动保活: 智能 WebSocket 连接保持，确保连接稳定
• 🎵 音频管理: 内置音效系统，支持自定义音频文件
• 🌐 双模支持: 支持 CommonJS 和 ES Module
• ⚙️ 动态配置: 支持运行时配置更新，无需重建实例

🎯 核心功能

• ✅ SIP 注册与认证
• ✅ 呼叫控制（呼出、接听、挂断）
• ✅ DTMF 信号发送
• ✅ 来电检测与处理
• ✅ 实时音频处理
• ✅ 静音控制
• ✅ 连接状态管理
• ✅ 早期媒体检测
• ✅ 动态配置更新

📦 安装

npm install vvott-sip-sdk@latest --legacy-peer-deps

🚀 快速开始

import { SipManager, AudioManager } from 'vvott-sip-sdk';

// 1. 创建音频元素
const audio = document.createElement('audio');
audio.autoplay = true;
document.body.appendChild(audio);

// 2. 配置 SIP 参数
const config = {
  server: 'your-sip-server.com',
  port: 5060,
  sipProtocol: 'wss',
  domain: 'your-sip-server.com',
  username: 'your-username',
  password: 'your-password'
};

// 3. 定义事件回调
const callbacks = {
  onLog: (msg) => console.log(msg),
  onConnected: () => console.log('通话已连接'),
  onDisconnected: () => console.log('通话已断开'),
  onIncomingCall: (invitation) => {
    const accept = confirm('有来电，是否接听？');
    if (accept) {
      sipManager.pickup(invitation);
    } else {
      sipManager.reject(invitation);
    }
  }
};

// 4. 创建 SIP 管理器
const sipManager = new SipManager(config, callbacks, audio, new AudioManager());

// 5. 连接并使用
async function demo() {
  // 连接到 SIP 服务器
  await sipManager.register();
  
  // 发起呼叫
  await sipManager.doCall('1234567890');
  
  // 发送 DTMF
  await sipManager.sendDTMF('1');
  
  // 挂断通话
  await sipManager.hangup();
}

📚 文档

| 文档 | 描述 | |------|------| | 🚀 快速入门 | 5分钟快速上手指南 | | 📖 完整文档 | 详细的使用说明和最佳实践 | | 📋 API参考 | 完整的API接口文档 | | 💡 示例代码 | React集成示例和代码片段 |

💻 兼容性

浏览器支持

| 浏览器 | 最低版本 | 说明 | |--------|----------|------| | Chrome | 60+ | ✅ 完全支持 | | Firefox | 55+ | ✅ 完全支持 | | Safari | 11+ | ✅ 完全支持 | | Edge | 79+ | ✅ 完全支持 |

环境要求

• 协议: 需要 HTTPS 环境（wss://）
• 权限: 需要麦克风权限（用户主动授权）
• 网络: 需要 WebSocket 连接支持

🔧 API 概览

SipManager 主要方法

// 连接管理
await sipManager.register();           // 注册到SIP服务器
await sipManager.connect();            // 仅连接（不注册）
await sipManager.unregister();         // 注销服务（保持连接）
await sipManager.disconnect();         // 断开连接

// 通话控制
await sipManager.doCall('123456');     // 发起呼叫
await sipManager.pickup(invitation);   // 接听来电
await sipManager.hangup();             // 挂断通话

// 功能控制
await sipManager.sendDTMF('1');        // 发送DTMF
await sipManager.mute(true);           // 静音控制

// 配置管理
const config = sipManager.getConfig(); // 获取当前配置
sipManager.updateConfig({              // 更新配置
  token: 'new-token',
  xtoken: 'new-xtoken'
});

// 状态查询
sipManager.getConnectionStatus();      // 获取连接状态
sipManager.getRegistrationStatus();    // 获取注册状态

事件回调

const callbacks = {
  onLog: (msg, code, category) => {},           // 日志事件
  onStatusChange: (status) => {},               // 状态变化
  onConnected: () => {},                        // 通话建立
  onDisconnected: () => {},                     // 通话结束
  onIncomingCall: (invitation) => {},           // 来电事件
  onConnectionStatusChange: (status) => {}      // 连接状态变化
};

🎵 音频文件配置

SDK需要以下音频文件，请将它们放在 public/sounds/ 目录下：

public/sounds/
├── incoming-call2.mp3      # 来电铃声
├── outgoing-call.mp3       # 呼出铃声
├── calling-end.mp3         # 通话结束音
├── outgoing-call-rejected.mp3  # 呼叫被拒绝音
├── incoming-chat.mp3       # 注册成功音
└── dialpad/               # DTMF按键音
    ├── 0.mp3
    ├── 1.mp3
    └── ...

🔍 故障排除

常见问题

Q: WebSocket 连接失败？

A: 检查服务器地址、端口和协议（ws/wss），确保网络可达

Q: 听不到声音？

A: 确保音频文件路径正确，audio元素已添加到DOM，浏览器已授权音频权限

Q: 连接经常断开？

A: 使用最新版本SDK (>= v1.0.11)，已修复WebSocket保活问题

Q: DTMF发送失败？

A: 确保在通话建立后发送，检查服务器DTMF支持

📋 更新日志

v1.0.21 (2025-09-29)

• ✨ 新增配置动态更新功能，支持在不重建实例的情况下更新SIP配置参数
• 🔧 添加getConfig和updateConfig方法，提供更灵活的配置管理
• 🔄 优化非注册模式下的配置更新机制，提高连接稳定性

v1.0.12 (2025-08-29)

• ✨ 新增 connect() 方法，支持非注册模式连接
• 🔗 完善 API 接口，提供与本地版本一致的功能
• 📚 改进类型定义和文档

v1.0.11 (2025-08-29)

• 🔧 重要修复: WebSocket 连接 2 分钟后自动断开的问题
• ⚡ 优化心跳机制，确保连接持续稳定
• 🔄 改进连接监控和保活机制

查看完整更新日志

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发环境

# 克隆仓库
git clone https://github.com/luqixin/vvott-sip-sdk.git

# 安装依赖
npm install

# 构建SDK
node build-sdk.js

# 本地测试
npm run dev

📄 许可证

MIT License

🔗 相关链接

• npm 包
• GitHub 仓库
• 问题反馈
• sip.js 官方文档

💪 技术支持

如有问题或需要技术支持，请通过以下方式联系：

• GitHub Issues: 提交问题
• 邮箱: [email protected]
• 文档: 在线文档

VVOTT SIP SDK - 让 Web 通信变得简单可靠！

快速开始 • 完整文档 • API参考 • 示例代码