agora-python-server-sdk 2.4.0__tar.gz → 2.4.1__tar.gz

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agora_python_server_sdk
-Version: 2.4.0
+Version: 2.4.1
 Summary: A Python SDK for Agora Server
 Home-page: https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK
 Classifier: Intended Audience :: Developers
@@ -38,7 +38,7 @@ Description-Content-Type: text/markdown
 # Required Operating Systems and Python Versions
 - Supported Linux versions:
   - Ubuntu 18.04 LTS and above
-  - CentOS 7.0 and above
+  - CentOS 8.0 and above
   
 - Supported Mac versions:
   - MacOS 13 and above(only for coding and testing)
@@ -57,40 +57,55 @@ pip install agora_python_server_sdk
 - Download and unzip [test_data.zip](https://download.agora.io/demo/test/test_data_202408221437.zip) to the Agora-Python-Server-SDK directory.
 
 ## Executing Test Script
-or linux os, should set env to ：/site_packages/agora/agora_sdk/, like:
+for linux os, should set env to ：/site_packages/agora/agora_sdk/, like:
 export LD_LIBRARY_PATH=/site_packages/agora/agora_sdk/
 ```
 python agora_rtc/examples/example_audio_pcm_send.py --appId=xxx --channelId=xxx --userId=xxx --audioFile=./test_data/demo.pcm --sampleRate=16000 --numOfChannels=1
 ```
 
 # Change log
-## 2025.11.18 Release version 2.4.0
--- Update SDK to APM version: 4.4.32/1025
--- Add configure support for enabling/disabling APM
--- Update methods in setup.py and __init__.py, ok, including version/URL, md5, etc.
--- Overall code pipeline ok, needs testing?? ok
--- Add support to rtm, one single sdk supports both rtm and rtc, ok
--- todo:
-  -[] Need to add VAD algorithm update ok
-  -[] Need to add vad_dump modifications ok
-  -[] Modify APM algorithm to support VAD switch, ok
-  -[] Add VAD configure parameter settings, ok
-  -[] Download every time, check md5 mismatch?? ok
-  NOTE:
-  APM features, i.e., server-side echo cancellation, noise suppression, automatic gain control, background voice removal, etc.
-  Normally, AEC/AINS/AGC, etc., are already implemented on the client side, and the server side does not need to implement them again, unless there are special requirements.
-  If you want to enable APM features, please contact Agora technical support.
-  NOTE：
-  How to use rtc,please ref to: https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/examples
-  Hot to use rtm,please ref to ://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/rtm_examples
+## 2025.12.17 Release 2.4.1
+
+- Updated RTC SDK to version 154.
+- Added support for VAD (Voice Activity Detection) for external audio sources, including:
+  - **Background voice removal**
+  - **Noise suppression**
+  - **Echo cancellation**
+  - **Automatic gain control**
+  - **Other 3A algorithms**  
+  All supported via the `external_Audio_Processor`.
+- Modified LocalUser return values for clearer SDK error code distinction.
+- Added `example_external_Audio_Processor.py` to demonstrate external audio data processing.
+
+---
+
+## 2025.11.18 Release 2.4.0
+
+- Updated SDK to APM version: `4.4.32/1025`
+- Added configuration support to enable/disable APM.
+- Updated methods in `setup.py` and `__init__.py`, including version/URL and MD5 processing.
+- Completed main code pipeline (**further testing recommended**).
+- Added RTM support: one SDK now supports both RTC and RTM.
+
+**To-Do Items:**
+- [x] Add VAD algorithm update
+- [x] Add vad_dump modifications
+- [x] Add APM algorithm VAD switch support
+- [x] Add VAD configuration parameter setting
+- [x] Download and check for MD5 mismatch on every download
+
+**Notes:**
+- **APM features** include server-side echo cancellation, noise suppression, automatic gain control, background voice removal, and more.
+- Typically, AEC/AINS/AGC, etc., are handled on the client; server-side activation is only necessary for specific requirements.
+- If you need to enable APM, please contact Agora technical support.
+
+**Usage Examples:**  
+- [RTC usage example](https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/examples)  
+- [RTM usage example](https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/rtm_examples)
 # 2025.11.07 release 2.3.3
 -- update: to support rtm
 -- adjust sdk's directory structure
 -- change requests to urllib
-# 2025.10.23 release 2.3.2: support rtc and rtm in one package
--- update: to support rtm.can support both rtc and rtm in one package.
--- adjust sdk's directory structure
--- update rtc sdk
 # 2025.10.09  release 2.3.1
 -- update arm64 rtc sdk:Fixed a JNI referencing issue in the previous arm64 build. This issue only outputs logs to the console and does not affect functionality.
 

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/README.md

@@ -23,7 +23,7 @@
 # Required Operating Systems and Python Versions
 - Supported Linux versions:
   - Ubuntu 18.04 LTS and above
-  - CentOS 7.0 and above
+  - CentOS 8.0 and above
   
 - Supported Mac versions:
   - MacOS 13 and above(only for coding and testing)
@@ -42,40 +42,55 @@ pip install agora_python_server_sdk
 - Download and unzip [test_data.zip](https://download.agora.io/demo/test/test_data_202408221437.zip) to the Agora-Python-Server-SDK directory.
 
 ## Executing Test Script
-or linux os, should set env to ：/site_packages/agora/agora_sdk/, like:
+for linux os, should set env to ：/site_packages/agora/agora_sdk/, like:
 export LD_LIBRARY_PATH=/site_packages/agora/agora_sdk/
 ```
 python agora_rtc/examples/example_audio_pcm_send.py --appId=xxx --channelId=xxx --userId=xxx --audioFile=./test_data/demo.pcm --sampleRate=16000 --numOfChannels=1
 ```
 
 # Change log
-## 2025.11.18 Release version 2.4.0
--- Update SDK to APM version: 4.4.32/1025
--- Add configure support for enabling/disabling APM
--- Update methods in setup.py and __init__.py, ok, including version/URL, md5, etc.
--- Overall code pipeline ok, needs testing?? ok
--- Add support to rtm, one single sdk supports both rtm and rtc, ok
--- todo:
-  -[] Need to add VAD algorithm update ok
-  -[] Need to add vad_dump modifications ok
-  -[] Modify APM algorithm to support VAD switch, ok
-  -[] Add VAD configure parameter settings, ok
-  -[] Download every time, check md5 mismatch?? ok
-  NOTE:
-  APM features, i.e., server-side echo cancellation, noise suppression, automatic gain control, background voice removal, etc.
-  Normally, AEC/AINS/AGC, etc., are already implemented on the client side, and the server side does not need to implement them again, unless there are special requirements.
-  If you want to enable APM features, please contact Agora technical support.
-  NOTE：
-  How to use rtc,please ref to: https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/examples
-  Hot to use rtm,please ref to ://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/rtm_examples
+## 2025.12.17 Release 2.4.1
+
+- Updated RTC SDK to version 154.
+- Added support for VAD (Voice Activity Detection) for external audio sources, including:
+  - **Background voice removal**
+  - **Noise suppression**
+  - **Echo cancellation**
+  - **Automatic gain control**
+  - **Other 3A algorithms**  
+  All supported via the `external_Audio_Processor`.
+- Modified LocalUser return values for clearer SDK error code distinction.
+- Added `example_external_Audio_Processor.py` to demonstrate external audio data processing.
+
+---
+
+## 2025.11.18 Release 2.4.0
+
+- Updated SDK to APM version: `4.4.32/1025`
+- Added configuration support to enable/disable APM.
+- Updated methods in `setup.py` and `__init__.py`, including version/URL and MD5 processing.
+- Completed main code pipeline (**further testing recommended**).
+- Added RTM support: one SDK now supports both RTC and RTM.
+
+**To-Do Items:**
+- [x] Add VAD algorithm update
+- [x] Add vad_dump modifications
+- [x] Add APM algorithm VAD switch support
+- [x] Add VAD configuration parameter setting
+- [x] Download and check for MD5 mismatch on every download
+
+**Notes:**
+- **APM features** include server-side echo cancellation, noise suppression, automatic gain control, background voice removal, and more.
+- Typically, AEC/AINS/AGC, etc., are handled on the client; server-side activation is only necessary for specific requirements.
+- If you need to enable APM, please contact Agora technical support.
+
+**Usage Examples:**  
+- [RTC usage example](https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/examples)  
+- [RTM usage example](https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/rtm_examples)
 # 2025.11.07 release 2.3.3
 -- update: to support rtm
 -- adjust sdk's directory structure
 -- change requests to urllib
-# 2025.10.23 release 2.3.2: support rtc and rtm in one package
--- update: to support rtm.can support both rtc and rtm in one package.
--- adjust sdk's directory structure
--- update rtc sdk
 # 2025.10.09  release 2.3.1
 -- update arm64 rtc sdk:Fixed a JNI referencing issue in the previous arm64 build. This issue only outputs logs to the console and does not affect functionality.
 

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/agora/__init__.py

@@ -95,7 +95,16 @@ def report_progress(blocknum, blocksize, totalsize):
         downloaded = blocknum * blocksize
         print(f"\rDownloading: ----{downloaded} bytes-----", end='', flush=True)
 
-
+def _get_url_from_version_file(path: str):
+    if not os.path.exists(path):
+        return ""
+    try:
+        with open(path, 'r') as f:
+            lines = f.readline()
+            return lines
+    except Exception as e:
+        logger.error(f"Failed to read version file: {e}")
+        return ""
 def _check_download_and_extract_sdk():
     agora_service_path = os.path.dirname(os.path.abspath(__file__))
     # change from dir like: /home/xxx/agora_rtc/agora/rtc/agora_sdk to
@@ -125,12 +134,20 @@ def _check_download_and_extract_sdk():
     #20251110 Fusion version: with apm filter
     mac_sdk="https://download.agora.io/sdk/release/agora_sdk_mac_v4.4.30_25869_FULL_20251030_1836_953684-aed.zip"
     linux_sdk = "https://download.agora.io/sdk/release/agora_rtc_sdk_x86_64-linux-gnu-v4.4.32.150_26715_SERVER_20251030_1807-aed.zip"
+
+    linux_sdk = "https://download.agora.io/sdk/release/agora_rtc_sdk_x86_64-linux-gnu-Agora_Native_SDK_for_Linux_x64_zhourui_26895_SERVER_20251121_1628_987405_20251021_1427-3a.zip"
+    mac_sdk="https://download.agora.io/sdk/release/agora_sdk_mac_Agora_Native_SDK_for_Mac_zhourui_26101_FULL_20251121_2135_987705_20251021_1427-3a.zip"
+
+    linux_sdk="https://download.agora.io/sdk/release/agora_rtc_sdk_x86_64-linux-gnu-v4.4.32.154_26982_SERVER_20251210_1745_994155_20251021_1427-3a.zip"
+    mac_sdk="https://download.agora.io/sdk/release/agora_sdk_mac_v4.4.32.154_26308_FULL_20251210_1756_994156_20251021_1427-3a.zip"
+
+
     
           
     linux_libfile_path = os.path.join(sdk_library_dir, "libagora_rtc_sdk.so")
     mac_libfile_path = os.path.join(sdk_library_dir, "libAgoraRtcKit.dylib")
-    linux_md5 = "821cb1a388279648fcb204ca795e6476"
-    mac_md5 = "5b9940d3fca033a53ac30216d5c39be6"
+    linux_md5 = "e89043f0db667c207d9308d3515a67ed"
+    mac_md5 = "f63e8af2047a53643a1ceb0a4b24b802"
 
     #rtc_md5 = "7031dd10d1681cd88fd89d68c5b54282"
     url = linux_sdk
@@ -156,6 +173,7 @@ def _check_download_and_extract_sdk():
         url = "https://download.agora.io/sdk/release/Agora-RTC-aarch64-linux-gnu-v4.4.32-20251009_145437-921455_20251023_1538.zip"
         rtc_md5 = "5c002f25d2b381e353082da4f835b4f2"
 
+    '''
     is_file_exist = os.path.exists(rtc_libfile_path)
     if is_file_exist:
         md5_value = get_file_md5(rtc_libfile_path)
@@ -163,8 +181,15 @@ def _check_download_and_extract_sdk():
         md5_value = ""
     if md5_value == rtc_md5:
         return
+    '''
+    is_file_exist = os.path.exists(rtc_libfile_path)
+    version_url = _get_url_from_version_file(os.path.join(sdk_root_dir, "version.txt"))
+    if version_url == url and is_file_exist:
+        return
+        
+    #change from md5 check to url check
 
-    logger.error(f"missing agora sdk, now download it, please wait for a while...: {rtc_libfile_path} {md5_value} {rtc_md5} {is_file_exist}")
+    logger.error(f"missing agora sdk, now download it, please wait for a while...: {rtc_libfile_path} {version_url} {url} {is_file_exist}")
     if os.path.exists(sdk_library_dir):
         os.system(f"rm -rf {sdk_library_dir}")
     os.makedirs(sdk_library_dir, exist_ok=True)
@@ -184,6 +209,9 @@ def _check_download_and_extract_sdk():
 
     if os.path.exists(zip_path):
         os.remove(zip_path)
+    #write version url to version.txt
+    with open(os.path.join(sdk_root_dir, "version.txt"), "w") as f:
+        f.write(url)
     logger.error("download done, continue...")
 
 
@@ -207,5 +235,5 @@ if not os.path.exists(rtc_libfile_path):
     logger.error(f"library {rtc_libfile_path} not found")
     sys.exit(1)
 
-# 显式导出这些变量，确保子模块可以导入
+# Explicitly export these variables to ensure that submodules can import them
 __all__ = ['sdk_library_dir', 'sdk_rtc_dir', 'sdk_rtm_dir', 'sdk_root_dir']

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/agora/rtc/_ctypes_handle/_ctypes_data.py

@@ -1368,4 +1368,49 @@ class CapabilitiesItemMapInner(ctypes.Structure):
         return CapabilitiesItemMap(
             item=self.item,
             size=self.size
-        )
+        )
+
+class AudioSinkWantesInner(ctypes.Structure):
+    _fields_ = [
+        ("samples_per_sec", ctypes.c_int),
+        ("channels", ctypes.c_uint32),
+    ]
+    pass
+class AudioLabelInner(ctypes.Structure):
+    _fields_ = [
+        ("far_filed_flag", ctypes.c_int),
+        ("rms", ctypes.c_int),
+        ("voice_prob", ctypes.c_int),
+        ("music_prob", ctypes.c_int),
+        ("pitch", ctypes.c_int),
+    ]
+class AudioPcmFrameInner(ctypes.Structure):
+    _fields_ = [
+        ("capture_timestamp", ctypes.c_uint32),
+        ("samples_per_channel", ctypes.c_uint32),
+        ("sample_rate_hz", ctypes.c_int),
+        ("num_channels", ctypes.c_uint32),
+        ("bytes_per_sample", ctypes.c_uint32),
+        ("data", ctypes.c_int16*3840),
+        ("audio_label", AudioLabelInner),
+    ]
+    def get(self):
+        return AudioFrame(
+            type=0,
+            samples_per_channel=self.samples_per_channel,
+            bytes_per_sample=self.bytes_per_sample,
+            channels=self.num_channels,
+            samples_per_sec=self.sample_rate_hz,
+            buffer=bytearray(ctypes.string_at(self.data, self.samples_per_channel * self.bytes_per_sample * self.num_channels)),
+            render_time_ms=self.capture_timestamp,
+            avsync_type=0,
+            presentation_ms=0,
+            audio_track_number=0,
+            rtp_timestamp=0,
+            far_field_flag=self.audio_label.far_filed_flag,
+            rms=self.audio_label.rms,
+            voice_prob=self.audio_label.voice_prob,
+            music_prob=self.audio_label.music_prob,
+            pitch=self.audio_label.pitch
+        )
+    pass

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/agora/rtc/agora_service.py

@@ -118,6 +118,12 @@ class AgoraService:
         result = agora_service_enable_extension(self.service_handle, cprovider, cgenerator, ctrak, 1)
         if result != 0:
             logger.error(f"Failed to enable audio processing remote playback filter. Error code: {result}")
+        if config.enable_apm:
+            generator = "audio_processing_pcm_source"
+            cgenerator = generator.encode('utf-8')
+            result = agora_service_enable_extension(self.service_handle, cprovider, cgenerator, ctrak, 1)
+            if result != 0:
+                logger.error(f"Failed to enable audio processing pcm source filter. Error code: {result}")
        
         #versio 2.2.0 for callback when muted
         if config.should_callbck_when_muted > 0:

agora_python_server_sdk-2.4.1/agora/rtc/external_audio_processor.py

@@ -0,0 +1,222 @@
+import time
+import ctypes
+
+from .agora_base import *
+from .agora_service import AgoraService, _set_filter_property_by_track, _enable_audio_filter_by_track
+from .local_user import LocalUser
+from .rtc_connection_observer import IRTCConnectionObserver
+from ._ctypes_handle._audio_frame_observer import AudioFrameObserverInner
+from .agora_parameter import AgoraParameter
+from ._utils.globals import AgoraHandleInstanceMap
+from ._ctypes_handle._rtc_connection_observer import RTCConnectionObserverInner, CapabilitiesObserverInner
+from ._ctypes_handle._ctypes_data import *
+from .utils.audio_consumer import PcmConsumeStats
+from .voice_detection import AudioVadConfigV2, AudioVadV2
+import logging
+logger = logging.getLogger(__name__)
+
+
+
+
+class IAudioSinkObserver:
+    def on_processed_audio_frame(self,processor: 'ExternalAudioProcessor',frame: AudioFrame,vad_result_state:int,vad_result_data:bytearray):
+        pass
+
+agora_audio_sink_create = agora_lib.agora_audio_sink_create
+agora_audio_sink_create.restype = ctypes.c_void_p
+agora_audio_sink_create.argtypes = [ctypes.c_void_p]
+
+agora_audio_track_add_audio_sink = agora_lib.agora_audio_track_add_audio_sink
+agora_audio_track_add_audio_sink.restype = ctypes.c_int
+agora_audio_track_add_audio_sink.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.POINTER(AudioSinkWantesInner)]
+
+agora_audio_sink_destroy = agora_lib.agora_audio_sink_destroy
+agora_audio_sink_destroy.restype = None
+agora_audio_sink_destroy.argtypes = [ctypes.c_void_p]
+
+#call back dec
+ON_AUDIO_SINK_DATA_CALLBACK = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.POINTER(AudioPcmFrameInner))
+
+
+class AudioSinkObserverInner(ctypes.Structure):
+    _fields_ = [
+        ("on_audio_sink_data", ON_AUDIO_SINK_DATA_CALLBACK),
+        ("user_data", ctypes.c_void_p),
+    ]
+    def __init__(self, processor: 'ExternalAudioProcessor'):
+        self.on_audio_sink_data = ON_AUDIO_SINK_DATA_CALLBACK(self._on_audio_sink_data)
+        self._processor = processor
+        pass
+    def _on_audio_sink_data(self, handle: ctypes.c_void_p, audio_pcm_frame_inner_ptr: ctypes.POINTER(AudioPcmFrameInner)):
+
+        #validity check
+        if audio_pcm_frame_inner_ptr is None:
+            return -1000
+    
+        #convert to aduioframe, and get user data
+        pcm_frame = audio_pcm_frame_inner_ptr.contents
+       
+        #conver to audioframe
+        audio_frame = pcm_frame.get()
+        
+        if self._processor:
+            self._processor._do_result_frame(audio_frame)
+
+        return 0
+
+class AudioSink:
+    def __init__(self, audio_processor: 'ExternalAudioProcessor'):
+        self._audio_sink_observer_inner = None
+        self._c_sink = None
+        self._audio_processor = audio_processor
+        pass
+    def release(self):
+        if self._c_sink:
+            agora_audio_sink_destroy(ctypes.c_void_p(self._c_sink))
+            self._c_sink = None
+        self._audio_sink_observer_inner = None
+        self._audio_processor = None
+        pass
+
+class ExternalAudioProcessor:
+    
+    def __init__(self, engine: AgoraService):
+        self._pcm_sender = None
+        self._local_audio_track = None
+        self._engine = engine
+        self._is_initialized = False
+        #do create sender and track
+        self._pcm_sender = self._engine.media_node_factory.create_audio_pcm_data_sender()
+        self._local_audio_track = self._engine._create_custom_audio_track_pcm(self._pcm_sender, AudioScenarioType.AUDIO_SCENARIO_DEFAULT)
+        self._audio_sink = self._create_audio_sink()
+        self._vad_instance = None
+        self._observer = None
+        pass
+    def initialize(self, apm_config: APMConfig, out_sample_rate: int, out_channels: int, vad_config: AudioVadConfigV2, observer: IAudioSinkObserver)->int:
+        if self._is_initialized:
+            return 0
+        if apm_config is None and vad_config is None:
+            logger.error("[ExternalAudioProcessor] apm_config and vad_config are both None")
+            return -1000
+        if out_sample_rate <= 0 or out_channels <= 0:
+            logger.error("[ExternalAudioProcessor] out_sample_rate or out_channels is invalid")
+            return -1001
+        if observer is None:
+            logger.error("[ExternalAudioProcessor] observer is None")
+            return -1002
+
+               #set filer properties
+        ret = self._set_filter_properties(apm_config)
+        if ret < 0:
+            logger.info(f"[ExternalAudioProcessor] Failed to set filter properties, error: {ret}")
+            return ret
+
+        #add sink
+        ret = self._add_audio_sink(out_sample_rate, out_channels)
+        if ret < 0:
+            logger.info(f"[ExternalAudioProcessor] Failed to add audio sink, error: {ret}")
+            return ret
+ 
+        #set track properties
+        self._local_audio_track.set_send_delay_ms(10)
+        self._local_audio_track.set_max_buffer_audio_frame_number(100000)
+        self._local_audio_track.set_enabled(True)
+
+        self._observer = observer
+
+        # create vad instance
+        if vad_config is not None:
+            self._vad_instance = AudioVadV2(vad_config)
+        return ret
+        pass
+        
+    def push_audio_pcm_data(self, data, sample_rate, channels, start_pts:int=0)->int:
+        ret = -1000
+        if self._pcm_sender is None:
+            return -1001
+        readLen = len(data)
+        bytes_per_frame_in_ms = (sample_rate / 1000) * 2 * channels
+        remainder = readLen % bytes_per_frame_in_ms
+        if remainder != 0:
+            return -1002
+        pack_num_in_ms = readLen // bytes_per_frame_in_ms
+        
+        frame = PcmAudioFrame()
+        frame.data = data
+        frame.sample_rate = sample_rate
+        frame.number_of_channels = channels
+        frame.bytes_per_sample = 2
+        frame.timestamp = 0
+        frame.samples_per_channel = readLen // (channels * 2)
+        frame.present_time_ms = start_pts
+
+        ret = self._pcm_sender.send_audio_pcm_data(frame)
+        return ret
+    def _create_audio_sink(self)->AudioSink:
+        audio_sink = AudioSink(self)
+        audio_sink_observer_inner = AudioSinkObserverInner(self)
+        audio_sink._audio_sink_observer_inner = audio_sink_observer_inner
+        audio_sink._c_sink = agora_audio_sink_create(ctypes.byref(audio_sink_observer_inner))
+        if audio_sink._c_sink is None:
+            return None
+        
+        return audio_sink
+    def _add_audio_sink(self, out_sample_rate: int, out_channels: int)->int:
+        if self._audio_sink is None or self._audio_sink._c_sink is None:
+            return -1000
+
+        # call to c api
+        wants = AudioSinkWantesInner(samples_per_sec=out_sample_rate, channels=out_channels)
+        ret = agora_audio_track_add_audio_sink(self._local_audio_track.track_handle, self._audio_sink._c_sink, ctypes.byref(wants))
+        return ret
+        pass
+    def _set_filter_properties(self, apm_config: APMConfig)->int:
+        if self._audio_sink is None or self._audio_sink._c_sink is None:
+            return -2000
+        if apm_config is None:
+            return 0
+        #call to c api
+        track_handle = self._local_audio_track.track_handle
+        ret = _enable_audio_filter_by_track(track_handle, "audio_processing_pcm_source", True, True)
+        if ret != 0:
+            logger.info(f"[ExternalAudioProcessor] Failed to enable audio filter by track, error: {ret}")
+            return -2003
+
+        ret = _set_filter_property_by_track(track_handle, "audio_processing_pcm_source", "apm_load_resource", "ains", True)
+        if ret != 0:
+            logger.info(f"[ExternalAudioProcessor] Failed to set filter property by track, error: {ret}")
+            return -2004
+
+        apm_config_json = apm_config._to_json_string()
+        if apm_config_json is None:
+            logger.info(f"[ExternalAudioProcessor] Failed to get apm config json")
+            return -2005
+
+
+        ret = _set_filter_property_by_track(track_handle, "audio_processing_pcm_source", "apm_config", apm_config_json, True)
+        if ret != 0:
+            logger.info(f"[ExternalAudioProcessor]Failed to set filter property by track, error: {ret}")
+            return -2006
+        logger.info(f"[ExternalAudioProcessor] apm configure json: {apm_config_json}")
+
+        if apm_config.enable_dump:
+            ret = _set_filter_property_by_track(track_handle, "audio_processing_pcm_source", "apm_dump", "true", True)
+            if ret != 0:
+                logger.info(f"[ExternalAudioProcessor] Failed to set filter property by track, error: {ret}")
+                return -2007
+        
+        return ret
+    def _do_result_frame(self, audio_frame: AudioFrame):
+        print(f"ExternalAudioProcessor _do_result_frame: audio_frame voice_prob {audio_frame.voice_prob}, rms {audio_frame.rms}, pitch {audio_frame.pitch}, far_field_flag {audio_frame.far_field_flag}")
+        ret  = 0
+        data = None
+        if self._vad_instance is not None:
+            ret, data = self._vad_instance.process(audio_frame)
+            print(f"ExternalAudioProcessor _do_result_frame: vad result ret {ret}, data length {len(data)}")
+        #do callback now
+        if self._observer is not None:
+            self._observer.on_processed_audio_frame(self, audio_frame, ret, data)
+        pass
+
+
+

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/agora/rtc/local_user.py

