Skip to main content

Audio

Allows playing audio in Flet apps.

Platform Support​

PlatformWindowsmacOSLinuxiOSAndroidWeb
Supported✅✅✅✅✅✅

Usage​

To use Audio control add flet-audio package to your project dependencies:

uv add flet-audio
Linux requirements

On Linux, Audio is only available in the full desktop client. With the default light client, calls such as play() fail with Timeout waiting for invoke method listener - set FLET_DESKTOP_FLAVOR=full or desktop_flavor = "full" in pyproject.toml, as described in Installation.

To play audio on Linux (or WSL) you need to install GStreamer library. The full client also contains the Video control, so it needs libmpv too. On Debian 12+ and Ubuntu 24.04+:

sudo apt install libmpv2

On older releases, install libmpv1 instead.

To install the minimal set of GStreamer libs on Ubuntu/Debian, run:

sudo apt install libgtk-3-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

To install the full set:

sudo apt install \
  libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev \
  gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
  gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-doc gstreamer1.0-tools \
  gstreamer1.0-x gstreamer1.0-alsa gstreamer1.0-gl gstreamer1.0-gtk3 \
  gstreamer1.0-qt5 gstreamer1.0-pulseaudio

If you receive error while loading shared libraries: libgstapp-1.0.so.0, it means GStreamer is not installed in your WSL environment. Install the full set of GStreamer libs, as shown above.

See this guide for installing on other Linux distributions.

Examples​

Audio playback controls​

Plays viper.mp3 from the example's assets folder. To run the code on its own, put that file in an assets folder next to your script, or set src to the URL of an audio file.

Sourceplay_arrowTry Online
import flet as ft
import flet_audio as fta


def main(page: ft.Page):
    url = "viper.mp3"

    async def play():
        await audio.play()

    async def pause():
        await audio.pause()

    async def resume():
        await audio.resume()

    async def release():
        await audio.release()

    def set_volume(value: float):
        audio.volume += value

    def set_balance(value: float):
        audio.balance += value

    async def seek_2s():
        await audio.seek(ft.Duration(seconds=2))

    async def get_duration():
        duration = await audio.get_duration()
        print("Duration:", duration)

    async def on_get_current_position():
        position = await audio.get_current_position()
        print("Current position:", position)

    audio = fta.Audio(
        src=url,
        autoplay=False,
        volume=1,
        balance=0,
        release_mode=fta.ReleaseMode.STOP,
        on_loaded=lambda _: print("Loaded"),
        on_duration_change=lambda e: print("Duration changed:", e.duration),
        on_position_change=lambda e: print("Position changed:", e.position),
        on_state_change=lambda e: print("State changed:", e.state),
        on_seek_complete=lambda _: print("Seek complete"),
    )
    page.services.append(audio)

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.Button("Play", on_click=play),
                    ft.Button("Pause", on_click=pause),
                    ft.Button("Resume", on_click=resume),
                    ft.Button("Release", on_click=release),
                    ft.Button("Seek 2s", on_click=seek_2s),
                    ft.Row(
                        controls=[
                            ft.Button(
                                "Volume down",
                                on_click=lambda _: set_volume(-0.1),
                            ),
                            ft.Button("Volume up", on_click=lambda _: set_volume(0.1)),
                        ]
                    ),
                    ft.Row(
                        controls=[
                            ft.Button(
                                "Balance left",
                                on_click=lambda _: set_balance(-0.1),
                            ),
                            ft.Button(
                                "Balance right",
                                on_click=lambda _: set_balance(0.1),
                            ),
                        ]
                    ),
                    ft.Button("Get duration", on_click=get_duration),
                    ft.Button(
                        "Get current position",
                        on_click=on_get_current_position,
                    ),
                ]
            )
        )
    )


if __name__ == "__main__":
    ft.run(main)

Description​

A control to simultaneously play multiple audio sources.

Note

Keep a reference to an Audio, such as in a variable that your event handlers use, for as long as it should play. Flet removes services that no longer have live Python references after an event is handled, which stops their playback.

Inherits: Service

Properties

  • autoplay - Starts playing audio as soon as audio control is added to a page.
  • balance - Defines the stereo balance.
  • context - Defines how this audio interacts with the device and with other audio on mobile platforms, such as whether it plays over other audio.
  • playback_rate - Defines the playback rate.
  • release_mode - Defines the release mode.
  • src - The audio source.
  • volume - Sets the volume (amplitude).

