From 177a477904a1d5762873c6bfadd6a25adcdb7487 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?The=CC=81o=20Monnom?= Date: Thu, 26 Sep 2024 16:16:58 -0700 Subject: [PATCH] docs --- livekit-rtc/livekit/rtc/audio_resampler.py | 53 +++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/livekit-rtc/livekit/rtc/audio_resampler.py b/livekit-rtc/livekit/rtc/audio_resampler.py index e6d10263..1d8c0adf 100644 --- a/livekit-rtc/livekit/rtc/audio_resampler.py +++ b/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