Flet AudioRecorder 音频录制指南:从基础录音到 PCM16 流式上传的完整实践

  • 前端
  • 跨平台
  • 桌面应用
  • 移动开发

【免费下载链接】flet

Build realtime web, mobile and desktop apps in Python only. No frontend experience required.

项目地址: https://gitcode.com/gh_mirrors/fl/flet
点击查看 免费下载

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 包实现,全平台可用:

平台WindowsmacOSLinuxiOSAndroidWeb
支持✅✅✅✅✅✅

需要注意的运行时前提:

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

其内部做了两条硬性校验:

  1. 非 Web 平台、非流式场景下,output_path 必须提供,否则抛出 ValueError;
  2. 只要启用了流式(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 数据类,字段及默认值如下:

字段默认值说明
encoderAudioEncoder.WAV输出格式/编码器
suppress_noiseFalse降噪(设备支持时),可能降低录音音量
cancel_echoFalse回声消除(设备支持时),可能降低录音音量
auto_gainFalse有限范围自动增益(设备支持时),可能降低录音音量
channels2声道数,1=单声道、2=立体声,多数平台最多 2 声道
sample_rate44100采样率(采样/秒)
bit_rate128000编码比特率(bit/s)
deviceNone指定录音输入设备,None 为默认设备
android_configurationAndroidRecorderConfiguration()Android 专属配置
ios_configurationIosRecorderConfiguration()iOS 专属配置

注意:旧版的 channels_num 在重构后更名为 channels,迁移代码时别漏掉。

AudioEncoder 编码器枚举

types.py 定义 9 种编码器:

枚举值底层值典型用途
AACLCaacLcAAC-LC,流媒体与通用录音常用
AACELDaacEldAAC-ELD,适合 VoIP 等低延迟场景
AACHEaacHeAAC-HE,低码率下保持高质量
AMRNBamrNbAMR-NB,移动通信语音
AMRWBamrWbAMR-WB,更高质量语音
OPUSopus语音与音频兼顾的通用编解码
FLACflac无损压缩
WAVwav未压缩原始音频
PCM16BITSpcm16bits16 位 PCM,流式录制专用

AndroidRecorderConfiguration

Android 专属配置(types.py):

  • use_legacy: bool = False:是否使用 Android MediaRecorder。默认使用高级录制器以解锁更多特性;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)

关键点:

  1. 编码器必须为 PCM16BITS:start_recording() 会在底层强制校验,否则抛出 ValueError;
  2. 原始 PCM16 字节不可直接播放:必须像示例中那样用 Python wave 模块封装成 WAV 容器,才能作为音频文件保存或下载;
  3. 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",  # 服务端须开启上传目录
    )

实践要点:

  1. 服务端前提:内置上传 URL 来自 Page.get_upload_url(),它要求应用以 upload_dir 参数运行(如上例的 upload_dir="uploads"),并设置环境变量 FLET_SECRET_KEY 用于签名;
  2. 上传内容为原始 PCM16 字节:上传文件并不包含 WAV 等可播放容器,示例中刻意使用 .pcm 扩展名;如需可播放文件,参考第七节先封装 WAV 再上传;
  3. 进度展示:录制过程中 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_numconfiguration.channels
on_state_changedon_state_change
await recorder.is_recording(wait_timeout=5)await recorder.is_recording(timeout=5)
同步调用各控制方法全部 await 异步调用

高频踩坑清单

  1. 控件未挂载到 Page.services:报错或事件不触发,先检查挂载位置;
  2. 非 Web 平台漏传 output_path:触发 ValueError: output_path must be provided on platforms other than web;
  3. 流式场景未用 PCM16BITS:触发 ValueError: Streaming recordings require AudioEncoder.PCM16BITS as encoder.;
  4. WAV 封装参数与录制配置不一致:导致文件无法播放或声音异常,务必让 channels/sample_rate 保持一致;
  5. 上传 500/签名错误:检查应用是否以 upload_dir 运行且设置了 FLET_SECRET_KEY。

十、源码地图:继续深入阅读

结合以上文档、源码与三个可运行示例,你可以快速构建出覆盖“基础录音 → 状态控制 → 流式采集 → 直传上传”全链路的音频录制功能,并从容应对 0.80.0 重构带来的 API 变化。

  • 前端
  • 跨平台
  • 桌面应用
  • 移动开发

【免费下载链接】flet

Build realtime web, mobile and desktop apps in Python only. No frontend experience required.

项目地址: https://gitcode.com/gh_mirrors/fl/flet
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值