@@ -383,7 +383,7 @@ class LocalUser:
 
     def subscribe_audio(self, user_id):
         if user_id is None:
-            return -1
+            return -1000
         uid_str = user_id.encode('utf-8')
         #ret = agora_local_user_subscribe_audio(self.user_handle, ctypes.create_string_buffer(uid_str))
         # note：both ctypes.create_string_buffer and ctypes.c_char_p are all can change python's str to c_char_p
@@ -398,7 +398,7 @@ class LocalUser:
     def unsubscribe_audio(self, user_id):
         #validity check
         if user_id is None:
-            return -1
+            return -1000
         uid_str = user_id.encode('utf-8')
         ret = agora_local_user_unsubscribe_audio(self.user_handle, ctypes.c_char_p(uid_str))
         if ret < 0:
@@ -517,7 +517,7 @@ class LocalUser:
 
     def subscribe_video(self, user_id, options: VideoSubscriptionOptions):
         if user_id is None:
-            return -1
+            return -1000
         uid_str = user_id.encode('utf-8')
 
         
@@ -540,7 +540,7 @@ class LocalUser:
 
     def unsubscribe_video(self, user_id):
         if user_id is None:
-            return -1
+            return -1000
         uid_str = user_id.encode('utf-8')
         ret = agora_local_user_unsubscribe_video(self.user_handle, ctypes.c_char_p(uid_str))
         if ret < 0:

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/agora_python_server_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agora_python_server_sdk
-Version: 2.4.0
+Version: 2.4.1
 Summary: A Python SDK for Agora Server
 Home-page: https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK
 Classifier: Intended Audience :: Developers
