flet-audio 0.1.0.dev3__py3-none-any.whl → 0.2.0.dev35__py3-none-any.whl

flet_audio/__init__.py

@@ -1,5 +1,5 @@
-from flet_audio.audio import (
-    Audio,
+from .audio import Audio
+from .types import (
     AudioDurationChangeEvent,
     AudioPositionChangeEvent,
     AudioState,

flet_audio/audio.py

@@ -1,294 +1,272 @@
-from enum import Enum
-from typing import Any, Optional
+import asyncio
+from typing import 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 OptionalControlEventCallable, OptionalEventCallable
-from flet.utils import deprecated
+import flet as ft
 
+from .types import (
+    AudioDurationChangeEvent,
+    AudioPositionChangeEvent,
+    AudioStateChangeEvent,
+    ReleaseMode,
+)
 
-class ReleaseMode(Enum):
-    RELEASE = "release"
-    LOOP = "loop"
-    STOP = "stop"
 
+@ft.control("Audio")
+class Audio(ft.Service):
+    """
+    A control to simultaneously play multiple audio sources.
+
+    Raises:
+        AssertionError: If both [`src`][(c).] and [`src_base64`][(c).] are `None`.
+
+    Note:
+        This control is non-visual and should be added to `Page.services` list before it can be used.
+    """
+
+    src: Optional[str] = None
+    """
+    The audio source. Can be a URL or a local [asset file](https://flet.dev/docs/cookbook/assets).
+
+    Note:
+        - At least one of `src` or [`src_base64`][..] must be provided, 
+            with `src_base64` having priority if both are provided.
+        - [Here](https://github.com/bluefireteam/audioplayers/blob/main/troubleshooting.md#supported-formats--encodings) 
+            is a list of supported audio formats.
+    """
 
-class AudioState(Enum):
-    STOPPED = "stopped"
-    PLAYING = "playing"
-    PAUSED = "paused"
-    COMPLETED = "completed"
-    DISPOSED = "disposed"
+    src_base64: Optional[str] = None
+    """
+    Sets the contents of audio file encoded in base-64 format.
+    
+    Note:
+        - At least one of [`src`][..] or `src_base64` must be provided, 
+            with `src_base64` having priority if both are provided.
+        - [Here](https://github.com/bluefireteam/audioplayers/blob/main/troubleshooting.md#supported-formats--encodings) 
+            is a list of supported audio formats.
+    """
 
+    autoplay: bool = False
+    """
+    Starts playing audio as soon as audio control is added to a page.
+    
+    Note:
+        Autoplay works in desktop, mobile apps and Safari browser, but doesn't work in Chrome/Edge.
+    """
 
-class AudioStateChangeEvent(ControlEvent):
-    def __init__(self, e: ControlEvent):
-        super().__init__(e.target, e.name, e.data, e.control, e.page)
-        self.state: AudioState = AudioState(e.data)
+    volume: ft.Number = 1.0
+    """
+    Sets the volume (amplitude).
+    It's value ranges between `0.0` (mute) and `1.0` (maximum volume). 
+    Intermediate values are linearly interpolated.
+    """
 
+    balance: ft.Number = 0.0
+    """
+    Sets the stereo balance.
 
-class AudioPositionChangeEvent(ControlEvent):
-    def __init__(self, e: ControlEvent):
-        super().__init__(e.target, e.name, e.data, e.control, e.page)
-        self.position: int = int(e.data)
 
+    * `-1` - The left channel is at full volume; the right channel is silent. 
+    * `1` - The right channel is at full volume; the left channel is silent. 
+    * `0` - Both channels are at the same volume.
+    """
 
-class AudioDurationChangeEvent(ControlEvent):
-    def __init__(self, e: ControlEvent):
-        super().__init__(e.target, e.name, e.data, e.control, e.page)
-        self.duration: int = int(e.data)
+    playback_rate: ft.Number = 1.0
+    """
+    Sets the playback rate. 
+    
+    Should ideally be set when creating the constructor.
+    
+    Note: 
+        - iOS and macOS have limits between `0.5x` and `2x`. 
+        - Android SDK version should be 23 or higher.
+    """
 
+    release_mode: ReleaseMode = ReleaseMode.RELEASE
+    """
+    Sets the release mode.
+    """
 
-class Audio(Control):
+    on_loaded: ft.OptionalControlEventHandler["Audio"] = None
+    """
+    Fires when an audio is loaded/buffered.
     """
-    A control to simultaneously play multiple audio files. Works on macOS, Linux, Windows, iOS, Android and web. Based on audioplayers Flutter widget (https://pub.dev/packages/audioplayers).
 
-    Audio control is non-visual and should be added to `page.overlay` list.
+    on_duration_change: ft.OptionalEventHandler[AudioDurationChangeEvent["Audio"]] = None
+    """
+    Fires as soon as audio duration is available (it might take a while to download or buffer it).
 
-    Example:
-    ```
-    import flet as ft
+    Event handler argument is of type [`AudioDurationChangeEvent`][(p).].
+    """
 
-    import flet_audio as fta
+    on_state_change: ft.OptionalEventHandler[AudioStateChangeEvent["Audio"]] = None
+    """
+    Fires when audio player state changes. 
 
-    def main(page: ft.Page):
-        audio1 = fta.Audio(
-            src="https://luan.xyz/files/audio/ambient_c_motion.mp3", autoplay=True
-        )
-        page.overlay.append(audio1)
-        page.add(
-            ft.Text("This is an app with background audio."),
-            ft.ElevatedButton("Stop playing", on_click=lambda _: audio1.pause()),
-        )
+    Event handler argument is of type [`AudioStateChangeEvent`][(p).].
+    """
 
-    ft.app(target=main)
-    ```
+    on_position_change: ft.OptionalEventHandler[AudioPositionChangeEvent["Audio"]] = None
+    """
+    Fires when audio position is changed. 
+    Will continuously update the position of the playback every 1 second if the status is playing. 
+    
+    Can be used for a progress bar.
 
-    -----
+    Event handler argument is of type [`AudioPositionChangeEvent`][(p).].
+    """
 
-    Online docs: https://flet.dev/docs/controls/audio
+    on_seek_complete: ft.OptionalControlEventHandler["Audio"] = None
+    """
+    Fires on seek completions. 
+    An event is going to be sent as soon as the audio seek is finished.
     """
 
-    def __init__(
-        self,
-        src: Optional[str] = None,
-        src_base64: Optional[str] = None,
-        autoplay: Optional[bool] = None,
-        volume: OptionalNumber = None,
-        balance: OptionalNumber = None,
-        playback_rate: OptionalNumber = None,
-        release_mode: Optional[ReleaseMode] = None,
-        on_loaded: OptionalControlEventCallable = None,
-        on_duration_changed: OptionalEventCallable[AudioDurationChangeEvent] = None,
-        on_state_changed: OptionalEventCallable[AudioStateChangeEvent] = None,
-        on_position_changed: OptionalEventCallable[AudioPositionChangeEvent] = None,
-        on_seek_complete: OptionalControlEventCallable = None,
-        #
-        # Control
-        #
-        ref: Optional[Ref] = None,
-        data: Any = None,
-    ):
-        Control.__init__(
-            self,
-            ref=ref,
-            data=data,
-        )
-
-        self.__on_state_changed = EventHandler(lambda e: AudioStateChangeEvent(e))
-        self._add_event_handler("state_changed", self.__on_state_changed.get_handler())
-
-        self.__on_position_changed = EventHandler(lambda e: AudioPositionChangeEvent(e))
-        self._add_event_handler(
-            "position_changed", self.__on_position_changed.get_handler()
-        )
-
-        self.__on_duration_changed = EventHandler(lambda e: AudioDurationChangeEvent(e))
-        self._add_event_handler(
-            "duration_changed", self.__on_duration_changed.get_handler()
-        )
-
-        self.src = src
-        self.src_base64 = src_base64
-        self.autoplay = autoplay
-        self.volume = volume
-        self.balance = balance
-        self.playback_rate = playback_rate
-        self.release_mode = release_mode
-        self.on_loaded = on_loaded
-        self.on_duration_changed = on_duration_changed
-        self.on_state_changed = on_state_changed
-        self.on_position_changed = on_position_changed
-        self.on_seek_complete = on_seek_complete
-
-    def _get_control_name(self):
-        return "audio"
-
-    def play(self):
-        self.invoke_method("play")
-
-    def pause(self):
-        self.invoke_method("pause")
-
-    def resume(self):
-        self.invoke_method("resume")
-
-    def release(self):
-        self.invoke_method("release")
-
-    def seek(self, position_milliseconds: int):
-        self.invoke_method("seek", {"position": str(position_milliseconds)})
-
-    def get_duration(self, wait_timeout: Optional[float] = 5) -> Optional[int]:
-        sr = self.invoke_method(
-            "get_duration",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return int(sr) if sr else None
-
-    async def get_duration_async(
-        self, wait_timeout: Optional[float] = 5
-    ) -> Optional[int]:
-        sr = await self.invoke_method_async(
-            "get_duration",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return int(sr) if sr else None
-
-    def get_current_position(self, wait_timeout: Optional[float] = 5) -> Optional[int]:
-        sr = self.invoke_method(
-            "get_current_position",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return int(sr) if sr else None
-
-    async def get_current_position_async(
-        self, wait_timeout: Optional[float] = 5
-    ) -> Optional[int]:
-        sr = await self.invoke_method_async(
-            "get_current_position",
-            wait_for_result=True,
-            wait_timeout=wait_timeout,
-        )
-        return int(sr) if sr else None
-
-    # src
-    @property
-    def src(self):
-        return self._get_attr("src")
-
-    @src.setter
-    def src(self, value):
-        self._set_attr("src", value)
-
-    # src_base64
-    @property
-    def src_base64(self):
-        return self._get_attr("srcBase64")
-
-    @src_base64.setter
-    def src_base64(self, value):
-        self._set_attr("srcBase64", value)
-
-    # autoplay
-    @property
-    def autoplay(self) -> bool:
-        return self._get_attr("autoplay", data_type="bool", def_value=False)
-
-    @autoplay.setter
-    def autoplay(self, value: Optional[bool]):
-        self._set_attr("autoplay", value)
-
-    # volume
-    @property
-    def volume(self) -> OptionalNumber:
-        return self._get_attr("volume")
-
-    @volume.setter
-    def volume(self, value: OptionalNumber):
-        if value is None or (0 <= value <= 1):
-            self._set_attr("volume", value)
-
-    # balance
-    @property
-    def balance(self) -> OptionalNumber:
-        return self._get_attr("balance")
-
-    @balance.setter
-    def balance(self, value: OptionalNumber):
-        if value is None or (-1 <= value <= 1):
-            self._set_attr("balance", value)
-
-    # playback_rate
-    @property
-    def playback_rate(self) -> OptionalNumber:
-        return self._get_attr("playbackRate")
-
-    @playback_rate.setter
-    def playback_rate(self, value: OptionalNumber):
-        if value is None or (0 <= value <= 2):
-            self._set_attr("playbackRate", value)
-
-    # release_mode
-    @property
-    def release_mode(self):
-        return self._get_attr("releaseMode")
-
-    @release_mode.setter
-    def release_mode(self, value: Optional[ReleaseMode]):
-        self._set_enum_attr("releaseMode", value, ReleaseMode)
-
-    # on_loaded
-    @property
-    def on_loaded(self):
-        return self._get_event_handler("loaded")
-
-    @on_loaded.setter
-    def on_loaded(self, handler: OptionalControlEventCallable):
-        self._add_event_handler("loaded", handler)
-
-    # on_duration_changed
-    @property
-    def on_duration_changed(self):
-        return self.__on_duration_changed.handler
-
-    @on_duration_changed.setter
-    def on_duration_changed(
-        self, handler: OptionalEventCallable[AudioDurationChangeEvent]
-    ):
-        self.__on_duration_changed.handler = handler
-
-    # 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[AudioStateChangeEvent]):
-        self.__on_state_changed.handler = handler
-
-    # on_position_changed
-    @property
-    def on_position_changed(self):
-        return self.__on_position_changed.handler
-
-    @on_position_changed.setter
-    def on_position_changed(
-        self, handler: OptionalEventCallable[AudioPositionChangeEvent]
-    ):
-        self.__on_position_changed.handler = handler
-        self._set_attr("onPositionChanged", True if handler is not None else None)
-
-    # on_seek_complete
-    @property
-    def on_seek_complete(self):
-        return self._get_event_handler("seek_complete")
-
-    @on_seek_complete.setter
-    def on_seek_complete(self, handler: OptionalControlEventCallable):
-        self._add_event_handler("seek_complete", handler)
+    def before_update(self):
+        super().before_update()
+        assert self.src or self.src_base64, "either src or src_base64 must be provided"
+
+    async def play_async(self, position: ft.DurationValue = ft.Duration(), timeout: Optional[float] = 10):
+        """
+        Starts playing audio from the specified `position`.
+
+        Args:
+            position: The position to start playback from.
+            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("play", {"position": position}, timeout=timeout)
+
+    def play(self, position: ft.DurationValue = ft.Duration(), timeout: Optional[float] = 10):
+        """
+        Starts playing audio from the specified `position`.
+
+        Args:
+            position: The position to start playback from.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        asyncio.create_task(self.play_async(position, timeout=timeout))
+
+    async def pause_async(self, timeout: Optional[float] = 10):
+        """
+        Pauses the audio that is currently playing.
+
+        If you call [`resume()`][.resume] or [`resume_async()`][.resume_async] later,
+        the audio will resume from the point that it has been paused.
+        """
+        await self._invoke_method_async("pause", timeout=timeout)
+
+    def pause(self, timeout: Optional[float] = 10):
+        """
+        Pauses the audio that is currently playing.
+
+        If you call [`resume()`][.resume] or [`resume_async()`][.resume_async] later,
+        the audio will resume from the point that it has been paused.
+
+        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_async(timeout=timeout))
+
+    async def resume_async(self, timeout: Optional[float] = 10):
+        """
+        Resumes the audio that has been paused or stopped.
+
+        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", timeout=timeout)
+
+    def resume(self, timeout: Optional[float] = 10):
+        """
+        Resumes the audio that has been paused or stopped.
+
+        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_async(timeout=timeout))
+
+    async def release_async(self, timeout: Optional[float] = 10):
+        """
+        Releases the resources associated with this media player.
+        These are going to be fetched or buffered again as soon as
+        you change the source or call [`resume()`][.resume] or [`resume_async()`][.resume_async].
+
+        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("release", timeout=timeout)
+
+    def release(self, timeout: Optional[float] = 10):
+        """
+        Releases the resources associated with this media player.
+        These are going to be fetched or buffered again as soon as
+        you change the source or call [`resume()`][.resume] or [`resume_async()`][.resume_async].
+
+        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.release_async(timeout=timeout))
+
+    async def seek_async(self, position: ft.DurationValue, timeout: Optional[float] = 10):
+        """
+        Moves the cursor to the desired position.
+
+        Args:
+            position: The position to seek/move to.
+            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("seek", {"position": position}, timeout=timeout)
+
+    def seek(self, position: ft.DurationValue, timeout: Optional[float] = 10):
+        """
+        Moves the cursor to the desired position.
+
+        Args:
+            position: The position to seek/move to.
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        asyncio.create_task(self.seek_async(position, timeout=timeout))
+
+    async def get_duration_async(self, timeout: Optional[float] = 10) -> Optional[ft.Duration]:
+        """
+        Get audio duration of the audio playback.
+
+        It will be available as soon as the audio duration is available
+        (it might take a while to download or buffer it if file is not local).
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Returns:
+            The duration of audio playback.
+        Raises:
+            TimeoutError: If the request times out.
+        """
+        return await self._invoke_method_async("get_duration", timeout=timeout)
+
+    async def get_current_position_async(self, timeout: Optional[float] = 10) -> Optional[ft.Duration]:
+        """
+        Get the current position of the audio playback.
+
+        Args:
+            timeout: The maximum amount of time (in seconds) to wait for a response.
+        Returns:
+            The current position of the audio playback.
+        """
+        return await self._invoke_method_async("get_current_position", timeout=timeout)

flet_audio/types.py

@@ -0,0 +1,69 @@
+from enum import Enum
+
+import flet as ft
+
+__all__ = [
+    "AudioState",
+    "AudioStateChangeEvent",
+    "AudioPositionChangeEvent",
+    "AudioDurationChangeEvent",
+    "ReleaseMode",
+]
+
+
+class ReleaseMode(Enum):
+    """The behavior of Audio player when an audio is finished or stopped."""
+
+    RELEASE = "release"
+    """
+    Releases all resources, just like calling release method.
+
+    Info:
+        - In Android, the media player is quite resource-intensive, and this will
+        let it go. Data will be buffered again when needed (if it's a remote file,
+        it will be downloaded again).
+        - In iOS and macOS, works just like [`Audio.stop()`][(p).Audio.stop] method.
+    """
+
+    LOOP = "loop"
+    """
+    Keeps buffered data and plays again after completion, creating a loop.
+    Notice that calling stop method is not enough to release the resources
+    when this mode is being used.
+    """
+
+    STOP = "stop"
+    """
+    Stops audio playback but keep all resources intact.
+    Use this if you intend to play again later.
+    """
+
+
+class AudioState(Enum):
+    """The state of the audio player."""
+    STOPPED = "stopped"
+    """The audio player is stopped."""
+
+    PLAYING = "playing"
+    """The audio player is currently playing audio."""
+
+    PAUSED = "paused"
+    """The audio player is paused and can be resumed."""
+
+    COMPLETED = "completed"
+    """The audio player has successfully reached the end of the audio."""
+
+    DISPOSED = "disposed"
+    """The audio player has been disposed of and should not be used anymore."""
+
+
+class AudioStateChangeEvent(ft.Event[ft.EventControlType]):
+    state: AudioState
+
+
+class AudioPositionChangeEvent(ft.Event[ft.EventControlType]):
+    position: int
+
+
+class AudioDurationChangeEvent(ft.Event[ft.EventControlType]):
+    duration: int