Flet中文文档

主题

Audio ​

允许在 Flet 应用中播放音频。

平台支持 ​

平台WindowsmacOSLinuxiOSAndroidWeb
支持✅✅✅✅✅✅

用法 ​

要使用 Audio 控件，请将 flet-audio 包添加到你的项目依赖中：

uv

bash
uv add flet-audio

pip

bash
pip install flet-audio  [^1]

[^1]: 之后，你还需要手动把这个包添加到 requirements.txt 或 pyproject.toml 中。

Linux 依赖要求

要在 Linux（或 WSL）上播放音频，你需要安装 GStreamer 库。

要在 Ubuntu/Debian 上安装最小集的 GStreamer 库，请运行：

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

要安装完整集：

bash
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

如果你收到 error while loading shared libraries: libgstapp-1.0.so.0， 说明你的 WSL 环境中没有安装 GStreamer。 请按上面的说明安装完整集的 GStreamer 库。

有关在其他 Linux 发行版上安装的方法，请参阅这份指南。

示例 ​

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

说明 ​

Audio 继承自：ft.Service, BaseControl

用于同时播放多个音频源的控件。

属性 ​

名称类型默认值说明
srcOptional[Union[str, bytes]]None音频源。 可以是以下之一： - URL 或本地静态资源文件路径； - base64 字符串； - 原始字节。 注意： 这里 列出了支持的音频格式。
autoplayboolFalse音频控件被添加到页面后立即开始播放音频。 注意： 自动播放在桌面端、移动应用和 Safari 浏览器中有效，但在 Chrome/Edge 中无效。
volumeft.Number1.0设置音量（振幅）。取值范围在 0.0（静音）和 1.0（最大音量）之间。中间值按线性插值。
balanceft.Number0.0定义立体声平衡。 * -1 —— 左声道为满音量；右声道静音。 * 1 —— 右声道为满音量；左声道静音。 * 0 —— 两个声道音量相同。
playback_rateft.Number1.0定义播放速率。 最好在创建构造函数时设置。 注意： - iOS 和 macOS 的限制在 0.5x 和 2x 之间。 - Android SDK 版本应为 23 或更高。
release_modeReleaseModeReleaseMode.RELEASE定义释放模式。
dataAnyskip_任意类型的自定义数据。
keyOptional['KeyValue']None用于在更新之间保持控件标识稳定的键。

只读属性 ​

名称类型默认值说明
parentOptional['BaseControl']—此控件的直接祖先（父级）。 默认为 None，只有在此控件被挂载（加入页面树）后才有值。 Page 控件（页面树的根）是个例外 —— 它的 parent 始终为 None。
page'Page'—此控件所属的页面。

事件 ​

名称类型默认值说明
on_loadedOptional[ft.ControlEventHandler['Audio']]None音频加载/缓冲完成时触发。
on_duration_changeOptional[ft.EventHandler[AudioDurationChangeEvent]]None音频时长一可用就触发（下载或缓冲它可能需要一些时间）。
on_state_changeOptional[ft.EventHandler[AudioStateChangeEvent]]None音频播放器状态改变时触发。
on_position_changeOptional[ft.EventHandler[AudioPositionChangeEvent]]None音频位置改变时触发。如果状态为播放中，将每 1 秒持续更新播放位置。 可用于进度条。
on_seek_completeOptional[ft.ControlEventHandler['Audio']]None跳转完成时触发。音频跳转一完成就会发送事件。

方法 ​

名称类型默认值说明
play——从指定的 position 开始播放音频。 参数： position：开始播放的位置。默认为音频开头。
pause——暂停当前正在播放的音频。 如果之后调用 resume，音频将从暂停的位置继续播放。
resume——恢复已暂停或已停止的音频。
release——释放与此媒体播放器关联的资源。当你更改音源或调用 resume 时，这些资源会被重新获取或缓冲。
seek——将光标移动到期望的位置。 参数： position：要跳转/移动到的位置。
get_durationOptional[ft.Duration]—获取音频播放的时长。 音频时长一可用就会返回（如果文件不是本地的，下载或缓冲可能需要一些时间）。 返回： 音频播放的时长。
get_current_positionOptional[ft.Duration]—获取音频播放的当前位置。 返回： 音频播放的当前位置。
init———
is_isolated——返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
build——在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。
before_update——每当此控件被更新时都会调用此方法。 注意： 务必不要在此处调用或请求 update()。
before_event——在事件处理器执行之前拦截事件。 返回 False 可取消分发。返回 True 或 None 则继续正常的事件处理。
did_mount——在控件挂载到页面树之后调用。 重写此方法以启动需要已挂载页面的资源，例如订阅、定时器或服务监听器。
will_unmount——在控件从页面树移除之前调用。 重写此方法以释放 did_mount() 中创建的资源，例如订阅、定时器或外部句柄。
get_data_channel——解析为此 widget 在 Dart 侧分配的 [DataChannel]。模式： on_data_channel_open: Optional[ft.EventHandler[DataChannelOpenEvent]] = None def init(self): self.on_data_channel_open = self._on_open def _on_open(self, e): self._channel = self.get_data_channel(e.channel_id) 幂等 —— 底层的 Connection 会按 id 缓存 DataChannel，因此重复调用会返回同一实例。没有错误路径：该 id 始终来自框架触发的事件，所以当此方法运行时，通道在两端都已存在。
updateNone—为此控件请求一次 UI 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。

关注我，学习大模型、大数据、Python等热门技术。

footer-banner