【免费下载链接】flet
Build realtime web, mobile and desktop apps in Python only. No frontend experience required.
Flet 官方在 0.80.0 与 0.85.0 两个版本中对 flet-audio-recorder 包进行了重要重构:控件由普通 Overlay 控件转型为 Service 类型控件,录制参数全部收敛到 configuration 数据类,并新增了 PCM16 流式录制(on_stream 分块回调)与直传上传(AudioRecorderUploadSettings)两大能力。本文以 CHANGELOG.md 为核心骨架,结合 audio_recorder.py 与 types.py 源码,以及 官方示例,带你掌握录制权限配置、基础录音、状态控制、PCM16 分块流式与直传上传的完整实战方案。
一、版本演进脉络:从 0.1.0 到 0.85.0 的关键变更
flet-audio-recorder 的 CHANGELOG.md 记录了三个关键里程碑,理解这段演进有助于你判断自己的代码应该使用哪套 API:
- 0.1.0(Initial release):包的初始版本,提供最基础的录音能力。
- 0.80.0(重大重构,含 Breaking Changes):
AudioRecorder改用@ft.control数据类风格定义,并切换为Service控件类型;- 控件必须添加到
Page.services而非Page.overlay; - 分散的录音配置属性(
audio_encoder、suppress_noise、cancel_echo、auto_gain、channels_num、sample_rate、bit_rate)全部收敛到configuration: AudioRecorderConfiguration数据类; - 事件
on_state_changed更名为on_state_change; - 所有方法参数
wait_timeout更名为timeout; - 一批同步方法改为
async(详见下文“异步方法清单”)。
- 0.85.0(流式能力增强):新增 PCM16 流式录制——
on_stream分块回调与基于AudioRecorderUploadSettings的直传上传。
从源码看,这次重构在 audio_recorder.py 中体现为 @ft.control("AudioRecorder") 装饰器配合 class AudioRecorder(ft.Service) 的定义方式,控件身份从“被动渲染的 UI 元素”变为“挂载于页面服务的后台能力”,这也解释了为什么它必须放入 Page.services。
二、安装与平台支持
安装
根据 README.md 与 pyproject.toml(requires-python = ">=3.10",依赖 flet),可通过两种方式安装:
# 方式一:uv(自动写入依赖清单)
uv add flet-audio-recorder
# 方式二:pip(需手动加入 requirements.txt 或 pyproject.toml)
pip install flet-audio-recorder
平台支持
AudioRecorder 基于 Flutter 生态的 record 包实现,全平台可用:
| 平台 | Windows | macOS | Linux | iOS | Android | Web |
|---|---|---|---|---|---|---|
| 支持 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
需要注意的运行时前提:
- Linux:编码依赖
fmedia(需单独安装),且系统需具备parecord(音频输入)、pactl(设备枚举等工具方法)与ffmpeg(编码与输出),例如 Ubuntu 24.04 上执行sudo apt install pulseaudio-utils ffmpeg。 - Web:
stop_recording()返回的是浏览器本地 Blob URL,而非真实文件路径;想要拿到录音字节,必须走流式方案(见下文)。
三、各平台麦克风权限配置
录音必须申请麦克风权限,官方文档 audiorecorder/index.md 给出了 flet build 命令与 pyproject.toml 两套等价配置方式。
Android
需要声明两项权限:
android.permission.RECORD_AUDIO:允许录音(必需);android.permission.MODIFY_AUDIO_SETTINGS(可选):允许使用蓝牙通话设备(耳机/耳塞)。
flet build apk \
--android-permissions android.permission.RECORD_AUDIO=true \
--android-permissions android.permission.MODIFY_AUDIO_SETTINGS=true
等价 pyproject.toml 配置:
[tool.flet.android.permission]
"android.permission.RECORD_AUDIO" = true
"android.permission.MODIFY_AUDIO_SETTINGS" = true
重要提醒:保存录音文件到应用自身目录(见
StoragePaths)无需任何存储权限;保存到其他位置应走FilePicker.save_file()系统选择器。申请WRITE_EXTERNAL_STORAGE/READ_EXTERNAL_STORAGE反而可能导致应用被 Google Play 拒绝。
iOS
需要 NSMicrophoneUsageDescription 权限描述文案:
flet build ipa \
--info-plist NSMicrophoneUsageDescription="Some message to describe why you need this permission..."
等价 pyproject.toml:
[tool.flet.ios.info]
NSMicrophoneUsageDescription = "Some message to describe why you need this permission..."
macOS
同时需要 Info.plist 描述与沙盒授权:
flet build macos \
--info-plist NSMicrophoneUsageDescription="Some message to describe why you need this permission..." \
--macos-entitlements com.apple.security.device.audio-input=true
等价 pyproject.toml:
[tool.flet.macos.info]
NSMicrophoneUsageDescription = "Some message to describe why you need this permission..."
[tool.flet.macos.entitlement]
"com.apple.security.device.audio-input" = true
Linux
安装系统依赖:
sudo apt install pulseaudio-utils ffmpeg
跨平台权限捆绑(推荐)
Flet 预定义了跨平台 microphone 权限捆绑,可一次性覆盖所有平台的麦克风权限配置:
flet build <target_platform> --permissions microphone
等价 pyproject.toml:
[tool.flet]
permissions = ["microphone"]
运行时权限检查
权限不仅要在打包时声明,应用运行时还需主动请求。源码 audio_recorder.py 中的 has_permission() 会在检查的同时发起权限请求:
async def has_permission(self) -> bool:
"""Checks if the app has permission to record audio, requesting it if needed."""
return await self._invoke_method("has_permission")
在示例 audio_recorder/main.py 中,通过按钮触发权限状态查询:
async def handle_has_permission(e: ft.Event[ft.Button]):
try:
status = await recorder.has_permission()
show_snackbar(f"Audio Recording Permission status: {status}")
except Exception as e:
show_snackbar(f"Error checking permission: {e}")
四、控件挂载与核心 API:Service 化后的使用方式
挂载位置:Page.services
0.80.0 起 AudioRecorder 是 ft.Service 类型控件,必须添加到 Page.services:
import flet as ft
import flet_audio_recorder as far
def main(page: ft.Page):
recorder = far.AudioRecorder(
configuration=far.AudioRecorderConfiguration(encoder=far.AudioEncoder.WAV),
on_state_change=lambda e: print(f"State Changed: {e.data}"),
)
page.services.append(recorder) # 关键:services 而非 overlay
# ... 其余 UI 代码
ft.run(main)
如果你仍按旧版习惯使用
page.overlay.append(recorder),将无法正常工作。
异步方法清单
0.80.0 起以下方法全部为 async,调用时需使用 await:
is_recording、stop_recording、cancel_recording、resume_recording、pause_recording、is_paused、is_supported_encoder、get_input_devices、has_permission。
控件属性与事件
从 audio_recorder.py 可看到控件级定义:
configuration: AudioRecorderConfiguration:默认录音配置(默认值为AudioRecorderConfiguration(),即 WAV 编码、立体声、44.1kHz);on_state_change:录音状态变化事件,载荷为AudioRecorderStateChangeEvent;on_upload:流式上传进度或错误事件,载荷为AudioRecorderUploadEvent;on_stream:PCM16 原始分块到达事件,载荷为AudioRecorderStreamEvent。
start_recording() 的签名与校验逻辑是理解整体 API 的关键(audio_recorder.py):
async def start_recording(
self,
output_path: Optional[str] = None,
configuration: Optional[AudioRecorderConfiguration] = None,
upload: Optional[AudioRecorderUploadSettings] = None,
) -> bool:
其内部做了两条硬性校验:
- 非 Web 平台、非流式场景下,
output_path必须提供,否则抛出ValueError; - 只要启用了流式(
upload或on_stream),编码器必须是AudioEncoder.PCM16BITS,否则抛出ValueError。对应代码:
is_streaming = upload is not None or self.on_stream is not None
if not is_streaming and not (self.page.web or output_path):
raise ValueError("output_path must be provided on platforms other than web")
...
if is_streaming and effective_configuration.encoder != AudioEncoder.PCM16BITS:
raise ValueError("Streaming recordings require AudioEncoder.PCM16BITS as encoder.")
五、录音配置详解:AudioRecorderConfiguration 与平台子配置
0.80.0 将所有录音参数收敛进 AudioRecorderConfiguration(types.py),这是一个 @ft.value 数据类,字段及默认值如下:
| 字段 | 默认值 | 说明 |
|---|---|---|
encoder | AudioEncoder.WAV | 输出格式/编码器 |
suppress_noise | False | 降噪(设备支持时),可能降低录音音量 |
cancel_echo | False | 回声消除(设备支持时),可能降低录音音量 |
auto_gain | False | 有限范围自动增益(设备支持时),可能降低录音音量 |
channels | 2 | 声道数,1=单声道、2=立体声,多数平台最多 2 声道 |
sample_rate | 44100 | 采样率(采样/秒) |
bit_rate | 128000 | 编码比特率(bit/s) |
device | None | 指定录音输入设备,None 为默认设备 |
android_configuration | AndroidRecorderConfiguration() | Android 专属配置 |
ios_configuration | IosRecorderConfiguration() | iOS 专属配置 |
注意:旧版的
channels_num在重构后更名为channels,迁移代码时别漏掉。
AudioEncoder 编码器枚举
types.py 定义 9 种编码器:
| 枚举值 | 底层值 | 典型用途 |
|---|---|---|
AACLC | aacLc | AAC-LC,流媒体与通用录音常用 |
AACELD | aacEld | AAC-ELD,适合 VoIP 等低延迟场景 |
AACHE | aacHe | AAC-HE,低码率下保持高质量 |
AMRNB | amrNb | AMR-NB,移动通信语音 |
AMRWB | amrWb | AMR-WB,更高质量语音 |
OPUS | opus | 语音与音频兼顾的通用编解码 |
FLAC | flac | 无损压缩 |
WAV | wav | 未压缩原始音频 |
PCM16BITS | pcm16bits | 16 位 PCM,流式录制专用 |
AndroidRecorderConfiguration
Android 专属配置(types.py):
use_legacy: bool = False:是否使用 AndroidMediaRecorder。默认使用高级录制器以解锁更多特性;legacy 录制器更注重稳定性。mute_audio: bool = False:静音所有音频流(闹钟、音乐、铃声等),适合录制纯净音频;停止录音后恢复原状,暂停/恢复期间维持当前状态。manage_bluetooth: bool = True:尝试建立蓝牙 SCO 连接(连接耳机/耳塞)。audio_source: AndroidAudioSource = AndroidAudioSource.DEFAULT_SOURCE:音频源,最常用DEFAULT_SOURCE或MIC。
AndroidAudioSource 枚举(types.py)包含 MIC、VOICE_UPLINK、VOICE_DOWNLINK、VOICE_CALL、CAMCORDER、VOICE_RECOGNITION、VOICE_COMMUNICATION、REMOTE_SUBMIX、UNPROCESSED、VOICE_PERFORMANCE 等,分别面向语音识别、VoIP、卡拉 OK 直播等场景调校。
IosRecorderConfiguration
iOS 专属配置(types.py)只有一个字段 options: list[IosAudioCategoryOption],默认值为 [DEFAULT_TO_SPEAKER, ALLOW_BLUETOOTH, ALLOW_BLUETOOTH_A2DP]。
IosAudioCategoryOption 枚举(types.py)涵盖:
MIX_WITH_OTHERS:与其他 App 音频混合播放;DUCK_OTHERS:本会话播放时降低其他会话音量;ALLOW_BLUETOOTH:允许蓝牙免提设备作为输入路由(iOS 9.0 起);DEFAULT_TO_SPEAKER:默认使用内置扬声器而非听筒;INTERRUPT_SPOKEN_AUDIO_AND_MIX_WITH_OTHERS:播放时暂停其他会话的语音内容(iOS 9.0 起);ALLOW_BLUETOOTH_A2DP:流式传输到支持 A2DP 的蓝牙设备(iOS 10.0 起);ALLOW_AIRPLAY:流式传输到 AirPlay 设备(iOS 10.0 起);OVERRIDE_MUTED_MICROPHONE_INTERRUPTION:系统静音内置麦克风时中断音频会话(iOS 14.5 起)。
六、基础录音实战:开始、停止、暂停、恢复
完整的可运行示例位于 audio_recorder/main.py,核心流程如下:
import flet as ft
import flet_audio_recorder as far
def main(page: ft.Page):
path = "test-audio-file.wav"
async def handle_recording_start(e: ft.Event[ft.Button]):
await recorder.start_recording(output_path=path)
async def handle_recording_stop(e: ft.Event[ft.Button]):
output_path = await recorder.stop_recording()
print(f"Stopped recording. Output Path: {output_path}")
# Web 平台返回 Blob URL,可直接交给 UrlLauncher 打开
if page.web and output_path is not None:
await ft.UrlLauncher().launch_url(output_path)
async def handle_pause(e: ft.Event[ft.Button]):
if await recorder.is_recording():
await recorder.pause_recording()
async def handle_resume(e: ft.Event[ft.Button]):
if await recorder.is_paused():
await recorder.resume_recording()
recorder = far.AudioRecorder(
configuration=far.AudioRecorderConfiguration(encoder=far.AudioEncoder.WAV),
on_state_change=lambda e: print(f"State Changed: {e.data}"),
)
page.services.append(recorder)
page.add(ft.Button("Start", on_click=handle_recording_start))
ft.run(main)
要点说明:
- 停止返回值:
stop_recording()在本地平台返回保存路径,在 Web 返回 Blob URL,流式场景返回None(audio_recorder.py)。 - 状态机:
AudioRecorderState枚举为STOPPED/RECORDING/PAUSED(types.py),is_recording()与is_paused()可用于动作前的状态判断。 - 设备枚举:
get_input_devices()返回list[InputDevice](id+label),可用于让用户选择录音设备(audio_recorder.py)。 - 编码器探测:
is_supported_encoder(encoder)用于运行时探测平台支持的编码器,避免选用不可用格式。
七、PCM16 流式录制:on_stream 分块回调
适用场景
Web 平台上 stop_recording() 只能拿到 Blob URL;当你需要真正访问录音字节(例如转写、分析、自建容器封装)时,应使用 PCM16 流式录制。on_stream 在所有平台均可用。
流式分块事件 AudioRecorderStreamEvent 携带三个字段(types.py):
chunk: bytes:原始 PCM16 音频字节;sequence: int:递增的分块序号;bytes_streamed: int:累计流出的总字节数。
完整示例:流式采集并封装 WAV
示例 stream_and_download/main.py 演示了“采集 PCM16 分块 → Python 侧封装 WAV → FilePicker 保存/下载”的完整链路:
import io
import time
import wave
import flet as ft
import flet_audio_recorder as far
SAMPLE_RATE = 44100
CHANNELS = 1
BYTES_PER_SAMPLE = 2 # 16-bit PCM
def pcm_to_wav_bytes(pcm_data: bytes) -> bytes:
wav_buffer = io.BytesIO()
with wave.open(wav_buffer, "wb") as wav:
wav.setnchannels(CHANNELS)
wav.setsampwidth(BYTES_PER_SAMPLE)
wav.setframerate(SAMPLE_RATE)
wav.writeframes(pcm_data)
return wav_buffer.getvalue()
def main(page: ft.Page):
buffer = bytearray()
def handle_stream(e: far.AudioRecorderStreamEvent):
buffer.extend(e.chunk)
status.value = f"Streaming chunk {e.sequence}; {e.bytes_streamed} bytes collected."
async def handle_recording_start(e: ft.Event[ft.Button]):
if not await recorder.has_permission():
show_snackbar("Microphone permission is required.")
return
buffer.clear()
await recorder.start_recording(
configuration=far.AudioRecorderConfiguration(
encoder=far.AudioEncoder.PCM16BITS,
sample_rate=SAMPLE_RATE,
channels=CHANNELS,
),
)
async def handle_recording_stop(e: ft.Event[ft.Button]):
await recorder.stop_recording()
if not buffer:
return
wav_bytes = pcm_to_wav_bytes(bytes(buffer))
file_name = f"recording-{int(time.time())}.wav"
file_path = await ft.FilePicker().save_file(
file_name=file_name,
file_type=ft.FilePickerFileType.CUSTOM,
allowed_extensions=["wav"],
src_bytes=wav_bytes,
)
if file_path and not (page.web or page.platform.is_mobile()):
with open(file_path, "wb") as output:
output.write(wav_bytes)
recorder = far.AudioRecorder(on_stream=handle_stream)
page.services.append(recorder)
ft.run(main)
关键点:
- 编码器必须为
PCM16BITS:start_recording()会在底层强制校验,否则抛出ValueError; - 原始 PCM16 字节不可直接播放:必须像示例中那样用 Python
wave模块封装成 WAV 容器,才能作为音频文件保存或下载; - WAV 封装参数需与录制配置一致:封装时的声道数、采样宽度、采样率必须与
AudioRecorderConfiguration中的channels、sample_rate对应(示例统一使用常量SAMPLE_RATE/CHANNELS),否则文件会失真或无法播放。
八、流式直传上传:AudioRecorderUploadSettings
上传设置
AudioRecorderUploadSettings(types.py)用于将录音字节在录制过程中直接上传,字段如下:
upload_url: str(必填):上传目标 URL,典型来源是Page.get_upload_url()返回的上传地址;method: str = "PUT":HTTP 方法;headers: Optional[dict[str, str]] = None:自定义 HTTP 请求头;file_name: Optional[str] = None:上传事件中报告的用户友好文件名。
上传进度通过 on_upload 事件回调,载荷 AudioRecorderUploadEvent 包含(types.py):
file_name:由AudioRecorderUploadSettings.file_name提供的名称;progress:0.0~1.0的上传进度(流式上传在录音停止前不知道总大小,所以录制过程中通常应看bytes_uploaded);bytes_uploaded:已上传字节数;error:上传失败时的错误信息。
完整示例:边录边传
示例 upload/main.py 展示了与 Flet 服务端上传能力联动的完整流程:
import time
import flet as ft
import flet_audio_recorder as far
def main(page: ft.Page):
def handle_upload(e: far.AudioRecorderUploadEvent):
if e.error:
status.value = f"Upload error: {e.error}"
elif e.progress == 1:
status.value = f"Upload complete: {e.bytes_uploaded or 0} bytes."
else:
status.value = f"Uploading: {e.bytes_uploaded or 0} bytes sent."
async def handle_recording_start(e: ft.Event[ft.Button]):
if not await recorder.has_permission():
show_snackbar("Microphone permission is required.")
return
file_name = f"recordings/rec-{int(time.time())}.pcm"
try:
upload_url = page.get_upload_url(file_name=file_name, expires=600)
except RuntimeError as ex:
if "FLET_SECRET_KEY" not in str(ex):
raise
status.value = "Uploads require a secret key. Set FLET_SECRET_KEY before running this app."
return
await recorder.start_recording(
upload=far.AudioRecorderUploadSettings(
upload_url=upload_url,
file_name=file_name,
),
configuration=far.AudioRecorderConfiguration(
encoder=far.AudioEncoder.PCM16BITS,
channels=1,
),
)
async def handle_recording_stop(e: ft.Event[ft.Button]):
await recorder.stop_recording()
recorder = far.AudioRecorder(on_upload=handle_upload)
page.services.append(recorder)
ft.run(
main,
upload_dir="uploads", # 服务端须开启上传目录
)
实践要点:
- 服务端前提:内置上传 URL 来自
Page.get_upload_url(),它要求应用以upload_dir参数运行(如上例的upload_dir="uploads"),并设置环境变量FLET_SECRET_KEY用于签名; - 上传内容为原始 PCM16 字节:上传文件并不包含 WAV 等可播放容器,示例中刻意使用
.pcm扩展名;如需可播放文件,参考第七节先封装 WAV 再上传; - 进度展示:录制过程中
progress字段不可靠(总大小未知),应优先用bytes_uploaded展示已发送字节数,progress == 1时才视为完成。
九、常见问题与迁移速查
从 0.1.0 迁移到 0.80.0+ 的速查表
| 旧写法 | 新写法 |
|---|---|
page.overlay.append(recorder) | page.services.append(recorder) |
recorder.audio_encoder = ft.AudioEncoder.WAV | 移入 configuration=AudioRecorderConfiguration(encoder=...) |
channels_num | configuration.channels |
on_state_changed | on_state_change |
await recorder.is_recording(wait_timeout=5) | await recorder.is_recording(timeout=5) |
| 同步调用各控制方法 | 全部 await 异步调用 |
高频踩坑清单
- 控件未挂载到
Page.services:报错或事件不触发,先检查挂载位置; - 非 Web 平台漏传
output_path:触发ValueError: output_path must be provided on platforms other than web; - 流式场景未用
PCM16BITS:触发ValueError: Streaming recordings require AudioEncoder.PCM16BITS as encoder.; - WAV 封装参数与录制配置不一致:导致文件无法播放或声音异常,务必让
channels/sample_rate保持一致; - 上传 500/签名错误:检查应用是否以
upload_dir运行且设置了FLET_SECRET_KEY。
十、源码地图:继续深入阅读
- 控件 API 与异步方法实现:audio_recorder.py
- 全部数据类与枚举定义:types.py
- 包配置与平台支持说明:pyproject.toml、README.md
- 基础录音示例:audio_recorder/main.py
- 流式采集并封装 WAV 示例:stream_and_download/main.py
- 流式直传上传示例:upload/main.py
- 官方使用文档:audiorecorder/index.md
- 类型参考文档:types/
结合以上文档、源码与三个可运行示例,你可以快速构建出覆盖“基础录音 → 状态控制 → 流式采集 → 直传上传”全链路的音频录制功能,并从容应对 0.80.0 重构带来的 API 变化。
【免费下载链接】flet
Build realtime web, mobile and desktop apps in Python only. No frontend experience required.
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



