Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

[Bug] SDK >= 2.3.0: on_playback_audio_frame_before_mixing never triggers when enable_audio_device=0 (Server SDK default)

オープン
  • 何か問題がありますか？
#34 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
48/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
静か
技術スタック
python
領域
audio-video-rtc

調査の方向性

agora/rtc/agora_service.py、agora/rtc/agora_base.py、agora/rtc/audio_frame_observer.py から始め、疑わしい 2.3.0 のコミット周辺で create_rtc_connection と initializeEx を追跡します。enable_audio_device=0 で callback 数を再現し、SDK 2.2.4 と比較します。サーバー構成で playback observer がオーディオハードウェアを必要とせずにデコード済みフレームを受信できれば完了です。

索引モデルが issue の本文から書いたものです。

説明

Description

Starting from SDK version 2.3.0, on_playback_audio_frame_before_mixing callback never fires in a Linux Server SDK environment (no physical audio device). This is a regression — versions <= 2.2.4 work correctly.

Root Cause (from our investigation)

In SDK >= 2.3.0, RtcConnectionImpl::initializeEx forcefully overrides enableAudioRecordingOrPlayout to 0 when enableAudioDevice=0:

// What we observe in agoraapi.log:
AgoraService::createRtcConnection(cfg:(enableAudioRecordingOrPlayout:1, ...))   // Python passes 1 ✓
RtcConnectionImpl::initializeEx(cfg:(enableAudioRecordingOrPlayout:0, ...))     // C++ overrides to 0 ✗

This disables the audio playback pipeline entirely, so on_playback_audio_frame_before_mixing is never called — even though onUserAudioTrackSubscribed fires successfully (audio data arrives but is not delivered to the callback).

Environment

  • OS: Ubuntu 22.04 (Docker, x86_64) / also tested on macOS ARM64
  • Python: 3.10 / 3.12
  • SDK versions tested:
    • 2.1.0 ~ 2.2.4: Working (receives ~770 audio frames in 8 seconds)
    • 2.3.0 ~ 2.4.6: Broken (0 audio frames received)

Reproduction Steps

from agora.rtc.agora_service import AgoraServiceConfig, AgoraService
from agora.rtc.agora_base import *
from agora.rtc.audio_frame_observer import IAudioFrameObserver

class AudioObs(IAudioFrameObserver):
    def __init__(self): self.count = 0
    def on_playback_audio_frame_before_mixing(self, lu, ch, uid, frame, vs, vb):
        self.count += 1
        return 1

# Initialize (standard Server SDK setup)
svc = AgoraService()
cfg = AgoraServiceConfig()
cfg.appid = "YOUR_APP_ID"
cfg.log_path = "/tmp/agora"
# enable_audio_device defaults to 0 (no audio hardware on server)
svc.initialize(cfg)

# Create connection
con_config = RTCConnConfig()
con_config.auto_subscribe_audio = 1
con_config.enable_audio_recording_or_playout = 1  # explicitly set to 1
pub_config = RtcConnectionPublishConfig()
pub_config.is_publish_audio = False
conn = svc.create_rtc_connection(con_config, pub_config)

# Register observer
lu = conn.get_local_user()
lu.set_playback_audio_frame_before_mixing_parameters(1, 16000)
ao = AudioObs()
lu._register_audio_frame_observer(ao, 0, None)
lu.subscribe_all_audio()

conn.connect(TOKEN, CHANNEL, UID)
time.sleep(10)  # wait while another user sends audio in the channel
print(f"Audio frames received: {ao.count}")  # Always 0 on SDK >= 2.3.0

Expected Behavior

Server SDK should deliver audio frames via on_playback_audio_frame_before_mixing even without a physical audio device (enable_audio_device=0). This worked correctly in SDK <= 2.2.4.

Workarounds

Workaround Limitation
Set enable_audio_device=1 Works on macOS (has CoreAudio), Segfaults on Linux containers (no ALSA/hardware)
Use modprobe snd-dummy on Linux Only works on VMs/physical machines with kernel module access, not standard Docker
Downgrade to SDK <= 2.2.4 Loses new features (bytes data stream, AI QoS, etc.)

Suspected Commit

The regression was introduced in the 2.3.0 release cycle, likely related to:

  • 838f49b — "merge from dev to main for aiqos, version 2.3.0"
  • 6c65a9e — "Add: add publish and connection configure in init(), modify connection"

The native C++ SDK upgrade for AI QoS appears to have added the logic that ties enableAudioRecordingOrPlayout to enableAudioDevice.

Suggested Fix

When enableAudioDevice=0, the SDK should still allow enableAudioRecordingOrPlayout=1 to enable the audio callback pipeline (without initializing hardware drivers). The audio frame observer should receive decoded PCM frames regardless of whether a physical playback device exists — this is the core Server SDK use case (AI speech processing, recording, etc.).

主要言語
Python
スター
18
フォーク
5
平均マージ
1分
マージ済み PR（30日）
1

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

AgoraIO-Extensions/Agora-Python-Server-SDK のほかの issue

AgoraIO-Extensions/Agora-Python-Server-SDK の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。