docs(audio-recorder): refine streaming docs

ndonkoHenri · ndonkoHenri · commit 52ba4eb8b3a6 · 2026-04-16T16:12:58.000+02:00
diff --git a/client/pubspec.lock b/client/pubspec.lock
@@ -157,10 +157,10 @@ packages:
     dependency: transitive
     description:
       name: characters
-      sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803
+      sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b
       url: "https://pub.dev"
     source: hosted
-    version: "1.4.0"
+    version: "1.4.1"
   charcode:
     dependency: transitive
     description:
@@ -359,7 +359,7 @@ packages:
       path: "../packages/flet"
       relative: true
     source: path
-    version: "0.82.2"
+    version: "0.85.0"
   flet_ads:
     dependency: "direct main"
     description:
@@ -911,18 +911,18 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2
+      sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.17"
+    version: "0.12.19"
   material_color_utilities:
     dependency: transitive
     description:
       name: material_color_utilities
-      sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec
+      sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b"
       url: "https://pub.dev"
     source: hosted
-    version: "0.11.1"
+    version: "0.13.0"
   media_kit:
     dependency: transitive
     description:
@@ -1628,10 +1628,10 @@ packages:
     dependency: transitive
     description:
       name: test_api
-      sha256: ab2726c1a94d3176a45960b6234466ec367179b87dd74f1611adb1f3b5fb9d55
+      sha256: "8161c84903fd860b26bfdefb7963b3f0b68fee7adea0f59ef805ecca346f0c7a"
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.7"
+    version: "0.7.10"
   torch_light:
     dependency: transitive
     description:
diff --git a/sdk/python/examples/services/audio_recorder/basic/main.py b/sdk/python/examples/services/audio_recorder/basic/main.py
diff --git a/sdk/python/examples/services/audio_recorder/basic/pyproject.toml b/sdk/python/examples/services/audio_recorder/basic/pyproject.toml
@@ -1,9 +1,9 @@
 [project]
-name = "services-audio-recorder-example-1"
+name = "services-audio-recorder-basic"
 version = "1.0.0"
 description = "Records audio, lists input devices, and checks recorder permissions from one screen."
 requires-python = ">=3.10"
-keywords = ["audio recorder", "example 1", "services", "async"]
+keywords = ["audio recorder", "basic", "services", "async"]
 authors = [{ name = "Flet team", email = "hello@flet.dev" }]
 dependencies = ["flet", "flet-audio-recorder"]
 
@@ -14,7 +14,7 @@ dev = ["flet-cli", "flet-desktop", "flet-web"]
 categories = ["Services/AudioRecorder"]
 
 [tool.flet.metadata]
-title = "Audio recorder example"
+title = "Audio recorder basic"
 controls = ["SafeArea", "Column", "Page", "AppBar", "Text", "Button", "AudioRecorder"]
 layout_pattern = "inline-actions"
 complexity = "basic"
diff --git a/sdk/python/examples/services/audio_recorder/stream/main.py b/sdk/python/examples/services/audio_recorder/stream/main.py
@@ -11,13 +11,11 @@
 
 def main(page: ft.Page):
     page.horizontal_alignment = ft.CrossAxisAlignment.CENTER
-    page.appbar = ft.AppBar(title=ft.Text("Audio Recorder Stream"), center_title=True)
 
     buffer = bytearray()
-    status = ft.Text("Waiting to record...")
 
     def show_snackbar(message: str):
-        page.show_dialog(ft.SnackBar(content=ft.Text(message)))
+        page.show_dialog(ft.SnackBar(content=message, duration=ft.Duration(seconds=5)))
 
     def handle_stream(e: far.AudioRecorderStreamEvent):
         buffer.extend(e.chunk)
@@ -55,23 +53,17 @@ async def handle_recording_stop(e: ft.Event[ft.Button]):
         status.value = f"Saved {len(buffer)} bytes to {OUTPUT_FILE}."
         show_snackbar(status.value)
 
-    recorder = far.AudioRecorder(
-        configuration=far.AudioRecorderConfiguration(
-            encoder=far.AudioEncoder.PCM16BITS,
-            sample_rate=SAMPLE_RATE,
-            channels=CHANNELS,
-        ),
-        on_stream=handle_stream,
-    )
+    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,
+                    status := ft.Text(),
                 ],
             ),
         )
diff --git a/sdk/python/examples/services/audio_recorder/upload/main.py b/sdk/python/examples/services/audio_recorder/upload/main.py
@@ -6,31 +6,40 @@
 
 def main(page: ft.Page):
     page.horizontal_alignment = ft.CrossAxisAlignment.CENTER
-    page.appbar = ft.AppBar(title=ft.Text("Audio Recorder Upload"), center_title=True)
-
-    upload_status = ft.Text("Waiting to record...")
 
     def show_snackbar(message: str):
-        page.show_dialog(ft.SnackBar(content=ft.Text(message)))
+        page.show_dialog(ft.SnackBar(content=message, duration=ft.Duration(seconds=5)))
 
     def handle_upload(e: far.AudioRecorderUploadEvent):
         if e.error:
