flet-audio-recorder 0.2.0.dev18__py3-none-any.whl → 0.2.0.dev55__py3-none-any.whl

flet_audio_recorder/__init__.py

@@ -1,6 +1,12 @@
-from flet_audio_recorder.audio_recorder import (
+from .audio_recorder import AudioRecorder
+from .types import (
+    AndroidAudioSource,
+    AndroidRecorderConfiguration,
     AudioEncoder,
-    AudioRecorder,
+    AudioRecorderConfiguration,
     AudioRecorderState,
     AudioRecorderStateChangeEvent,
+    InputDevice,
+    IosAudioCategoryOption,
+    IosRecorderConfiguration,
 )

flet_audio_recorder/audio_recorder.py

@@ -1,113 +1,52 @@
-import json
-from enum import Enum
-from typing import Any, Optional
+import asyncio
+from dataclasses import field
+from typing import List, Optional
 
-from flet.core.control import Control, OptionalNumber
-from flet.core.control_event import ControlEvent
-from flet.core.event_handler import EventHandler
-from flet.core.ref import Ref
-from flet.core.types import OptionalEventCallable
-from flet.utils import deprecated
+import flet as ft
 
+from .types import (
+    AudioEncoder,
+    AudioRecorderConfiguration,
+    AudioRecorderStateChangeEvent,
+    InputDevice,
+)
 
-class AudioRecorderState(Enum):
-    """
-        The available AudioRecorder states are:
-
-    - `STOPPED`
-    - `RECORDING`
-    - `PAUSED`
-    """
-    STOPPED = "stopped"
-    RECORDING = "recording"
-    PAUSED = "paused"
+__all__ = ["AudioRecorder"]
 
 
-class AudioRecorderStateChangeEvent(ControlEvent):
-    def __init__(self, e: ControlEvent):
-        """The current state of the audio recorder.
+@ft.control("AudioRecorder")
+class AudioRecorder(ft.Service):
+    """
+    A control that allows you to record audio from your device.
 
-        Value is of type [AudioRecorderState](audiorecorderstate.md)."""
-        super().__init__(e.target, e.name, e.data, e.control, e.page)
-        self.state: AudioRecorderState = AudioRecorderState(e.data)
+    This control can record audio using different audio encoders and also allows configuration
+    of various audio recording parameters such as noise suppression, echo cancellation, and more.
 
+    Note:
+        This control is non-visual and should be added to `Page.services` list before it can be used.
+    """
 
-class AudioEncoder(Enum):
+    configuration: AudioRecorderConfiguration = field(
+        default_factory=lambda: AudioRecorderConfiguration()
+    )
     """
-    The `AudioEncoder` enum represents the different audio encoders supported by the audio recorder.
-
-    The available encoders are:
-
-    - `AACLC`: Advanced Audio Codec Low Complexity. A commonly used encoder for streaming and general audio recording.
-    - `AACELD`: Advanced Audio Codec Enhanced Low Delay. Suitable for low-latency applications like VoIP.
-    - `AACHE`: Advanced Audio Codec High Efficiency. Optimized for high-quality audio at lower bit rates.
-    - `AMRNB`: Adaptive Multi-Rate Narrow Band. Used for speech audio in mobile communication.
-    - `AMRWB`: Adaptive Multi-Rate Wide Band. Used for higher-quality speech audio.
-    - `OPUS`: A codec designed for both speech and audio applications, known for its versatility.
-    - `FLAC`: Free Lossless Audio Codec. Provides high-quality lossless audio compression.
-    - `WAV`: Standard audio format used for raw, uncompressed audio data.
-    - `PCM16BITS`: Pulse Code Modulation with 16-bit depth, used for high-fidelity audio.
+    The default configuration of the audio recorder.
     """
-    AACLC = "aacLc"
-    AACELD = "aacEld"
-    AACHE = "aacHe"
-    AMRNB = "amrNb"
-    AMRWB = "amrWb"
-    OPUS = "opus"
-    FLAC = "flac"
-    WAV = "wav"
-    PCM16BITS = "pcm16bits"
 
-
-
-class AudioRecorder(Control):
+    on_state_change: ft.OptionalEventHandler[
+        AudioRecorderStateChangeEvent["AudioRecorder"]
+    ] = None
     """
-    A control that allows you to record audio from your device.
-
-    This control can record audio using different audio encoders and also allows configuration
-    of various audio recording parameters such as noise suppression, echo cancellation, and more.
+    Event handler that is called when the state of the audio recorder changes.
+    
+    Event handler argument is of type [`AudioRecorderStateChangeEvent`][(p).].
     """
 
-    def __init__(
+    async def start_recording_async(
         self,
-        audio_encoder: Optional[AudioEncoder] = None,
-        suppress_noise: Optional[bool] = None,
-        cancel_echo: Optional[bool] = None,
-        auto_gain: Optional[bool] = None,
-        channels_num: OptionalNumber = None,
-        sample_rate: OptionalNumber = None,
-        bit_rate: OptionalNumber = None,
-        on_state_changed: OptionalEventCallable[AudioRecorderStateChangeEvent] = None,
-        #
-        # Control
-        #
-        ref: Optional[Ref] = None,
-        data: Any = None,
-    ):
-        Control.__init__(
-            self,
-            ref=ref,
-            data=data,
-        )
-        self.__on_state_changed = EventHandler(
-            lambda e: AudioRecorderStateChangeEvent(e)
-        )
-        self._add_event_handler("state_changed", self.__on_state_changed.get_handler())
-
-        self.audio_encoder = audio_encoder
-        self.suppress_noise = suppress_noise
-        self.cancel_echo = cancel_echo
-        self.auto_gain = auto_gain
-        self.channels_num = channels_num
-        self.sample_rate = sample_rate
-        self.bit_rate = bit_rate
-        self.on_state_changed = on_state_changed
-
-    def _get_control_name(self):
-        return "audiorecorder"
-
-    def start_recording(
-        self, output_path: str = None, wait_timeout: Optional[float] = 10
+        output_path: Optional[str] = None,
+        configuration: Optional[AudioRecorderConfiguration] = None,
+        timeout: Optional[float] = 10,
     ) -> bool:
         """
         Starts recording audio and saves it to the specified output path.
@@ -115,388 +54,176 @@ class AudioRecorder(Control):
         If not on the web, the `output_path` parameter must be provided.
 
         Args:
-            output_path: The file path where the audio will be saved. It must be specified if not on web.
-            wait_timeout: The time in seconds to wait for the recording to start. Default is 10.
-
+            output_path: The file path where the audio will be saved.
+                It must be specified if not on web.
+            configuration: The configuration for the audio recorder.
+                If `None`, the `AudioRecorder.configuration` will be used.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
         Returns:
-            bool: `True` if recording was successfully started, `False` otherwise.
+            `True` if recording was successfully started, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
         """
         assert (
             self.page.web or output_path
-        ), "output_path must be provided when not on web"
-        started = self.invoke_method(
-            "start_recording",
-            {"outputPath": output_path},
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
+        ), "output_path must be provided on platforms other than web"
+        return await self._invoke_method_async(
+            method_name="start_recording",
+            arguments={
+                "output_path": output_path,
+                "configuration": configuration
+                if configuration is not None
+                else self.configuration,
+            },
+            timeout=timeout,
         )
-        return started == "true"
 
-    def is_recording(self, wait_timeout: Optional[float] = 5) -> bool:
+    async def is_recording_async(self, timeout: Optional[float] = 10) -> bool:
         """
         Checks whether the audio recorder is currently recording.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
+            timeout: The maximum amount of time (in seconds) to wait for a response.
         Returns:
-            bool: `True` if the recorder is currently recording, `False` otherwise.
+            `True` if the recorder is currently recording, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        recording = self.invoke_method(
-            "is_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return recording == "true"
+        return await self._invoke_method_async("is_recording", timeout=timeout)
 
-    async def is_recording_async(self, wait_timeout: Optional[float] = 5) -> bool:
-        """
-        Asynchronously checks whether the audio recorder is currently recording.
-
-        Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
-        Returns:
-            bool: `True` if the recorder is currently recording, `False` otherwise.
-        """
-        recording = await self.invoke_method_async(
-            "is_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return recording == "true"
-
-    def stop_recording(self, wait_timeout: Optional[float] = 5) -> Optional[str]:
+    async def stop_recording_async(self, timeout: Optional[float] = 10) -> Optional[str]:
         """
         Stops the audio recording and optionally returns the path to the saved file.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
+            timeout: The maximum amount of time (in seconds) to wait for a response.
         Returns:
-            Optional[str]: The file path where the audio was saved or `None` if not applicable.
+            The file path where the audio was saved or `None` if not applicable.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        return self.invoke_method(
-            "stop_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
+        return await self._invoke_method_async("stop_recording", timeout=timeout)
 
-    async def stop_recording_async(
-        self, wait_timeout: Optional[float] = 10
-    ) -> Optional[str]:
+    async def cancel_recording_async(self, timeout: Optional[float] = 10):
         """
-        Asynchronously stops the audio recording and optionally returns the path to the saved file.
+        Cancels the current audio recording.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 10.
-
-        Returns:
-            Optional[str]: The file path where the audio was saved or `None` if not applicable.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        return await self.invoke_method_async(
-            "stop_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
+        await self._invoke_method_async("cancel_recording", timeout=timeout)
 
-    def cancel_recording(self, wait_timeout: Optional[float] = 5) -> None:
+    def cancel_recording(self, timeout: Optional[float] = 10):
         """
         Cancels the current audio recording.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        self.invoke_method(
-            "cancel_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
+        asyncio.create_task(self.cancel_recording_async(timeout=timeout))
 
-    def resume_recording(self):
+    async def resume_recording_async(self, timeout: Optional[float] = 10):
         """
         Resumes a paused audio recording.
-        """
-        self.invoke_method("resume_recording")
-
-    def pause_recording(self):
-        """
-        Pauses the ongoing audio recording.
-        """
-        self.invoke_method("pause_recording")
-
-    def is_paused(self, wait_timeout: Optional[float] = 5) -> bool:
-        """
-        Checks whether the audio recorder is currently paused.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
-        Returns:
-            bool: `True` if the recorder is paused, `False` otherwise.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        paused = self.invoke_method(
-            "is_paused",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return paused == "true"
+        await self._invoke_method_async("resume_recording", timeout=timeout)
 
-    async def is_paused_async(self, wait_timeout: Optional[float] = 5) -> bool:
+    def resume_recording(self, timeout: Optional[float] = 10):
         """
-        Asynchronously checks whether the audio recorder is currently paused.
+        Resumes a paused audio recording.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
-        Returns:
-            bool: `True` if the recorder is paused, `False` otherwise.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        supported = await self.invoke_method_async(
-            "is_paused",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return supported == "true"
+        asyncio.create_task(self.resume_recording_async(timeout=timeout))
 
-    def is_supported_encoder(
-        self, encoder: AudioEncoder, wait_timeout: Optional[float] = 5
-    ) -> bool:
+    async def pause_recording_async(self, timeout: Optional[float] = 10):
         """
-        Checks if the given audio encoder is supported by the recorder.
+        Pauses the ongoing audio recording.
 
         Args:
-            encoder: The audio encoder to check.
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
-        Returns:
-            bool: `True` if the encoder is supported, `False` otherwise.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        supported = self.invoke_method(
-            "is_supported_encoder",
-            {
-                "encoder": (
-                    encoder.value if isinstance(encoder, AudioEncoder) else encoder
-                )
-            },
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return supported == "true"
+        await self._invoke_method_async("pause_recording", timeout=timeout)
 
-    async def is_supported_encoder_async(
-        self, encoder: AudioEncoder, wait_timeout: Optional[float] = 5
-    ) -> bool:
+    def pause_recording(self, timeout: Optional[float] = 10):
         """
-        Asynchronously checks if the given audio encoder is supported by the recorder.
+        Pauses the ongoing audio recording.
 
         Args:
-            encoder: The audio encoder to check.
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
-        Returns:
-            bool: `True` if the encoder is supported, `False` otherwise.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        supported = await self.invoke_method_async(
-            "is_supported_encoder",
-            {
-                "encoder": (
-                    encoder.value if isinstance(encoder, AudioEncoder) else encoder
-                )
-            },
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return supported == "true"
+        asyncio.create_task(self.pause_recording_async(timeout=timeout))
 
-    def get_input_devices(self, wait_timeout: Optional[float] = 5) -> dict:
+    async def is_paused_async(self, timeout: Optional[float] = 10) -> bool:
         """
-        Retrieves the available input devices for recording.
+        Checks whether the audio recorder is currently paused.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
+            timeout: The maximum amount of time (in seconds) to wait for a response.
         Returns:
-            dict: A dictionary of available input devices.
+            `True` if the recorder is paused, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        devices = self.invoke_method(
-            "get_input_devices",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return json.loads(devices)
+        return await self._invoke_method_async("is_paused", timeout=timeout)
 
-    async def get_input_devices_async(self, wait_timeout: Optional[float] = 5) -> dict:
+    async def is_supported_encoder_async(self, encoder: AudioEncoder, timeout: Optional[float] = 10) -> bool:
         """
-        Asynchronously retrieves the available input devices for recording.
+        Checks if the given audio encoder is supported by the recorder.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 5.
-
+            encoder: The audio encoder to check.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
         Returns:
-            dict: A dictionary of available input devices.
+            `True` if the encoder is supported, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        devices = await self.invoke_method_async(
-            "get_input_devices",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
+        return await self._invoke_method_async(
+            "is_supported_encoder", {"encoder": encoder}, timeout=timeout
         )
-        return json.loads(devices)
 
-    def has_permission(self, wait_timeout: Optional[float] = 10) -> bool:
+    async def get_input_devices_async(self, timeout: Optional[float] = 10) -> List[InputDevice]:
         """
-        Checks if the app has permission to record audio.
+        Retrieves the available input devices for recording.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 10.
-
+            timeout: The maximum amount of time (in seconds) to wait for a response.
         Returns:
-            bool: `True` if the app has permission, `False` otherwise.
+            A list of available input devices.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        p = self.invoke_method(
-            "has_permission",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return p == "true"
+        r = await self._invoke_method_async("get_input_devices", timeout=timeout)
+        return [
+            InputDevice(id=device_id, label=label) for device_id, label in r.items()
+        ]
 
-    async def has_permission_async(self, wait_timeout: Optional[float] = 10) -> bool:
+    async def has_permission_async(self, timeout: Optional[float] = 10) -> bool:
         """
-        Asynchronously checks if the app has permission to record audio.
+        Checks if the app has permission to record audio.
 
         Args:
-            wait_timeout: The time in seconds to wait for the result. Default is 10.
-
+            timeout: The maximum amount of time (in seconds) to wait for a response.
         Returns:
-            bool: `True` if the app has permission, `False` otherwise.
-        """
-        p = await self.invoke_method_async(
-            "has_permission",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return p == "true"
-
-    # audio_encoder
-    @property
-    def audio_encoder(self):
-        """
-        The audio encoder to be used for recording.
-
-        Value is of type [`AudioEncoder`](audioencoder.md) 
-        and defaults to `AudioEncoder.WAV`.
-        """
-        return self._get_attr("audioEncoder")
-
-    @audio_encoder.setter
-    def audio_encoder(self, value: Optional[AudioEncoder]):
-        self._set_enum_attr("audioEncoder", value, AudioEncoder)
-
-    # suppress_noise
-    @property
-    def suppress_noise(self) -> bool:
-        """
-        Whether to suppress noise during recording.
-
-        Defaults to `False`.
-
-        If `True`, it reduces the background noise while recording.
-        """
-        return self._get_attr("suppressNoise", data_type="bool", def_value=False)
-
-    @suppress_noise.setter
-    def suppress_noise(self, value: Optional[bool]):
-        self._set_attr("suppressNoise", value)
-
-    # cancel_echo
-    @property
-    def cancel_echo(self) -> bool:
-        """
-        Whether to cancel echo during recording.
-
-        Defaults to `False`.
-
-        If `True`, it reduces or cancels echo during recording.
-        """
-        return self._get_attr("cancelEcho", data_type="bool", def_value=False)
-
-    @cancel_echo.setter
-    def cancel_echo(self, value: Optional[bool]):
-        self._set_attr("cancelEcho", value)
-
-    # auto_gain
-    @property
-    def auto_gain(self) -> bool:
-        """
-        Whether to automatically adjust the audio gain during recording.
-
-        Defaults to `False`.
-
-        If `True`, the audio gain is automatically adjusted to avoid distortion or clipping.
-        """
-        return self._get_attr("autoGain", data_type="bool", def_value=False)
-
-    @auto_gain.setter
-    def auto_gain(self, value: Optional[bool]):
-        self._set_attr("autoGain", value)
-
-    # bit_rate
-    @property
-    def bit_rate(self) -> OptionalNumber:
-        """
-        The bit rate of the audio recording.
-
-        This value is specified in kilobits per second (kbps). Defaults to `None`.
-        """
-        return self._get_attr("bitRate")
-
-    @bit_rate.setter
-    def bit_rate(self, value: OptionalNumber):
-        self._set_attr("bitRate", value)
-
-    # sample_rate
-    @property
-    def sample_rate(self) -> OptionalNumber:
+            `True` if the app has permission, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
         """
-        The sample rate for the audio recording.
-
-        This value is specified in Hertz (Hz). Defaults to `None`.
-        """
-        return self._get_attr("sampleRate")
-
-    @sample_rate.setter
-    def sample_rate(self, value: OptionalNumber):
-        self._set_attr("sampleRate", value)
-
-    # channels_num
-    @property
-    def channels_num(self) -> OptionalNumber:
-        """
-        The number of audio channels for the recording.
-
-        Can be `1` (mono) or `2` (stereo). Defaults to `None`.
-        """
-        return self._get_attr("channels")
-
-    @channels_num.setter
-    def channels_num(self, value: OptionalNumber):
-        if value is None or value in (1, 2):
-            self._set_attr("channels", value)
-
-    # on_state_changed
-    @property
-    def on_state_changed(self):
-        """
-        Event handler that is triggered when the recording state changes.
-
-        This handler should accept an instance of [`AudioRecorderStateChangeEvent`](audiorecorderstatechangeevent.md).
-        """
-        return self.__on_state_changed.handler
-
-    @on_state_changed.setter
-    def on_state_changed(
-        self, handler: OptionalEventCallable[AudioRecorderStateChangeEvent]
-    ):
-        self.__on_state_changed.handler = handler
-
-
+        return await self._invoke_method_async("has_permission", timeout=timeout)