explicitly clean up the platformAudio

Author: xianshijing-lk

examples/local_audio/full_duplex.py

@@ -65,17 +65,20 @@ def list_audio_devices() -> None:
         print(f"Failed to initialize PlatformAudio: {e}")
         return
 
-    print("\nRecording devices (microphones):")
-    for device in platform_audio.recording_devices():
-        print(f"  [{device.index}] {device.name}")
-        print(f"      ID: {device.id}")
+    try:
+        print("\nRecording devices (microphones):")
+        for device in platform_audio.recording_devices():
+            print(f"  [{device.index}] {device.name}")
+            print(f"      ID: {device.id}")
 
-    print("\nPlayout devices (speakers):")
-    for device in platform_audio.playout_devices():
-        print(f"  [{device.index}] {device.name}")
-        print(f"      ID: {device.id}")
+        print("\nPlayout devices (speakers):")
+        for device in platform_audio.playout_devices():
+            print(f"  [{device.index}] {device.name}")
+            print(f"      ID: {device.id}")
 
-    print()
+        print()
+    finally:
+        platform_audio.close()
 
 
 async def main(args: argparse.Namespace) -> None:
@@ -123,6 +126,7 @@ async def main(args: argparse.Namespace) -> None:
             logging.warning(f"Failed to select speaker: {e}")
 
     room = rtc.Room()
+    source = None
 
     # dB level monitoring (mic only)
     mic_db_queue: queue.Queue[float] = queue.Queue()
@@ -236,6 +240,10 @@ async def monitor_mic_db():
             await room.disconnect()
         except Exception:
             pass
+        # Clean up PlatformAudio resources
+        if source is not None:
+            source.close()
+        platform_audio.close()
 
 
 if __name__ == "__main__":

examples/local_audio/publish_mic.py

@@ -54,12 +54,15 @@ def list_audio_devices() -> None:
         print(f"Failed to initialize PlatformAudio: {e}")
         return
 
-    print("\nRecording devices (microphones):")
-    for device in platform_audio.recording_devices():
-        print(f"  [{device.index}] {device.name}")
-        print(f"      ID: {device.id}")
+    try:
+        print("\nRecording devices (microphones):")
+        for device in platform_audio.recording_devices():
+            print(f"  [{device.index}] {device.name}")
+            print(f"      ID: {device.id}")
 
-    print()
+        print()
+    finally:
+        platform_audio.close()
 
 
 async def main(args: argparse.Namespace) -> None:
@@ -95,6 +98,7 @@ async def main(args: argparse.Namespace) -> None:
             logging.warning(f"Failed to select microphone: {e}")
 
     room = rtc.Room()
+    source = None
 
     # dB level monitoring
     mic_db_queue: queue.Queue[float] = queue.Queue()
@@ -170,6 +174,10 @@ async def monitor_mic_db():
             await room.disconnect()
         except Exception:
             pass
+        # Clean up PlatformAudio resources
+        if source is not None:
+            source.close()
+        platform_audio.close()
 
 
 if __name__ == "__main__":

livekit-rtc/livekit/rtc/platform_audio.py

@@ -146,6 +146,12 @@ class PlatformAudioSource:
 
     Note: This class is created via PlatformAudio.create_audio_source() and should
     not be instantiated directly.
+
+    Resource Management:
+        Call `close()` when done to immediately release native resources. If not
+        called, resources are released when the object is garbage collected, but
+        GC timing is non-deterministic and may cause issues on some platforms
+        (especially Windows) where audio device handles must be released promptly.
     """
 
     def __init__(self, ffi_handle: FfiHandle, info: proto_audio_frame.AudioSourceInfo):
@@ -157,6 +163,27 @@ def _handle(self) -> int:
         """Internal FFI handle for use with LocalAudioTrack.create_audio_track()."""
         return self._ffi_handle.handle
 
+    def close(self) -> None:
+        """Release the native audio source resources.
+
+        Call this method when you are done using the audio source to immediately
+        release the underlying native handle. This is especially important on
+        Windows where audio device handles must be released promptly to avoid
+        interfering with other audio operations.
+
+        If `close()` is not called, resources will be released when the object
+        is garbage collected. However, Python's garbage collection timing is
+        non-deterministic, which can lead to:
+        - Audio device contention if creating new audio sources before old ones
+          are collected
+        - Test failures when running multiple audio tests in sequence
+        - Resource leaks in long-running applications that frequently create
+          and discard audio sources
+
+        It is safe to call `close()` multiple times; subsequent calls are no-ops.
+        """
+        self._ffi_handle.dispose()
+
 
 class PlatformAudio:
     """Platform audio device management via WebRTC's Audio Device Module (ADM).
