docs

livekit-rtc/livekit/rtc/audio_resampler.py

@@ -20,14 +20,35 @@ class AudioResamplerQuality(str, Enum):
 
 
 class AudioResampler:
+    """
+    A class for resampling audio data from one sample rate to another.
+
+    `AudioResampler` provides functionality to resample audio data from an input sample rate to an output
+    sample rate using the Sox resampling library. It supports multiple channels and configurable resampling quality.
+    """
+
     def __init__(
         self,
         input_rate: int,
         output_rate: int,
         *,
         num_channels: int = 1,
-        quality: AudioResamplerQuality = AudioResamplerQuality.HIGH,
+        quality: AudioResamplerQuality = AudioResamplerQuality.MEDIUM,
     ) -> None:
+        """
+        Initialize an `AudioResampler` instance for resampling audio data.
+
+        Args:
+            input_rate (int): The sample rate of the input audio data (in Hz).
+            output_rate (int): The desired sample rate of the output audio data (in Hz).
+            num_channels (int, optional): The number of audio channels (e.g., 1 for mono, 2 for stereo). Defaults to 1.
+            quality (AudioResamplerQuality, optional): The quality setting for the resampler. Can be one of the
+                `AudioResamplerQuality` enum values: `QUICK`, `LOW`, `MEDIUM`, `HIGH`, `VERY_HIGH`. Higher quality settings
+                result in better audio quality but require more processing power. Defaults to `AudioResamplerQuality.MEDIUM`.
+
+        Raises:
+            Exception: If there is an error creating the resampler.
+        """
         self._input_rate = input_rate
         self._output_rate = output_rate
         self._num_channels = num_channels
@@ -55,6 +76,23 @@ def __init__(
         self._ffi_handle = FfiHandle(resp.new_sox_resampler.resampler.handle.id)
 
     def push(self, data: bytearray | AudioFrame) -> list[AudioFrame]:
+        """
+        Push audio data into the resampler and retrieve any available resampled data.
+
+        This method accepts audio data, resamples it according to the configured input and output rates,
+        and returns any resampled data that is available after processing the input.
+
+        Args:
+            data (bytearray | AudioFrame): The audio data to resample. This can be a `bytearray` containing
+                raw audio bytes in int16le format or an `AudioFrame` object.
+
+        Returns:
+            list[AudioFrame]: A list of `AudioFrame` objects containing the resampled audio data.
+                The list may be empty if no output data is available yet.
+
+        Raises:
+            Exception: If there is an error during resampling.
+        """
         bdata = data if isinstance(data, bytearray) else data.data
 
         req = proto_ffi.FfiRequest()
@@ -85,6 +123,19 @@ def push(self, data: bytearray | AudioFrame) -> list[AudioFrame]:
         ]
 
     def flush(self) -> list[AudioFrame]:
+        """
+        Flush any remaining audio data through the resampler and retrieve the resampled data.
+
+        This method should be called when no more input data will be provided to ensure that all internal
+        buffers are processed and all resampled data is output.
+
+        Returns:
+            list[AudioFrame]: A list of `AudioFrame` objects containing the remaining resampled audio data after flushing.
+                The list may be empty if no output data remains.
+
+        Raises:
+            Exception: If there is an error during flushing.
+        """
         req = proto_ffi.FfiRequest()
         req.flush_sox_resampler.resampler_handle = self._ffi_handle.handle