-            upload_status.value = f"Upload error: {e.error}"
+            status.value = f"Upload error: {e.error}"
         elif e.progress == 1:
-            upload_status.value = f"Upload complete: {e.bytes_uploaded or 0} bytes."
+            status.value = f"Upload complete: {e.bytes_uploaded or 0} bytes."
         else:
-            upload_status.value = f"Uploading: {e.bytes_uploaded or 0} bytes sent."
+            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/recording-{int(time.time())}.pcm"
-        upload_status.value = "Recording..."
+        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."
+            )
+            show_snackbar(status.value)
+            return
+
+        status.value = "Recording..."
         await recorder.start_recording(
             upload=far.AudioRecorderUploadSettings(
-                upload_url=page.get_upload_url(file_name, expires=600),
+                upload_url=upload_url,
                 file_name=file_name,
             ),
             configuration=far.AudioRecorderConfiguration(
@@ -41,29 +50,29 @@ async def handle_recording_start(e: ft.Event[ft.Button]):
 
     async def handle_recording_stop(e: ft.Event[ft.Button]):
         await recorder.stop_recording()
-        show_snackbar("Recording stopped.")
+        show_snackbar(
+            "Recording stopped. See 'uploads/recordings' folder for the recorded file."
+        )
 
-    recorder = far.AudioRecorder(
-        configuration=far.AudioRecorderConfiguration(
-            encoder=far.AudioEncoder.PCM16BITS,
-            channels=1,
-        ),
-        on_upload=handle_upload,
-    )
+    recorder = far.AudioRecorder(on_upload=handle_upload)
 
     page.add(
         ft.SafeArea(
             content=ft.Column(
+                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
                 controls=[
                     ft.Text("Record PCM16 audio and upload it as it streams."),
                     ft.Button("Start upload", on_click=handle_recording_start),
                     ft.Button("Stop recording", on_click=handle_recording_stop),
-                    upload_status,
+                    status := ft.Text(),
                 ],
             ),
         )
     )
 
 
 if __name__ == "__main__":
-    ft.run(main, upload_dir="uploads")
+    ft.run(
+        main,
+        upload_dir="uploads",
+    )
diff --git a/sdk/python/packages/flet-audio-recorder/CHANGELOG.md b/sdk/python/packages/flet-audio-recorder/CHANGELOG.md
@@ -9,9 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
-- Added streaming recordings with `AudioRecorder.on_stream`.
-- Added direct streaming uploads with `AudioRecorderUploadSettings` and `AudioRecorder.on_upload`.
-- Added AudioRecorder streaming and upload examples.
+- Added PCM16 streaming to `AudioRecorder`, including `on_stream` chunks and direct upload support via `AudioRecorderUploadSettings`.
 
 ## 0.80.0
 
diff --git a/sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/audio_recorder.py b/sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/audio_recorder.py
@@ -21,9 +21,8 @@ class AudioRecorder(ft.Service):
     """
     A control that allows you to record audio from your device.
 
-    This control can record audio using different
-    audio encoders and also allows configuration
-    of various audio recording parameters such as
+    This control can record audio using different audio encoders and also allows
+    configuration of various audio recording parameters such as
     noise suppression, echo cancellation, and more.
     """
 
@@ -36,17 +35,18 @@ class AudioRecorder(ft.Service):
 
     on_state_change: Optional[ft.EventHandler[AudioRecorderStateChangeEvent]] = None
     """
-    Event handler that is called when the state of the audio recorder changes.
+    Called when recording state changes.
     """
 
     on_upload: Optional[ft.EventHandler[AudioRecorderUploadEvent]] = None
     """
-    Event handler that is called when a streaming upload reports progress or errors.
+    Called when streaming upload progress or errors are available.
     """
 
     on_stream: Optional[ft.EventHandler[AudioRecorderStreamEvent]] = None
     """
-    Event handler that is called with raw PCM16 chunks while recording streams.
+    Called when a raw :attr:`~flet_audio_recorder.AudioEncoder.PCM16BITS` \
+    recording chunk is available.
     """
 
     async def start_recording(
@@ -58,18 +58,21 @@ async def start_recording(
         """
         Starts recording audio and saves it to a file or streams it.
 
-        If neither :attr:`on_stream` nor `upload` is used, `output_path` must be
+        If neither `upload` nor :attr:`on_stream` is used, `output_path` must be
         provided on platforms other than web.
 
-        Streaming mode uses :attr:`~flet_audio_recorder.AudioEncoder.PCM16BITS`.
-        The emitted or uploaded chunks contain raw PCM16 data, not a WAV container.
+        When streaming, use :attr:`~flet_audio_recorder.AudioEncoder.PCM16BITS` as
+        encoder, in which case, then emitted or uploaded
+        :attr:`~flet_audio_recorder.AudioRecorderStreamEvent.chunk`s contain raw PCM16
+        data. In some usecases, these chunks could be wrapped in a container such as
+        WAV if the output must be directly playable as an audio file.
 
         Args:
             output_path: The file path where the audio will be saved.
                 It must be specified if not on web.
-            configuration: The configuration for the audio recorder.
-                If `None`, the `AudioRecorder.configuration` will be used.
-            upload: Optional upload settings to stream recording bytes directly
+            configuration: The configuration for the audio recorder. If `None`, the
+                :attr:`flet_audio_recorder.AudioRecorder.configuration` will be used.
+            upload: Upload settings to stream recording bytes directly
                 to a destination, for example a URL returned by
                 :meth:`flet.Page.get_upload_url`.
 
@@ -83,6 +86,7 @@ async def start_recording(
         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")
+
         return await self._invoke_method(
             method_name="start_recording",
             arguments={
@@ -108,7 +112,8 @@ async def stop_recording(self) -> Optional[str]:
         Stops the audio recording and optionally returns the path to the saved file.
 
         Returns:
-            The file path where the audio was saved or `None` when streaming.
+            The file path where the audio was saved or `None` when
+                streaming (i.e. when `upload` or :attr:`on_stream` is set).
         """
         return await self._invoke_method("stop_recording")
 
diff --git a/sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/types.py b/sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/types.py
@@ -41,7 +41,7 @@ class AudioRecorderStateChangeEvent(ft.Event["AudioRecorder"]):
     """
     Event payload for recorder state transitions.
 
-    Emitted by `AudioRecorder` when recording state changes.
+    Delivered by :attr:`flet_audio_recorder.AudioRecorder.on_state_change`.
     """
 
     state: AudioRecorderState
@@ -52,18 +52,21 @@ class AudioRecorderStateChangeEvent(ft.Event["AudioRecorder"]):
 class AudioRecorderUploadEvent(ft.Event["AudioRecorder"]):
     """
     Event payload for streaming recording uploads.
+
+    Delivered by :attr:`flet_audio_recorder.AudioRecorder.on_upload` for
+    uploads started with :meth:`flet_audio_recorder.AudioRecorder.start_recording`.
     """
 
     file_name: Optional[str] = None
-    """Name associated with the current upload."""
+    """Name provided by :attr:`AudioRecorderUploadSettings.file_name`."""
 
     progress: Optional[float] = None
     """
     Upload progress from `0.0` to `1.0`.
 
     Streaming uploads do not know their total size until recording stops, so
-    :attr:`bytes_uploaded` is usually the best progress indicator while
-    recording is active.
+    :attr:`bytes_uploaded` is usually the best progress indicator while recording is
+    active.
     """
 
     bytes_uploaded: Optional[int] = None
@@ -77,16 +80,21 @@ class AudioRecorderUploadEvent(ft.Event["AudioRecorder"]):
 class AudioRecorderStreamEvent(ft.Event["AudioRecorder"]):
     """
     Event payload for raw recording stream chunks.
+
+    Delivered by :attr:`flet_audio_recorder.AudioRecorder.on_stream`.
     """
 
     chunk: bytes
-    """Raw PCM16 audio bytes emitted by the recorder."""
+    """
+    Raw :attr:`~flet_audio_recorder.AudioEncoder.PCM16BITS` audio bytes emitted by \
+    :class:`~flet_audio_recorder.AudioRecorder`.
+    """
 
     sequence: int
     """Incremental chunk number."""
 
     bytes_streamed: int
-    """Total number of bytes streamed so far."""
+    """Total number of bytes delivered through :attr:`chunk` so far."""
 
 
 class AudioEncoder(Enum):
@@ -407,6 +415,11 @@ class AudioRecorderConfiguration:
 class AudioRecorderUploadSettings:
     """
     Upload settings for streaming recordings.
+
+    Note:
+        Uploads started by :meth:`flet_audio_recorder.AudioRecorder.start_recording`
+        send raw :attr:`~flet_audio_recorder.AudioEncoder.PCM16BITS` bytes. They do
+        not add a playable audio container such as WAV.
     """
 
     upload_url: str
@@ -421,7 +434,7 @@ class AudioRecorderUploadSettings:
 
     headers: Optional[dict[str, str]] = None
     """
-    Optional HTTP headers sent with the upload request.
+    HTTP headers sent with the upload request.
     """
 
     file_name: Optional[str] = None
diff --git a/sdk/python/packages/flet/src/flet/controls/material/snack_bar.py b/sdk/python/packages/flet/src/flet/controls/material/snack_bar.py
@@ -157,10 +157,10 @@ class SnackBar(DialogControl):
     A lightweight message with an optional action which briefly displays at the bottom \
     of the screen.
 
+    Example:
     ```python
     page.show_dialog(ft.SnackBar(ft.Text("Opened snack bar")))
     ```
-
     """
 
     content: Annotated[
diff --git a/website/docs/services/audiorecorder/index.md b/website/docs/services/audiorecorder/index.md
