nx-sip-client 1.0.2

Python SIP client library with PJSUA2 and native UDP implementations

SIP Client Library

Python SIP 客戶端庫，提供兩種不同的實現方式：基於 PJSUA2 的高階實現和基於原生 UDP Socket 的底層實現。

概述

這個庫包含兩個獨立的 SIP 客戶端實現：

🚀 PJSUA2 版本 (sip_client.pj)

• 適用場景: 生產環境、快速開發、穩定性要求高
• 特點: 成熟穩定、功能完整、API 簡潔
• 依賴: PJSUA2 庫

🛠️ UDP 手刻版本 (sip_client.udp)

• 適用場景: 學習研究、深度客製化、嵌入式系統
• 特點: 完全控制、教育價值、輕量級
• 依賴: 僅 Python 標準庫

安裝方式

PyPI 安裝

pip install nx-sip-client

⚠️ 注意: 若欲使用本庫中的pj.sip_client，需要系統中已安裝 PJSUA2 庫。若無，建議使用下面的 Docker 環境。

🐳 使用 Docker 環境（推薦）

# 克隆項目（獲取 Docker 配置）
git clone <repository-url>
cd sip-client

# 構建含 PJSUA2 的 Docker 映像
cd docker
docker build -t sip-client .
docker run -it --network host sip-client /bin/bash

# 使用 Docker Compose 啟動環境
# 內有 volume 本庫做快速測試
cd docker
docker-compose up -d

🔧 自行安裝環境

如果需要開發或客製化：

# 克隆項目
git clone <repository-url>
cd sip-client

# PJSUA2 安裝及編譯（複雜，建議使用 Docker）
# 詳細步驟請參考 docker/Dockerfile

# 安裝測試依賴
pip install -r requirements.txt

基本使用

使用測試程式

# 進入容器
docker exec -it sip-client /bin/bash

# 在容器中運行測試
cd /home/user
python3 test_pjsua2.py  # 測試 PJSUA2 版本
python3 test_udp.py     # 測試 UDP 版本

PJSUA2 版本（需要 Docker 環境）

from sip_client.pj import SipClient
import logging

# 設定日誌
logging.basicConfig(level=logging.DEBUG)

# 建立客戶端
sc = SipClient(
    domain="sip.provider.com",
    port=5060,
    username="your_username",
    password="your_password",
    transport_ip="192.168.1.100",
    transport_port=5060,
    sip_log_level=3
)

# 初始化並註冊
sc.init()

# 等待註冊成功
while not sc.account.getInfo().regIsActive:
    sc.ENDPOINT.libHandleEvents(10)

print("SIP 註冊成功")

# 撥打電話
sc.make_call("target_user")

# 主事件循環
while True:
    sc.ENDPOINT.libHandleEvents(10)
    # 其他邏輯...

UDP 手刻版本

from sip_client.udp import SipClient, CallState
import time

# 建立客戶端
sc = SipClient(
    domain="sip.provider.com",
    port=5060,
    username="your_username",
    password="your_password",
    transport_ip="192.168.1.100",
    transport_port=5060,
    rtp_port=5004,
    rtcp_port=5005
)

# 註冊 SIP 帳號
success = sc.register()
if success:
    print("註冊成功")
    
    # 撥打電話
    sc.make_call("target_user")
    
    # 檢查通話狀態
    while sc.state != CallState.CONFIRMED:
        time.sleep(0.1)
    
    print("通話已建立")

功能比較

功能	PJSUA2 版本	UDP 手刻版本
基本通話	✅	✅
來電處理	✅	✅
主動轉接	✅	✅
被動轉接（接收 REFER）	⚠️	⚠️
通話保留	✅	✅
Digest 認證	✅	✅
RTP 音頻	✅	✅
183 智能處理	✅	❌
Hold-then-REFER	✅	❌
線程安全	✅	⚠️
多編解碼器	✅	⚠️
開發難度	低	中
資源使用	高	低
客製化程度	中	高

詳細文檔

PJSUA2 版本

詳細說明請參考：sip_client/pj/README.md

主要特色：

• 基於成熟的 PJSIP 庫
• 完整的線程安全支援
• 自動通話處理（183 Session Progress）
• 標準的 Hold-then-REFER 轉接機制
• 多編解碼器支援

UDP 手刻版本

詳細說明請參考：sip_client/udp/README.md

主要特色：

• 完全手工實現 SIP 協議
• 基於 RFC 3261 的完整狀態機
• 詳細的識別符管理說明
• 適合學習和深度客製化
• 輕量級，無外部依賴

音頻處理範例

兩個版本都支援音頻處理，以下是通用的音頻處理範例：

import librosa
import numpy as np

def convert_to_audio_bytes(audio, sr, norm=True):
    """將音頻轉換為 8kHz 16bit PCM 格式"""
    if sr != 8000:
        audio = librosa.resample(audio, orig_sr=sr, target_sr=8000, res_type='kaiser_fast')

    if norm:  
        # 正規化避免高頻雜音
        audio = audio * (32767 / max(0.01, np.max(np.abs(audio))))
        audio = audio.astype(np.int16)
    else:
        audio = (audio * 32767).astype(np.int16)

    return audio.tobytes()

# 播放音頻到通話中
def play_audio_to_call(sip_client, audio_file):
    audio, sr = librosa.load(audio_file, sr=None)
    audio_bytes = convert_to_audio_bytes(audio, sr)
    
    # PJSUA2 版本
    if hasattr(sip_client, 'current_call') and sip_client.current_call:
        sip_client.current_call.putFrame(audio_bytes)
    
    # UDP 版本  
    if hasattr(sip_client, 'current_call') and sip_client.current_call:
        sip_client.current_call.send_audio(audio_bytes)

測試範例

項目包含完整的測試範例：

• test_pjsua2.py: PJSUA2 版本的完整測試
• test_udp.py: UDP 版本的完整測試
• test_audio.py: 音頻處理測試

# 測試 PJSUA2 版本
python test_pjsua2.py

# 測試 UDP 版本
python test_udp.py

# 測試音頻處理
python test_audio.py

已知限制與 TODO

當前限制

• 被動轉接功能不完整: 當對方（第三方）嘗試將通話轉接到本 SIP 客戶端時，可能會出現問題
• REFER 請求處理: 接收和處理來自外部的 REFER 請求尚未完全實現

TODO 清單

1. 完善被動轉接機制

   • 實現接收 REFER 請求的完整處理流程
   • 支援被動轉接時的狀態機轉換
   • 處理轉接過程中的錯誤情況

2. UDP 版本改進

   • RTP socket 的保護機制
   • Socket 發送失敗時的 FSM 調整
   • 增強線程安全性

3. 功能擴展

   • 支援更多音頻編解碼器
   • 改進錯誤處理和恢復機制
   • 添加更完整的 SIP 特性支援

注意事項

1. 推薦使用 Docker: 由於 PJSUA2 編譯複雜，強烈建議使用提供的 Docker 環境
2. 網路配置: 使用 --network host 模式確保 SIP 和 RTP 端口正常通信
3. 音頻格式: 預設使用 PCMA/8000 編解碼器
4. 線程安全: UDP 版本在多線程環境需要額外注意
5. 手動編譯: 如需手動編譯 PJSUA2，請參考 docker/Dockerfile 中的詳細步驟