@@ -38,7 +38,7 @@ Description-Content-Type: text/markdown
 # Required Operating Systems and Python Versions
 - Supported Linux versions:
   - Ubuntu 18.04 LTS and above
-  - CentOS 7.0 and above
+  - CentOS 8.0 and above
   
 - Supported Mac versions:
   - MacOS 13 and above(only for coding and testing)
@@ -57,40 +57,55 @@ pip install agora_python_server_sdk
 - Download and unzip [test_data.zip](https://download.agora.io/demo/test/test_data_202408221437.zip) to the Agora-Python-Server-SDK directory.
 
 ## Executing Test Script
-or linux os, should set env to ：/site_packages/agora/agora_sdk/, like:
+for linux os, should set env to ：/site_packages/agora/agora_sdk/, like:
 export LD_LIBRARY_PATH=/site_packages/agora/agora_sdk/
 ```
 python agora_rtc/examples/example_audio_pcm_send.py --appId=xxx --channelId=xxx --userId=xxx --audioFile=./test_data/demo.pcm --sampleRate=16000 --numOfChannels=1
 ```
 
 # Change log
-## 2025.11.18 Release version 2.4.0
--- Update SDK to APM version: 4.4.32/1025
--- Add configure support for enabling/disabling APM
--- Update methods in setup.py and __init__.py, ok, including version/URL, md5, etc.
--- Overall code pipeline ok, needs testing?? ok
--- Add support to rtm, one single sdk supports both rtm and rtc, ok
--- todo:
-  -[] Need to add VAD algorithm update ok
-  -[] Need to add vad_dump modifications ok
-  -[] Modify APM algorithm to support VAD switch, ok
-  -[] Add VAD configure parameter settings, ok
-  -[] Download every time, check md5 mismatch?? ok
-  NOTE:
-  APM features, i.e., server-side echo cancellation, noise suppression, automatic gain control, background voice removal, etc.
-  Normally, AEC/AINS/AGC, etc., are already implemented on the client side, and the server side does not need to implement them again, unless there are special requirements.
-  If you want to enable APM features, please contact Agora technical support.
-  NOTE：
-  How to use rtc,please ref to: https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/examples
-  Hot to use rtm,please ref to ://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/rtm_examples
+## 2025.12.17 Release 2.4.1
+
+- Updated RTC SDK to version 154.
+- Added support for VAD (Voice Activity Detection) for external audio sources, including:
+  - **Background voice removal**
+  - **Noise suppression**
+  - **Echo cancellation**
+  - **Automatic gain control**
+  - **Other 3A algorithms**  
+  All supported via the `external_Audio_Processor`.
+- Modified LocalUser return values for clearer SDK error code distinction.
+- Added `example_external_Audio_Processor.py` to demonstrate external audio data processing.
+
+---
+
+## 2025.11.18 Release 2.4.0
+
+- Updated SDK to APM version: `4.4.32/1025`
+- Added configuration support to enable/disable APM.
+- Updated methods in `setup.py` and `__init__.py`, including version/URL and MD5 processing.
+- Completed main code pipeline (**further testing recommended**).
+- Added RTM support: one SDK now supports both RTC and RTM.
+
+**To-Do Items:**
+- [x] Add VAD algorithm update
+- [x] Add vad_dump modifications
+- [x] Add APM algorithm VAD switch support
+- [x] Add VAD configuration parameter setting
+- [x] Download and check for MD5 mismatch on every download
+
+**Notes:**
+- **APM features** include server-side echo cancellation, noise suppression, automatic gain control, background voice removal, and more.
+- Typically, AEC/AINS/AGC, etc., are handled on the client; server-side activation is only necessary for specific requirements.
+- If you need to enable APM, please contact Agora technical support.
+
+**Usage Examples:**  
+- [RTC usage example](https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/examples)  
+- [RTM usage example](https://github.com/AgoraIO-Extensions/Agora-Python-Server-SDK/tree/main/agora_rtc/rtm_examples)
 # 2025.11.07 release 2.3.3
 -- update: to support rtm
 -- adjust sdk's directory structure
 -- change requests to urllib
-# 2025.10.23 release 2.3.2: support rtc and rtm in one package
--- update: to support rtm.can support both rtc and rtm in one package.
--- adjust sdk's directory structure
--- update rtc sdk
 # 2025.10.09  release 2.3.1
 -- update arm64 rtc sdk:Fixed a JNI referencing issue in the previous arm64 build. This issue only outputs logs to the console and does not affect functionality.
 

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/agora_python_server_sdk.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ agora/rtc/audio_frame_observer.py
 agora/rtc/audio_pcm_data_sender.py
 agora/rtc/audio_sessionctrl.py
 agora/rtc/audio_vad_manager.py
+agora/rtc/external_audio_processor.py
 agora/rtc/local_audio_track.py
 agora/rtc/local_user.py
 agora/rtc/local_user_observer.py

{agora_python_server_sdk-2.4.0 → agora_python_server_sdk-2.4.1}/setup.py

@@ -84,6 +84,16 @@ class CustomInstallCommand(install):
         #20251110 Fusion version: with apm filter
         mac_sdk="https://download.agora.io/sdk/release/agora_sdk_mac_v4.4.30_25869_FULL_20251030_1836_953684-aed.zip"
         url = "https://download.agora.io/sdk/release/agora_rtc_sdk_x86_64-linux-gnu-v4.4.32.150_26715_SERVER_20251030_1807-aed.zip"
+        #date:20251124 update sdk for fix the issue of auto load so and auto load ains resource
+        url = "https://download.agora.io/sdk/release/agora_rtc_sdk_x86_64-linux-gnu-Agora_Native_SDK_for_Linux_x64_zhourui_26895_SERVER_20251121_1628_987405_20251021_1427-3a.zip"
+        mac_sdk="https://download.agora.io/sdk/release/agora_sdk_mac_Agora_Native_SDK_for_Mac_zhourui_26101_FULL_20251121_2135_987705_20251021_1427-3a.zip"
+        #added local track apm filter
+        #date:20251217 for incremental sending mode support
+        url="https://download.agora.io/sdk/release/agora_rtc_sdk_x86_64-linux-gnu-v4.4.32.154_26982_SERVER_20251210_1745_994155_20251021_1427-3a.zip"
+        mac_sdk="https://download.agora.io/sdk/release/agora_sdk_mac_v4.4.32.154_26308_FULL_20251210_1756_994156_20251021_1427-3a.zip"
+
+      
+        
         if sys.platform == 'darwin':
             url = mac_sdk
    
@@ -109,11 +119,14 @@ class CustomInstallCommand(install):
 
         if os.path.exists(zip_path):
             os.remove(zip_path)
+        #write version url to version.txt ,to replace the md5 check
+        with open(os.path.join(agora_service_path, "version.txt"), "w") as f:
+            f.write(url)
 
 
 setup(
     name='agora_python_server_sdk',
-    version='2.4.0',
+    version='2.4.1',
     description='A Python SDK for Agora Server',
     long_description=open('README.md').read(),
     long_description_content_type='text/markdown',