add and export NoiseCancellationOptions dataclass

Author: typester

livekit-rtc/livekit/rtc/__init__.py

@@ -36,7 +36,7 @@
 from ._proto.video_frame_pb2 import VideoBufferType, VideoCodec, VideoRotation
 from .audio_frame import AudioFrame
 from .audio_source import AudioSource
-from .audio_stream import AudioFrameEvent, AudioStream
+from .audio_stream import AudioFrameEvent, AudioStream, NoiseCancellationOptions
 from .audio_filter import AudioFilter
 from .chat import ChatManager, ChatMessage
 from .e2ee import (
@@ -110,6 +110,7 @@
     "AudioFrame",
     "AudioSource",
     "AudioStream",
+    "NoiseCancellationOptions",
     "AudioFilter",
     "AudioFrameEvent",
     "LocalParticipant",

livekit-rtc/livekit/rtc/audio_stream.py

@@ -40,6 +40,12 @@ class AudioFrameEvent:
     frame: AudioFrame
 
 
+@dataclass
+class NoiseCancellationOptions:
+    module_id: str
+    options: dict[str, Any]
+
+
 class AudioStream:
     """An asynchronous audio stream for receiving audio frames from a participant or track.
 
@@ -55,7 +61,7 @@ def __init__(
         capacity: int = 0,
         sample_rate: int = 48000,
         num_channels: int = 1,
-        noise_cancellation: Optional[Tuple[str, dict[str, Any]]] = None,
+        noise_cancellation: Optional[NoiseCancellationOptions] = None,
         **kwargs,
     ) -> None:
         """Initialize an `AudioStream` instance.
@@ -69,6 +75,10 @@ def __init__(
             sample_rate (int, optional): The sample rate for the audio stream in Hz.
                 Defaults to 48000.
             num_channels (int, optional): The number of audio channels. Defaults to 1.
+            noise_cancellation (Optional[NoiseCancellationOptions], optional):
+                If noise cancellation is used, pass a `NoiseCancellationOptions` instance
+                created by the noise cancellation module.
+
         Example:
             ```python
             audio_stream = AudioStream(
@@ -94,8 +104,8 @@ def __init__(
         self._audio_filter_module = None
         self._audio_filter_options = None
         if noise_cancellation is not None:
-            self._audio_filter_module = noise_cancellation[0]
-            self._audio_filter_options = noise_cancellation[1]
+            self._audio_filter_module = noise_cancellation.module_id
+            self._audio_filter_options = noise_cancellation.options
         self._task = self._loop.create_task(self._run())
         self._task.add_done_callback(task_done_logger)
 
@@ -119,7 +129,7 @@ def from_participant(
         capacity: int = 0,
         sample_rate: int = 48000,
         num_channels: int = 1,
-        noise_cancellation: Optional[Tuple[str, dict[str, Any]]] = None,
+        noise_cancellation: Optional[NoiseCancellationOptions] = None,
     ) -> AudioStream:
         """Create an `AudioStream` from a participant's audio track.
 
@@ -130,6 +140,9 @@ def from_participant(
             capacity (int, optional): The capacity of the internal frame queue. Defaults to 0 (unbounded).
             sample_rate (int, optional): The sample rate for the audio stream in Hz. Defaults to 48000.
             num_channels (int, optional): The number of audio channels. Defaults to 1.
+            noise_cancellation (Optional[NoiseCancellationOptions], optional):
+                If noise cancellation is used, pass a `NoiseCancellationOptions` instance
+                created by the noise cancellation module.
 
         Returns:
             AudioStream: An instance of `AudioStream` that can be used to receive audio frames.
@@ -164,7 +177,7 @@ def from_track(
         capacity: int = 0,
         sample_rate: int = 48000,
         num_channels: int = 1,
-        noise_cancellation: Optional[Tuple[str, dict[str, Any]]] = None,
+        noise_cancellation: Optional[NoiseCancellationOptions] = None,
     ) -> AudioStream:
         """Create an `AudioStream` from an existing audio track.
 
@@ -174,6 +187,9 @@ def from_track(
             capacity (int, optional): The capacity of the internal frame queue. Defaults to 0 (unbounded).
             sample_rate (int, optional): The sample rate for the audio stream in Hz. Defaults to 48000.
             num_channels (int, optional): The number of audio channels. Defaults to 1.
+            noise_cancellation (Optional[NoiseCancellationOptions], optional):
+                If noise cancellation is used, pass a `NoiseCancellationOptions` instance
+                created by the noise cancellation module.
 
         Returns:
             AudioStream: An instance of `AudioStream` that can be used to receive audio frames.