feat(flet-audio-recorder): Add streaming and upload support to AudioRecorder

[ndonkoHenri]

Fixes #5858

Adds PCM16 streaming support to flet-audio-recorder.
Will help web apps access recorded audio bytes directly instead of relying on browser-local Blob URLs.

Test Code

import wave

import flet as ft
import flet_audio_recorder as far

SAMPLE_RATE = 44100
CHANNELS = 1
BYTES_PER_SAMPLE = 2
OUTPUT_FILE = "streamed-recording.wav"


def main(page: ft.Page):
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    buffer = bytearray()

    def show_snackbar(message: str):
        page.show_dialog(ft.SnackBar(content=message, duration=ft.Duration(seconds=5)))

    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()
        status.value = "Recording..."
        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:
            show_snackbar("Nothing was recorded.")
            return

        with wave.open(OUTPUT_FILE, "wb") as wav:
            wav.setnchannels(CHANNELS)
            wav.setsampwidth(BYTES_PER_SAMPLE)
            wav.setframerate(SAMPLE_RATE)
            wav.writeframes(buffer)

        status.value = f"Saved {len(buffer)} bytes to {OUTPUT_FILE}."
        show_snackbar(status.value)

    recorder = far.AudioRecorder(on_stream=handle_stream)

    page.add(
        ft.SafeArea(
            content=ft.Column(
                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
                controls=[
                    ft.Text("Record PCM16 audio chunks and save them as a WAV file."),
                    ft.Button("Start streaming", on_click=handle_recording_start),
                    ft.Button("Stop and save", on_click=handle_recording_stop),
                    status := ft.Text(),
                ],
            ),
        )
    )


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

Summary by Sourcery

Add PCM16-based streaming and upload capabilities to AudioRecorder, enabling direct access to raw audio bytes and live HTTP uploads alongside traditional file recording.

New Features:

• Introduce streaming recording mode that emits raw PCM16 chunks via the AudioRecorder.on_stream event across platforms.
• Add upload support for streaming recordings using AudioRecorderUploadSettings to send PCM16 bytes directly to HTTP endpoints while recording.
• Expose AudioRecorderUploadEvent and AudioRecorderStreamEvent payload types for upload progress/errors and streaming chunk metadata, respectively.

Enhancements:

• Extend AudioRecorder.start_recording to validate streaming-compatible encoders, support optional upload settings, and clarify permission semantics.
• Implement internal streaming session management in the Flutter service to coordinate record stream subscriptions, chunk counting, HTTP streamed requests, and cleanup on stop/cancel.
• Improve AudioRecorder service disposal to correctly tear down streaming subscriptions and in-flight uploads.
• Clarify SnackBar documentation with an inline usage example.

Documentation:

• Restructure AudioRecorder docs into multiple examples, adding dedicated sections for basic file recording, streaming chunks, and streaming upload workflows.
• Document new AudioRecorderStreamEvent, AudioRecorderUploadEvent, and AudioRecorderUploadSettings types and link them from the AudioRecorder service docs.
• Update sidebars to surface new AudioRecorder streaming and upload type documentation.

Tests:

• Add example apps demonstrating PCM16 chunk streaming to WAV and streaming upload to Flet upload storage, including corresponding project metadata.

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[cloudflare-workers-and-pages]

Deploying flet-website-v2 with    Cloudflare Pages

Latest commit:	dcbf3c6
Status:	✅  Deploy successful!
Preview URL:	https://cb95eebb.flet-website-v2.pages.dev
Branch Preview URL:	https://audiorec-stream-upload.flet-website-v2.pages.dev

View logs

[Copilot]

Pull request overview

Adds PCM16 streaming and direct upload capabilities to the flet-audio-recorder service so web (and other) apps can access recorded audio bytes during recording instead of relying on Blob URLs returned by stop_recording().

Changes:

• Implemented streaming recording path in the Flutter service, with optional chunk forwarding to Python and/or chunked HTTP upload.
• Added new Python types/events (AudioRecorderStreamEvent, AudioRecorderUploadEvent, AudioRecorderUploadSettings) and extended AudioRecorder.start_recording() to support streaming/upload.
• Expanded docs and examples to cover basic recording, streaming-to-Python, and streaming upload workflows.

Reviewed changes

Copilot reviewed 18 out of 20 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
website/sidebars.yml	Adds new AudioRecorder type docs to the YAML sidebar navigation.
website/sidebars.js	Adds new AudioRecorder type docs to the JS sidebar navigation.
website/docs/services/audiorecorder/types/audiorecorderuploadsettings.md	New API doc stub for AudioRecorderUploadSettings.
website/docs/services/audiorecorder/types/audiorecorderuploadevent.md	New API doc stub for AudioRecorderUploadEvent.
website/docs/services/audiorecorder/types/audiorecorderstreamevent.md	New API doc stub for AudioRecorderStreamEvent.
website/docs/services/audiorecorder/index.md	Updates service docs to include multiple examples and explain streaming/upload behavior on web.
sdk/python/packages/flet/src/flet/controls/material/snack_bar.py	Minor docstring formatting update for SnackBar example.
sdk/python/packages/flet-audio-recorder/src/flutter/flet_audio_recorder/pubspec.yaml	Adds http dependency required for chunked upload implementation.
sdk/python/packages/flet-audio-recorder/src/flutter/flet_audio_recorder/lib/src/audio_recorder.dart	Implements streaming recording session management, Python stream events, and chunked HTTP upload with progress/error events.
sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/types.py	Adds new stream/upload event dataclasses and AudioRecorderUploadSettings value type.
sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/audio_recorder.py	Extends Python API: new handlers, streaming/upload argument, PCM16 enforcement, updated docstrings.
sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/init.py	Exposes the new types/events from the package top-level.
sdk/python/packages/flet-audio-recorder/CHANGELOG.md	Documents the new streaming + upload features under 0.85.0.
sdk/python/examples/services/audio_recorder/upload/pyproject.toml	New example project metadata for streaming upload.
sdk/python/examples/services/audio_recorder/upload/main.py	New example demonstrating upload while recording with progress events.
sdk/python/examples/services/audio_recorder/stream/pyproject.toml	New example project metadata for streaming chunks to Python.
sdk/python/examples/services/audio_recorder/stream/main.py	New example demonstrating receiving PCM16 chunks and wrapping into WAV.
sdk/python/examples/services/audio_recorder/basic/pyproject.toml	Renames/retitles the “basic” example metadata to match updated docs.
sdk/python/examples/services/audio_recorder/basic/main.py	Adds/updates the basic recording example code referenced by docs.
client/pubspec.lock	Updates Flutter client lockfile (including flet version and transitive deps).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cloudflare-workers-and-pages]

Deploying flet-examples with    Cloudflare Pages

Latest commit:	dcbf3c6
Status:	✅  Deploy successful!
Preview URL:	https://9f4b86f3.flet-examples.pages.dev
Branch Preview URL:	https://audiorec-stream-upload.flet-examples.pages.dev

View logs