Events

Methods

  • get_current_position - Get the current position of the audio playback.
  • get_duration - Get audio duration of the audio playback.
  • pause - Pauses the audio that is currently playing.
  • play - Starts playing audio from the specified position.
  • release - Releases the resources associated with this media player.
  • resume - Resumes the audio that has been paused or stopped.
  • seek - Moves the cursor to the desired position.

Properties​

autoplayclass-attributeinstance-attribute​

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.

balanceclass-attributeinstance-attribute​

balance: Number = 0.0

Defines the stereo balance.

  • -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.

contextclass-attributeinstance-attribute​

context: AudioContext | None = None

Defines how this audio interacts with the device and with other audio on mobile platforms, such as whether it plays over other audio.

If None, AudioContext.respect_silence is False, and AudioContext.focus depends on the platform:

  • On Android, focus is AudioFocus.DUCK_OTHERS, so every Audio of an app plays together, and other apps' audio usually gets quieter.
  • On iOS, focus is AudioFocus.GAIN, which interrupts other apps' audio.
  • On other platforms, this property is ignored.

On iOS, a context applies to the whole app, so if another Audio of the app has applied one, all of it applies here instead of these values, respect_silence included. Setting this back to None after it was set applies these values.

Should ideally be set when creating the control. On Android, changing it after a source is set prepares that source again, which restarts audio that is playing from the beginning. Changing it to AudioFocus.GAIN stops that audio instead, until Audio.resume is called.

Note

If the app declares the android.permission.MODIFY_AUDIO_SETTINGS permission, setting this resets the device's audio mode to normal and turns its speakerphone off, which can interrupt a call that the app has in progress. The same reset happens once when the app starts, whether or not this is set.

playback_rateclass-attributeinstance-attribute​

playback_rate: Number = 1.0

Defines 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_modeclass-attributeinstance-attribute​

release_mode: ReleaseMode = ReleaseMode.RELEASE

Defines the release mode.

srcclass-attributeinstance-attribute​

src: str | bytes | None = None

The audio source.

It can be one of the following:

  • A URL or local asset file path;
  • A base64 string;
  • Raw bytes.

It can be left unset and assigned later, e.g. once the user picks a file. While it is unset, Audio.play, Audio.resume and Audio.seek raise an error.

Note

Here is a list of supported audio formats.

volumeclass-attributeinstance-attribute​

volume: 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.

Events​

on_duration_changeclass-attributeinstance-attribute​

on_duration_change: (
    EventHandler[AudioDurationChangeEvent] | None
) = None

Fires as soon as audio duration is available (it might take a while to download or buffer it).

on_loadedclass-attributeinstance-attribute​

on_loaded: ControlEventHandler[Audio] | None = None

Fires when an audio is loaded/buffered.

on_position_changeclass-attributeinstance-attribute​

on_position_change: (
    EventHandler[AudioPositionChangeEvent] | None
) = 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.

Note
  • On Android, it stops firing while something else pauses this audio, such as a ringing phone call or another app taking audio focus.
  • On iOS, it stops firing once audio with ReleaseMode.LOOP restarts for the first time.

on_seek_completeclass-attributeinstance-attribute​

on_seek_complete: ControlEventHandler[Audio] | None = (
    None
)

Fires on seek completions. An event is going to be sent as soon as the audio seek is finished.

on_state_changeclass-attributeinstance-attribute​

on_state_change: (
    EventHandler[AudioStateChangeEvent] | None
) = None

Fires when audio player state changes.

Note

Methods​

get_current_positionasync​

get_current_position() -> Duration | None

Get the current position of the audio playback.

Returns:

  • Duration | None - The current position of the audio playback.

get_durationasync​

get_duration() -> Duration | None

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).

Returns:

  • Duration | None - The duration of audio playback.

pauseasync​

pause()

Pauses the audio that is currently playing.

If you call Audio.resume later, the audio will resume from the point that it has been paused.

playasync​

play(position: DurationValue=0)

Starts playing audio from the specified position.

Parameters:

  • position (DurationValue, default: 0) - The position to start playback from. Defaults to the beginning of the audio.

releaseasync​

release()

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 Audio.resume.

resumeasync​

resume()

Resumes the audio that has been paused or stopped.

seekasync​

seek(position: DurationValue)

Moves the cursor to the desired position.

Parameters: