使用Python的Azure Communication Services媒体播放问题求助

一、ACS Python SDK媒体播放的硬性要求 #

• 音频格式必须严格合规：
  仅支持WAV格式，且参数需满足：
  • 采样率：8kHz 或 16kHz
  • 位深度：16位
  • 声道：单声道（Mono）
  • 编码：PCM（无压缩脉冲编码调制）
• 音频URL的访问限制：
  • 必须是无身份验证的公网可访问地址，ACS服务无法处理带Token、Basic Auth的URL
  • 支持HTTP/HTTPS协议，优先用HTTPS避免跨域或安全策略限制
  • 不能存在3xx重定向，ACS会直接拒绝重定向地址
• SDK调用的关键注意点：
  • play_media是异步操作，调用成功不代表播放成功，必须监听Microsoft.Communication.PlayCompleted或Microsoft.Communication.PlayFailed事件确认状态
  • play_to=True表示播放给所有通话参与者，若需定向播放需传入participant_ids参数
  • 确保调用play_media时，对应的Call Connection处于已连接且未断开的状态

二、公网音频无法播放的调试步骤 #

1. 先验证音频文件本身
   • 用Audacity等工具检查文件参数，确认符合上述ACS格式要求
   • 本地播放测试，确保音频无损坏、音量正常
2. 确认URL的可达性与有效性
   • 在Azure同区域的VM或服务器上访问该URL，确认能直接下载完整文件（模拟ACS服务的访问环境）
   • 检查服务器防火墙/安全组，确保允许ACS服务的IP段访问
   • 确认URL无拼写错误，没有特殊字符或空格
3. 排查ACS事件与日志
   • 查看/calling-events端点接收的事件，若存在PlayFailed事件，里面会包含具体错误原因和代码
   • 登录Azure Portal，在ACS资源的监控-日志中筛选CallAutomation相关日志，查找播放操作的详细报错信息
4. 代码逻辑与环境验证
   • 替换音频URL为已知合规的公开WAV文件（比如符合参数要求的测试音频），测试是否能正常播放，排除自身音频问题
   • 确认call_connection_id正确，且对应的通话未断开
   • 检查是否有并发媒体操作（如录音、语音识别），同一时间ACS只允许一个媒体操作执行
5. TTS生成环节校验
   • 确保Speech Service生成TTS时指定了符合ACS要求的输出格式，示例配置：

     speech_config = SpeechConfig(subscription=speech_key, region=service_region)
     # 指定ACS兼容的输出格式
     speech_config.set_speech_synthesis_output_format(SpeechSynthesisOutputFormat.Riff16Khz16BitMonoPcm)
     

代码优化建议 #

原代码未处理播放结果事件，建议补充事件监听以排查问题：

@app.route('/calling-events', methods=['POST'])
def handle_calling_events():
    event_data = request.get_json()
    event_type = event_data.get('eventType')
    
    if event_type == 'Microsoft.Communication.PlayCompleted':
        print(f"音频播放完成，关联通话ID：{event_data['callConnectionId']}")
    elif event_type == 'Microsoft.Communication.PlayFailed':
        error = event_data.get('error', {})
        print(f"音频播放失败：{error.get('message')}，错误代码：{error.get('code')}，通话ID：{event_data['callConnectionId']}")
    
    return '', 200

内容的提问来源于stack exchange，提问作者Saad Illahi