flet-audio-recorder 0.2.0.dev17__py3-none-any.whl → 0.2.0.dev50__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,294 +1,229 @@
-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):
-    STOPPED = "stopped"
-    RECORDING = "recording"
-    PAUSED = "paused"
+__all__ = ["AudioRecorder"]
 
 
-class AudioRecorderStateChangeEvent(ControlEvent):
-    def __init__(self, e: ControlEvent):
-        super().__init__(e.target, e.name, e.data, e.control, e.page)
-        self.state: AudioRecorderState = AudioRecorderState(e.data)
-
-
-class AudioEncoder(Enum):
-    AACLC = "aacLc"
-    AACELD = "aacEld"
-    AACHE = "aacHe"
-    AMRNB = "amrNb"
-    AMRWB = "amrWb"
-    OPUS = "opus"
-    FLAC = "flac"
-    WAV = "wav"
-    PCM16BITS = "pcm16bits"
+@ft.control("AudioRecorder")
+class AudioRecorder(ft.Service):
+    """
+    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.
 
-class AudioRecorder(Control):
+    Note:
+        This control is non-visual and should be added to `Page.services` list before it can be used.
     """
-    A control that allows you to record audio from your device.
 
-    -----
+    configuration: AudioRecorderConfiguration = field(
+        default_factory=lambda: AudioRecorderConfiguration()
+    )
+    """
+    The default configuration of the audio recorder.
+    """
 
-    Online docs: https://flet.dev/docs/controls/audiorecorder
+    on_state_change: ft.OptionalEventHandler[
+        AudioRecorderStateChangeEvent["AudioRecorder"]
+    ] = None
+    """
+    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.
+
+        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.
+            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:
+            `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,
-        )
-        return started == "true"
-
-    def is_recording(self, wait_timeout: Optional[float] = 5) -> bool:
-        recording = self.invoke_method(
-            "is_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return recording == "true"
-
-    async def is_recording_async(self, wait_timeout: Optional[float] = 5) -> bool:
-        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]:
-        return self.invoke_method(
-            "stop_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-
-    async def stop_recording_async(
-        self, wait_timeout: Optional[float] = 10
-    ) -> Optional[str]:
-        return await self.invoke_method_async(
-            "stop_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-
-    def cancel_recording(self, wait_timeout: Optional[float] = 5) -> None:
-        self.invoke_method(
-            "cancel_recording",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-
-    def resume_recording(self):
-        self.invoke_method("resume_recording")
-
-    def pause_recording(self):
-        self.invoke_method("pause_recording")
-
-    def is_paused(self, wait_timeout: Optional[float] = 5) -> bool:
-        paused = self.invoke_method(
-            "is_paused",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return paused == "true"
-
-    async def is_paused_async(self, wait_timeout: Optional[float] = 5) -> bool:
-        supported = await self.invoke_method_async(
-            "is_paused",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return supported == "true"
-
-    def is_supported_encoder(
-        self, encoder: AudioEncoder, wait_timeout: Optional[float] = 5
-    ) -> bool:
-        supported = self.invoke_method(
-            "is_supported_encoder",
-            {
-                "encoder": (
-                    encoder.value if isinstance(encoder, AudioEncoder) else encoder
-                )
+        ), "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,
             },
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return supported == "true"
-
-    async def is_supported_encoder_async(
-        self, encoder: AudioEncoder, wait_timeout: Optional[float] = 5
-    ) -> bool:
-        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"
-
-    def get_input_devices(self, wait_timeout: Optional[float] = 5) -> dict:
-        devices = self.invoke_method(
-            "get_input_devices",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return json.loads(devices)
-
-    async def get_input_devices_async(self, wait_timeout: Optional[float] = 5) -> dict:
-        devices = await self.invoke_method_async(
-            "get_input_devices",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return json.loads(devices)
-
-    def has_permission(self, wait_timeout: Optional[float] = 10) -> bool:
-        p = self.invoke_method(
-            "has_permission",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return p == "true"
-
-    async def has_permission_async(self, wait_timeout: Optional[float] = 10) -> bool:
-        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):
-        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:
-        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:
-        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:
-        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:
-        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:
-        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:
-        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):
-        return self.__on_state_changed.handler
-
-    @on_state_changed.setter
-    def on_state_changed(
-        self, handler: OptionalEventCallable[AudioRecorderStateChangeEvent]
-    ):
-        self.__on_state_changed.handler = handler
+            timeout=timeout,
+        )
+
+    async def is_recording_async(self, timeout: Optional[float] = 10) -> bool:
+        """
+        Checks whether the audio recorder is currently recording.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Returns:
+            `True` if the recorder is currently recording, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        return await self._invoke_method_async("is_recording", timeout=timeout)
+
+    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:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Returns:
+            The file path where the audio was saved or `None` if not applicable.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        return await self._invoke_method_async("stop_recording", timeout=timeout)
+
+    async def cancel_recording_async(self, timeout: Optional[float] = 10):
+        """
+        Cancels the current audio recording.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        await self._invoke_method_async("cancel_recording", timeout=timeout)
+
+    def cancel_recording(self, timeout: Optional[float] = 10):
+        """
+        Cancels the current audio recording.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        asyncio.create_task(self.cancel_recording_async(timeout=timeout))
+
+    async def resume_recording_async(self, timeout: Optional[float] = 10):
+        """
+        Resumes a paused audio recording.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        await self._invoke_method_async("resume_recording", timeout=timeout)
+
+    def resume_recording(self, timeout: Optional[float] = 10):
+        """
+        Resumes a paused audio recording.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        asyncio.create_task(self.resume_recording_async(timeout=timeout))
+
+    async def pause_recording_async(self, timeout: Optional[float] = 10):
+        """
+        Pauses the ongoing audio recording.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        await self._invoke_method_async("pause_recording", timeout=timeout)
+
+    def pause_recording(self, timeout: Optional[float] = 10):
+        """
+        Pauses the ongoing audio recording.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        asyncio.create_task(self.pause_recording_async(timeout=timeout))
+
+    async def is_paused_async(self, timeout: Optional[float] = 10) -> bool:
+        """
+        Checks whether the audio recorder is currently paused.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Returns:
+            `True` if the recorder is paused, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        return await self._invoke_method_async("is_paused", timeout=timeout)
+
+    async def is_supported_encoder_async(self, encoder: AudioEncoder, timeout: Optional[float] = 10) -> bool:
+        """
+        Checks if the given audio encoder is supported by the recorder.
+
+        Args:
+            encoder: The audio encoder to check.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Returns:
+            `True` if the encoder is supported, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        return await self._invoke_method_async(
+            "is_supported_encoder", {"encoder": encoder}, timeout=timeout
+        )
+
+    async def get_input_devices_async(self, timeout: Optional[float] = 10) -> List[InputDevice]:
+        """
+        Retrieves the available input devices for recording.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Returns:
+            A list of available input devices.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        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, timeout: Optional[float] = 10) -> bool:
+        """
+        Checks if the app has permission to record audio.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Returns:
+            `True` if the app has permission, `False` otherwise.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        return await self._invoke_method_async("has_permission", timeout=timeout)