@@ -185,12 +212,18 @@ class PlatformAudio:
         source = platform_audio.create_audio_source()
         track = rtc.LocalAudioTrack.create_audio_track("mic", source)
         await room.local_participant.publish_track(track)
+
+        # When done, close resources
+        source.close()
+        platform_audio.close()
         ```
 
-    Note:
-        The PlatformAudio instance must be kept alive while audio is needed.
-        When all PlatformAudio instances are garbage collected, the ADM is
-        automatically disabled.
+    Resource Management:
+        Call `close()` when done to immediately release native ADM resources.
+        If not called, resources are released via garbage collection, but GC
+        timing is non-deterministic. On Windows especially, failing to promptly
+        release ADM resources can cause audio device contention and interfere
+        with subsequent audio operations (including synthetic AudioSource usage).
     """
 
     def __init__(self) -> None:
@@ -353,3 +386,41 @@ def create_audio_source(
             FfiHandle(source_info.handle.id),
             source_info,
         )
+
+    def close(self) -> None:
+        """Release the native Audio Device Module resources.
+
+        Call this method when you are done using PlatformAudio to immediately
+        release the underlying ADM handle and associated native resources.
+
+        Why call close() explicitly?
+            Python's garbage collection is non-deterministic. If you rely on GC
+            to clean up PlatformAudio, the ADM may remain active longer than
+            expected. This can cause problems on some platforms (especially
+            Windows) where:
+
+            - Audio device handles are held longer than necessary, preventing
+              other applications or audio subsystems from accessing the devices
+            - Subsequent audio operations (including synthetic AudioSource) may
+              fail or behave unexpectedly due to ADM still being active
+            - Tests running in sequence may interfere with each other if the
+              previous test's ADM resources haven't been collected yet
+
+        What happens if close() is not called?
+            Resources will eventually be released when the PlatformAudio object
+            is garbage collected. This works fine in simple applications where
+            the object goes out of scope and is collected promptly. However, in
+            these scenarios you should call close() explicitly:
+
+            - Running multiple tests that use audio
+            - Switching between PlatformAudio and synthetic AudioSource
+            - Long-running applications that create/destroy audio resources
+            - Applications where prompt device release is important
+
+        It is safe to call `close()` multiple times; subsequent calls are no-ops.
+
+        Note:
+            Always close PlatformAudioSource instances before closing the parent
+            PlatformAudio instance.
+        """
+        self._ffi_handle.dispose()

tests/rtc/test_platform_audio.py

@@ -16,6 +16,14 @@
 _platform_audio_error: Optional[str] = None
 
 
+def _dispose_track(track: rtc.Track) -> None:
+    """Release track handles created only for local PlatformAudio tests.
+
+    Note: Track doesn't have a public close() method yet, so we use the internal API.
+    """
+    track._ffi_handle.dispose()
+
+
 def _check_platform_audio_available() -> tuple[bool, Optional[str]]:
     """Check if PlatformAudio can be initialized on this system."""
     global _platform_audio_available, _platform_audio_error
@@ -27,8 +35,7 @@ def _check_platform_audio_available() -> tuple[bool, Optional[str]]:
         pa = rtc.PlatformAudio()
         _platform_audio_available = True
         _platform_audio_error = None
-        # Keep reference to avoid cleanup issues
-        del pa
+        pa.close()
     except rtc.PlatformAudioError as e:
         _platform_audio_available = False
         _platform_audio_error = str(e)
@@ -60,8 +67,10 @@ def platform_audio():
         pytest.skip(f"PlatformAudio not available: {error}")
 
     pa = rtc.PlatformAudio()
-    yield pa
-    # Cleanup handled by garbage collection
+    try:
+        yield pa
+    finally:
+        pa.close()
 
 
 class TestPlatformAudioCreation:
@@ -79,9 +88,12 @@ def test_platform_audio_multiple_instances(self, platform_audio):
             pytest.skip(f"PlatformAudio not available: {error}")
 
         pa2 = rtc.PlatformAudio()
-        assert pa2 is not None
-        # Both should work
-        assert platform_audio is not None
+        try:
+            assert pa2 is not None
+            # Both should work
+            assert platform_audio is not None
+        finally:
+            pa2.close()
 
 
 class TestDeviceEnumeration:
@@ -197,8 +209,11 @@ class TestAudioSourceCreation:
     def test_create_audio_source_default_options(self, platform_audio):
         """Test creating an audio source with default options."""
         source = platform_audio.create_audio_source()
-        assert source is not None
-        assert isinstance(source, rtc.PlatformAudioSource)
+        try:
+            assert source is not None
+            assert isinstance(source, rtc.PlatformAudioSource)
+        finally:
+            source.close()
 
     def test_create_audio_source_custom_options(self, platform_audio):
         """Test creating an audio source with custom options."""
@@ -209,8 +224,11 @@ def test_create_audio_source_custom_options(self, platform_audio):
             prefer_hardware=False,
         )
         source = platform_audio.create_audio_source(options)
-        assert source is not None
-        assert isinstance(source, rtc.PlatformAudioSource)
+        try:
+            assert source is not None
+            assert isinstance(source, rtc.PlatformAudioSource)
+        finally:
+            source.close()
 
     def test_create_audio_source_all_processing_disabled(self, platform_audio):
         """Test creating an audio source with all processing disabled."""
@@ -220,24 +238,35 @@ def test_create_audio_source_all_processing_disabled(self, platform_audio):
             auto_gain_control=False,
         )
         source = platform_audio.create_audio_source(options)
-        assert source is not None
+        try:
+            assert source is not None
+        finally:
+            source.close()
 
     def test_audio_source_has_handle(self, platform_audio):
         """Test that created audio source has a valid internal handle."""
         source = platform_audio.create_audio_source()
-        # The _handle property is used internally for track creation
-        assert hasattr(source, "_handle")
-        assert source._handle > 0
+        try:
+            # The _handle property is used internally for track creation
+            assert hasattr(source, "_handle")
+            assert source._handle > 0
+        finally:
+            source.close()
 
     def test_create_multiple_audio_sources(self, platform_audio):
         """Test creating multiple audio sources from the same PlatformAudio."""
         source1 = platform_audio.create_audio_source()
-        source2 = platform_audio.create_audio_source()
-
-        assert source1 is not None
-        assert source2 is not None
-        # Each source should have a unique handle
-        assert source1._handle != source2._handle
+        source2 = None
+        try:
+            source2 = platform_audio.create_audio_source()
+            assert source1 is not None
+            assert source2 is not None
+            # Each source should have a unique handle
+            assert source1._handle != source2._handle
+        finally:
+            source1.close()
+            if source2 is not None:
+                source2.close()
 
 
 class TestPlatformAudioOptions:
@@ -291,8 +320,13 @@ class TestIntegrationWithTrack:
     def test_create_track_from_platform_audio_source(self, platform_audio):
         """Test creating a LocalAudioTrack from PlatformAudioSource."""
         source = platform_audio.create_audio_source()
-        track = rtc.LocalAudioTrack.create_audio_track("test-mic", source)
-
-        assert track is not None
-        assert track.name == "test-mic"
-        assert track.kind == rtc.TrackKind.KIND_AUDIO
+        track = None
+        try:
+            track = rtc.LocalAudioTrack.create_audio_track("test-mic", source)
+            assert track is not None
+            assert track.name == "test-mic"
+            assert track.kind == rtc.TrackKind.KIND_AUDIO
+        finally:
+            if track is not None:
+                _dispose_track(track)
+            source.close()