fix: rename noise_cancellation_leave_open -> auto_close_noise_cancellation

Author: 1egoman

livekit-rtc/livekit/rtc/audio_stream.py

@@ -65,7 +65,7 @@ def __init__(
         num_channels: int = 1,
         frame_size_ms: int | None = None,
         noise_cancellation: Optional[NoiseCancellationOptions | FrameProcessor[AudioFrame]] = None,
-        noise_cancellation_leave_open: bool = False,
+        auto_close_noise_cancellation: bool = True,
         **kwargs: Any,
     ) -> None:
         """Initialize an `AudioStream` instance.
@@ -82,9 +82,9 @@ def __init__(
             noise_cancellation (Optional[NoiseCancellationOptions | FrameProcessor[AudioFrame]], optional):
                 If noise cancellation is used, pass a `NoiseCancellationOptions` or `FrameProcessor[AudioFrame]` instance
                 created by the noise cancellation module.
-            noise_cancellation_leave_open (bool):
-                When the audio stream closes, leaves the FrameProcessor in an unclosed state so it
-                can be used with another AudioStream.
+            auto_close_noise_cancellation (bool):
+                When the audio stream closes, should the FrameProcessor's close method be run? If
+                False, then the frame processor can be reused with another AudioStream.
 
         Example:
             ```python
@@ -117,13 +117,13 @@ def __init__(
         self._audio_filter_module: str | None = None
         self._audio_filter_options: dict[str, Any] | None = None
         self._processor: FrameProcessor[AudioFrame] | None = None
-        self._processor_leave_open = False
+        self._processor_auto_close = True
         if isinstance(noise_cancellation, NoiseCancellationOptions):
             self._audio_filter_module = noise_cancellation.module_id
             self._audio_filter_options = noise_cancellation.options
         elif isinstance(noise_cancellation, FrameProcessor):
             self._processor = noise_cancellation
-            self._processor_leave_open = noise_cancellation_leave_open
+            self._processor_auto_close = auto_close_noise_cancellation
 
         self._task = self._loop.create_task(self._run())
         self._task.add_done_callback(task_done_logger)
@@ -153,7 +153,7 @@ def from_participant(
         num_channels: int = 1,
         frame_size_ms: int | None = None,
         noise_cancellation: Optional[NoiseCancellationOptions | FrameProcessor[AudioFrame]] = None,
-        noise_cancellation_leave_open: bool = False,
+        auto_close_noise_cancellation: bool = False,
     ) -> AudioStream:
         """Create an `AudioStream` from a participant's audio track.
 
@@ -191,7 +191,7 @@ def from_participant(
             num_channels=num_channels,
             frame_size_ms=frame_size_ms,
             noise_cancellation=noise_cancellation,
-            noise_cancellation_leave_open=noise_cancellation_leave_open,
+            auto_close_noise_cancellation=auto_close_noise_cancellation,
         )
 
     @classmethod
@@ -205,7 +205,7 @@ def from_track(
         num_channels: int = 1,
         frame_size_ms: int | None = None,
         noise_cancellation: Optional[NoiseCancellationOptions | FrameProcessor[AudioFrame]] = None,
-        noise_cancellation_leave_open: bool = False,
+        auto_close_noise_cancellation: bool = False,
     ) -> AudioStream:
         """Create an `AudioStream` from an existing audio track.
 
@@ -218,7 +218,7 @@ def from_track(
             noise_cancellation (Optional[NoiseCancellationOptions | FrameProcessor[AudioFrame]], optional):
                 If noise cancellation is used, pass a `NoiseCancellationOptions` or `FrameProcessor[AudioFrame]` instance
                 created by the noise cancellation module.
-            noise_cancellation_leave_open (bool):
+            auto_close_noise_cancellation (bool):
                 When the audio stream closes, leaves the FrameProcessor in an unclosed state so it
                 can be used with another AudioStream.
 
@@ -242,7 +242,7 @@ def from_track(
             num_channels=num_channels,
             frame_size_ms=frame_size_ms,
             noise_cancellation=noise_cancellation,
-            noise_cancellation_leave_open=noise_cancellation_leave_open,
+            auto_close_noise_cancellation=auto_close_noise_cancellation,
         )
 
     def __del__(self) -> None:
@@ -323,7 +323,7 @@ async def aclose(self) -> None:
             self._track._unregister_audio_stream(self)
         self._ffi_handle.dispose()
         await self._task
-        if self._processor is not None and not self._processor_leave_open:
+        if self._processor is not None and self._processor_auto_close:
             self._processor._close()
 
     def _is_event(self, e: proto_ffi.FfiEvent) -> bool:

livekit-rtc/tests/test_audio_stream_room_lifecycle.py

@@ -7,7 +7,7 @@
   - `_on_stream_info_updated` / `_on_credentials_updated` on every room transition
     or token refresh,
   - `_on_stream_info_cleared` / `_on_credentials_cleared` when the track leaves a room,
-and that `AudioStream.aclose()` honors `noise_cancellation_leave_open`.
+and that `AudioStream.aclose()` honors `auto_close_noise_cancellation`.
 """
 
 from __future__ import annotations
@@ -91,11 +91,11 @@ def _make_closeable_stream(
     *,
     track: Optional[rtc.Track] = None,
     processor: Optional[rtc.FrameProcessor[rtc.AudioFrame]] = None,
-    leave_open: bool = False,
+    auto_close: bool = True,
 ) -> rtc.AudioStream:
     """Extends _make_stream with the minimal state `aclose()` touches."""
     stream = _make_stream(track=track, processor=processor)
-    stream._processor_leave_open = leave_open
+    stream._processor_auto_close = auto_close
     stream._task = asyncio.ensure_future(asyncio.sleep(0))
     stream._ffi_handle = cast(Any, SimpleNamespace(dispose=lambda: None))
     return stream
@@ -446,24 +446,24 @@ def test_unregister_one_of_many_streams_only_fans_out_to_remaining() -> None:
 
 
 @pytest.mark.asyncio
-async def test_aclose_closes_processor_when_leave_open_false() -> None:
+async def test_aclose_closes_processor_when_auto_close_true() -> None:
     """`aclose()` calls `_close()` on the attached FrameProcessor when
-    `noise_cancellation_leave_open` is False (the default)."""
+    `auto_close_noise_cancellation` is True (the default)."""
     processor = _RecordingProcessor()
-    stream = _make_closeable_stream(processor=processor, leave_open=False)
+    stream = _make_closeable_stream(processor=processor, auto_close=True)
 
     await stream.aclose()
 
     assert processor.close_calls == 1
 
 
 @pytest.mark.asyncio
-async def test_aclose_leaves_processor_open_when_leave_open_true() -> None:
-    """`aclose()` does NOT call `_close()` when `noise_cancellation_leave_open`
-    is True — the agents SDK path for sharing one processor across many track
+async def test_aclose_leaves_processor_open_when_auto_close_false() -> None:
+    """`aclose()` does NOT call `_close()` when `auto_close_noise_cancellation`
+    is False — the agents SDK path for sharing one processor across many track
     attach/detach cycles."""
     processor = _RecordingProcessor()
-    stream = _make_closeable_stream(processor=processor, leave_open=True)
+    stream = _make_closeable_stream(processor=processor, auto_close=False)
 
     await stream.aclose()