flet-audio 1.1.0.dev2__tar.gz → 1.1.0.dev4__tar.gz

{flet_audio-1.1.0.dev2/src/flet_audio.egg-info → flet_audio-1.1.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flet-audio
-Version: 1.1.0.dev2
+Version: 1.1.0.dev4
 Summary: Provides audio integration and playback in Flet apps.
 Author-email: Flet contributors <hello@flet.dev>
 License-Expression: Apache-2.0
@@ -11,7 +11,7 @@ Project-URL: Issues, https://github.com/flet-dev/flet/issues
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flet==1.1.0.dev2
+Requires-Dist: flet==1.1.0.dev4
 Dynamic: license-file
 
 # flet-audio
@@ -58,15 +58,20 @@ To install the `flet-audio` package and add it to your project dependencies:
     After this, you will have to manually add this package to your `requirements.txt` or `pyproject.toml`.
 
 > [!NOTE]
-> On Linux/WSL, you need to install [`GStreamer`](https://github.com/GStreamer/gstreamer) library.
+> On Linux, `Audio` is only available in the **full** desktop client. With the default **light** client,
+> calls such as [`play()`](https://flet.dev/docs/services/audio#flet_audio.Audio.play) fail with `Timeout waiting for invoke method listener` - set
+> [`FLET_DESKTOP_FLAVOR=full`](https://flet.dev/docs/reference/environment-variables#flet_desktop_flavor) or `desktop_flavor = "full"` under `[tool.flet]` in `pyproject.toml`.
 >
-> If you receive `error while loading shared libraries: libgstapp-1.0.so.0`, it means `GStreamer` is not installed in your WSL environment.
->
-> To install it, run the following command:
+> The full client needs GStreamer and, because it also contains the `Video` control, `libmpv`.
+> On Debian 12+ and Ubuntu 24.04+:
 >
 > ```bash
-> apt install -y libgstreamer1.0-0 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-tools
+> sudo apt install libmpv2 gstreamer1.0-plugins-base gstreamer1.0-plugins-good
 > ```
+>
+> On Debian 11 and Ubuntu 20.04/22.04, install `libmpv1` instead of `libmpv2`. For more formats, also install
+> `gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav`.
+> If you receive `error while loading shared libraries: libgstapp-1.0.so.0`, GStreamer is not installed.
 
 ### Examples
 

{flet_audio-1.1.0.dev2 → flet_audio-1.1.0.dev4}/README.md

@@ -42,15 +42,20 @@ To install the `flet-audio` package and add it to your project dependencies:
     After this, you will have to manually add this package to your `requirements.txt` or `pyproject.toml`.
 
 > [!NOTE]
-> On Linux/WSL, you need to install [`GStreamer`](https://github.com/GStreamer/gstreamer) library.
+> On Linux, `Audio` is only available in the **full** desktop client. With the default **light** client,
+> calls such as [`play()`](https://flet.dev/docs/services/audio#flet_audio.Audio.play) fail with `Timeout waiting for invoke method listener` - set
+> [`FLET_DESKTOP_FLAVOR=full`](https://flet.dev/docs/reference/environment-variables#flet_desktop_flavor) or `desktop_flavor = "full"` under `[tool.flet]` in `pyproject.toml`.
 >
-> If you receive `error while loading shared libraries: libgstapp-1.0.so.0`, it means `GStreamer` is not installed in your WSL environment.
->
-> To install it, run the following command:
+> The full client needs GStreamer and, because it also contains the `Video` control, `libmpv`.
+> On Debian 12+ and Ubuntu 24.04+:
 >
 > ```bash
-> apt install -y libgstreamer1.0-0 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-tools
+> sudo apt install libmpv2 gstreamer1.0-plugins-base gstreamer1.0-plugins-good
 > ```
+>
+> On Debian 11 and Ubuntu 20.04/22.04, install `libmpv1` instead of `libmpv2`. For more formats, also install
+> `gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav`.
+> If you receive `error while loading shared libraries: libgstapp-1.0.so.0`, GStreamer is not installed.
 
 ### Examples
 

{flet_audio-1.1.0.dev2 → flet_audio-1.1.0.dev4}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "flet-audio"
-version = "1.1.0.dev2"
+version = "1.1.0.dev4"
 description = "Provides audio integration and playback in Flet apps."
 readme = "README.md"
 authors = [{ name = "Flet contributors", email = "hello@flet.dev" }]
 license = "Apache-2.0"
 requires-python = ">=3.10"
 dependencies = [
-    "flet==1.1.0.dev2",
+    "flet==1.1.0.dev4",
 ]
 
 [project.urls]

{flet_audio-1.1.0.dev2 → flet_audio-1.1.0.dev4}/src/flet_audio/__init__.py

@@ -1,5 +1,8 @@
 from flet_audio.audio import Audio
 from flet_audio.types import (
+    AudioContext,
+    AudioContextFocus,
+    AudioContextRoute,
     AudioDurationChangeEvent,
     AudioPositionChangeEvent,
     AudioState,
@@ -9,6 +12,9 @@ from flet_audio.types import (
 
 __all__ = [
     "Audio",
+    "AudioContext",
+    "AudioContextFocus",
+    "AudioContextRoute",
     "AudioDurationChangeEvent",
     "AudioPositionChangeEvent",
     "AudioState",

{flet_audio-1.1.0.dev2 → flet_audio-1.1.0.dev4}/src/flet_audio/audio.py

@@ -2,6 +2,7 @@ from typing import Optional, Union
 
 import flet as ft
 from flet_audio.types import (
+    AudioContext,
     AudioDurationChangeEvent,
     AudioPositionChangeEvent,
     AudioStateChangeEvent,
@@ -75,6 +76,21 @@ class Audio(ft.Service):
     Defines the release mode.
     """
 
+    audio_context: Optional[AudioContext] = None
+    """
+    Configures platform-specific audio session and focus behavior
+    (for example mixing or ducking background music on Android/iOS).
+
+    When unset (`None`), Flet does not apply a custom audio context, so the
+    player keeps whatever context it already has. For a new player on mobile,
+    that means the usual effective behavior:
+    :attr:`~flet_audio.AudioContextRoute.SYSTEM`,
+    :attr:`~flet_audio.AudioContextFocus.GAIN`, `respect_silence=False`,
+    and `stay_awake=False`.
+
+    See :class:`~flet_audio.AudioContext`.
+    """
+
     on_loaded: Optional[ft.ControlEventHandler["Audio"]] = None
     """
     Fires when an audio is loaded/buffered.

{flet_audio-1.1.0.dev2 → flet_audio-1.1.0.dev4}/src/flet_audio/types.py

@@ -1,6 +1,6 @@
 from dataclasses import dataclass
 from enum import Enum
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
 
 import flet as ft
 
@@ -8,6 +8,9 @@ if TYPE_CHECKING:
     from flet_audio.audio import Audio  # noqa
 
 __all__ = [
+    "AudioContext",
+    "AudioContextFocus",
+    "AudioContextRoute",
     "AudioDurationChangeEvent",
     "AudioPositionChangeEvent",
     "AudioState",
@@ -117,3 +120,113 @@ class AudioDurationChangeEvent(ft.Event["Audio"]):
 
     duration: ft.Duration
     """The duration of the audio."""
+
+
+class AudioContextFocus(Enum):
+    """
+    How the audio player requests and handles audio focus on mobile platforms.
+    """
+
+    GAIN = "gain"
+    """
+    Requests permanent audio focus, pausing other background audio apps.
+    """
+
+    DUCK_OTHERS = "duckOthers"
+    """
+    Lowers the volume of other audio apps while this audio plays.
+
+    Warning:
+        Due to iOS platform limitations, cannot be combined with
+        :attr:`~flet_audio.AudioContext.respect_silence` set to `True`.
+    """
+
+    MIX_WITH_OTHERS = "mixWithOthers"
+    """
+    Mixes with other background audio apps without pausing or ducking them.
+
+    Warning:
+        Due to iOS platform limitations, cannot be combined with
+        :attr:`~flet_audio.AudioContext.respect_silence` set to `True`.
+    """
+
+
+class AudioContextRoute(Enum):
+    """
+    Audio output routing behavior.
+    """
+
+    SYSTEM = "system"
+    """Uses the default system audio route."""
+
+    SPEAKER = "speaker"
+    """
+    Forces audio output through the built-in speaker.
+
+    Warning:
+        Due to iOS platform limitations, cannot be combined with
+        :attr:`~flet_audio.AudioContext.respect_silence` set to `True`.
+    """
+
+    EARPIECE = "earpiece"
+    """Routes audio output to the earpiece receiver."""
+
+
+@ft.value(kw_only=True)
+class AudioContext:
+    """
+    Cross-platform configuration for native audio session and focus behavior.
+
+    Unset fields (`None`) are filled in when the context is applied on mobile:
+    route as :attr:`~flet_audio.AudioContextRoute.SYSTEM`, focus as
+    :attr:`~flet_audio.AudioContextFocus.GAIN`, and `respect_silence` /
+    `stay_awake` as `False`.
+
+    Note:
+        On iOS, audio context cannot be handled for each player individually,
+        so setting this property on an :class:`~flet_audio.Audio` instance
+        applies the context globally for the app.
+
+        Meaningful mainly on Android and iOS; desktop and web ignore it.
+    """
+
+    route: Optional[AudioContextRoute] = None
+    """
+    The audio output route (:attr:`~flet_audio.AudioContextRoute.SYSTEM`,
+    :attr:`~flet_audio.AudioContextRoute.SPEAKER`, or
+    :attr:`~flet_audio.AudioContextRoute.EARPIECE`).
+
+    If unset (`None`), mobile platforms behave as
+    :attr:`~flet_audio.AudioContextRoute.SYSTEM`.
+    """
+
+    focus: Optional[AudioContextFocus] = None
+    """
+    The audio focus mode (:attr:`~flet_audio.AudioContextFocus.GAIN`,
+    :attr:`~flet_audio.AudioContextFocus.DUCK_OTHERS`, or
+    :attr:`~flet_audio.AudioContextFocus.MIX_WITH_OTHERS`).
+
+    If unset (`None`), mobile platforms behave as
+    :attr:`~flet_audio.AudioContextFocus.GAIN`.
+    """
+
+    respect_silence: Optional[bool] = None
+    """
+    Whether the audio should be muted when the device is in silent/ringer mode.
+
+    If unset (`None`), mobile platforms behave as `False`
+    (audio can play while the device is silenced).
+
+    Warning:
+        Due to iOS platform limitations, setting this to `True` cannot be
+        combined with :attr:`~flet_audio.AudioContextFocus.DUCK_OTHERS`,
+        :attr:`~flet_audio.AudioContextFocus.MIX_WITH_OTHERS`, or
+        :attr:`~flet_audio.AudioContextRoute.SPEAKER`.
+    """
+
+    stay_awake: Optional[bool] = None
+    """
+    Whether to keep the device awake (acquire a wake lock) while playing audio.
+
+    If unset (`None`), mobile platforms behave as `False`.
+    """

{flet_audio-1.1.0.dev2 → flet_audio-1.1.0.dev4/src/flet_audio.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flet-audio
-Version: 1.1.0.dev2
+Version: 1.1.0.dev4
 Summary: Provides audio integration and playback in Flet apps.
 Author-email: Flet contributors <hello@flet.dev>
 License-Expression: Apache-2.0
@@ -11,7 +11,7 @@ Project-URL: Issues, https://github.com/flet-dev/flet/issues
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: flet==1.1.0.dev2
+Requires-Dist: flet==1.1.0.dev4
 Dynamic: license-file
 
 # flet-audio
@@ -58,15 +58,20 @@ To install the `flet-audio` package and add it to your project dependencies:
     After this, you will have to manually add this package to your `requirements.txt` or `pyproject.toml`.
 
 > [!NOTE]
-> On Linux/WSL, you need to install [`GStreamer`](https://github.com/GStreamer/gstreamer) library.
+> On Linux, `Audio` is only available in the **full** desktop client. With the default **light** client,
+> calls such as [`play()`](https://flet.dev/docs/services/audio#flet_audio.Audio.play) fail with `Timeout waiting for invoke method listener` - set
+> [`FLET_DESKTOP_FLAVOR=full`](https://flet.dev/docs/reference/environment-variables#flet_desktop_flavor) or `desktop_flavor = "full"` under `[tool.flet]` in `pyproject.toml`.
 >
-> If you receive `error while loading shared libraries: libgstapp-1.0.so.0`, it means `GStreamer` is not installed in your WSL environment.
->
-> To install it, run the following command:
+> The full client needs GStreamer and, because it also contains the `Video` control, `libmpv`.
+> On Debian 12+ and Ubuntu 24.04+:
 >
 > ```bash
-> apt install -y libgstreamer1.0-0 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-tools
+> sudo apt install libmpv2 gstreamer1.0-plugins-base gstreamer1.0-plugins-good
 > ```
+>
+> On Debian 11 and Ubuntu 20.04/22.04, install `libmpv1` instead of `libmpv2`. For more formats, also install
+> `gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav`.
+> If you receive `error while loading shared libraries: libgstapp-1.0.so.0`, GStreamer is not installed.
 
 ### Examples
 

flet_audio-1.1.0.dev4/src/flet_audio.egg-info/requires.txt

@@ -0,0 +1 @@
+flet==1.1.0.dev4

{flet_audio-1.1.0.dev2 → flet_audio-1.1.0.dev4}/src/flutter/flet_audio/lib/src/audio.dart

@@ -20,6 +20,7 @@ class AudioService extends FletService {
   String? _src;
   Uint8List? _srcBytes;
   ReleaseMode? _releaseMode;
+  AudioContext? _audioContext;
   double? _volume;
   double? _balance;
   double? _playbackRate;
@@ -121,6 +122,16 @@ class AudioService extends FletService {
       }
 
       final sourceVersion = srcChanged ? ++_sourceVersion : _sourceVersion;
+
+      // Apply the context before loading: Android re-prepares an existing
+      // source when its context changes, without awaiting that preparation.
+      final audioContext = parseAudioContext(control.get("audio_context"));
+      if (audioContext != null && audioContext != _audioContext) {
+        _audioContext = audioContext;
+        await player.setAudioContext(audioContext);
+        if (sourceVersion != _sourceVersion) return;
+      }
+
       if (srcChanged) {
         try {
           await _applySource();

flet_audio-1.1.0.dev4/src/flutter/flet_audio/lib/src/utils/audio.dart

@@ -0,0 +1,25 @@
+import 'package:audioplayers/audioplayers.dart';
+import 'package:collection/collection.dart';
+import 'package:flet/flet.dart';
+
+ReleaseMode? parseReleaseMode(String? value, [ReleaseMode? defaultValue]) {
+  if (value == null) return defaultValue;
+  return ReleaseMode.values.firstWhereOrNull(
+          (e) => e.name.toLowerCase() == value.toLowerCase()) ??
+      defaultValue;
+}
+
+AudioContext? parseAudioContext(dynamic value) {
+  if (value is! Map) return null;
+
+  final config = AudioContextConfig(
+    route: parseEnum(AudioContextConfigRoute.values, value["route"]?.toString(),
+        AudioContextConfigRoute.system)!,
+    focus: parseEnum(AudioContextConfigFocus.values, value["focus"]?.toString(),
+        AudioContextConfigFocus.gain)!,
+    respectSilence: parseBool(value["respect_silence"], false)!,
+    stayAwake: parseBool(value["stay_awake"], false)!,
+  );
+
+  return config.build();
+}

flet_audio-1.1.0.dev2/src/flet_audio.egg-info/requires.txt

@@ -1 +0,0 @@
-flet==1.1.0.dev2

flet_audio-1.1.0.dev2/src/flutter/flet_audio/lib/src/utils/audio.dart

@@ -1,9 +0,0 @@
-import 'package:audioplayers/audioplayers.dart';
-import 'package:collection/collection.dart';
-
-ReleaseMode? parseReleaseMode(String? value, [ReleaseMode? defaultValue]) {
-  if (value == null) return defaultValue;
-  return ReleaseMode.values.firstWhereOrNull(
-          (e) => e.name.toLowerCase() == value.toLowerCase()) ??
-      defaultValue;
-}