flet-audio-recorder v1

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+      - v1
+    paths:
+      - 'LICENSE'
+      - 'CHANGELOG.md'
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+      - 'src/flet_audio_recorder/**'
+      - 'examples/audio_recorder_example/src/**'
+
+  workflow_dispatch:    # Allow manual trigger from the GitHub Actions UI
+
+concurrency:
+  group: "docs"                   # Prevent multiple overlapping deploys
+  cancel-in-progress: false       # Allow in-progress deploys to finish
+
+permissions:
+  contents: write  # Required to push to the gh-pages branch
+
+env:
+  GH_TOKEN: ${{ secrets.GH_TOKEN }}         # Token used by mkdocs for pushing
+  UV_SYSTEM_PYTHON: 1                       # Use system Python interpreter with uv
+
+jobs:
+  deploy:
+    name: Deploy Documentation
+    runs-on: ubuntu-latest
+    if: github.repository == github.event.repository.full_name  # don't run on forks
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Configure Git for mkdocs
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"  # Match Python version with project config
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e .
+          uv pip install --group docs
+
+      - name: Deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

.gitignore

@@ -4,3 +4,4 @@ develop-eggs/
 dist/
 .DS_store
 /site
+.venv/

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+  - repo: https://github.com/ambv/black
+    rev: 22.12.0
+    hooks:
+      - id: black

CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] - 2025-06-dd
+
+### Added
+
+- Deployed online documentation: https://flet-dev.github.io/flet-audiorecorder/
+- `AudioRecorder` control new property: `configuration`
+- New dataclasses:
+    - `AudioRecorderConfiguration`
+    - `AndroidRecorderConfiguration`
+    - `IosRecorderConfiguration`
+    - `InputDevice`
+- New enums:
+    - `AndroidAudioSource`
+    - `IosAudioCategoryOption`
+
+### Changed
+
+- Refactored `AudioRecorder` control to use `@ft.control` dataclass-style definition and switched to `Service` control type
+
+#### Breaking Changes
+
+- `AudioRecorder` must now be added to `Page.services` instead of `Page.overlay`.
+- Recording configuration properties (`audio_encoder`, `suppress_noise`, `cancel_echo`, `auto_gain`, `channels_num`, `sample_rate`, `bit_rate`) are now grouped under `configuration: AudioRecorderConfiguration`
+- Event `on_state_changed` renamed to `on_state_change`
+- In all methods, parameter `wait_timeout` was renamed to `timeout`.
+- The following sync methods were removed from `AudioRecorder` (use corresponding async methods instead):
+    - `is_recording` → `is_recording_async`
+    - `stop_recording` → `stop_recording_async`
+    - `cancel_recording` → `cancel_recording_async`
+    - `resume_recording` → `resume_recording_async`
+    - `pause_recording` → `pause_recording_async`
+    - `is_paused` → `is_paused_async`
+    - `is_supported_encoder` → `is_supported_encoder_async`
+    - `get_input_devices` → `get_input_devices_async`
+    - `has_permission` → `has_permission_async`
+
+## [0.1.0] - 2025-01-15
+
+Initial release.
+
+
+[Unreleased]: https://github.com/flet-dev/flet-audio-recorder/compare/0.1.0...HEAD
+[0.1.0]: https://github.com/flet-dev/flet-audio-recorder/releases/tag/0.1.0

docs/audio_recorder.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.audio_recorder.AudioRecorder

docs/changelog.md

@@ -0,0 +1,5 @@
+---
+title: Changelog
+---
+
+--8<-- "CHANGELOG.md"

docs/index.md

@@ -1,98 +1,55 @@
-# Getting Started
+# flet-audio-recorder
 
-Audio recorder from microphone to a given file path. Works on macOS, Linux, Windows, iOS, Android and web.
-Based on the [record](https://pub.dev/packages/record) Dart/Flutter package.
+[![pypi](https://img.shields.io/pypi/v/flet-audio-recorder.svg)](https://pypi.python.org/pypi/flet-audio-recorder)
+[![downloads](https://static.pepy.tech/badge/flet-audio-recorder/month)](https://pepy.tech/project/flet-audio-recorder)
+[![license](https://img.shields.io/github/license/flet-dev/flet-audio-recorder.svg)](https://github.com/flet-dev/flet-audio-recorder/blob/main/LICENSE)
 
-**NOTE:** On Linux, encoding is provided by [fmedia](https://stsaz.github.io/fmedia/) which must be installed separately.
+Adds audio recording support to Flet apps.
 
-AudioRecorder control is non-visual and should be added to `page.overlay` list.
+It is based on the [record](https://pub.dev/packages/record) Flutter package.
 
-## Installation
+## Platform Support
 
-Add `flet-audio-recorder` as dependency to `pyproject.toml` of your Flet app:
+This package supports the following platforms:
 
-```
-dependencies = [
-  "flet-audio-recorder",
-  "flet>=0.27.4",
-]
-```
-
-## Example
-
-```py
-
-import flet as ft
-
-import flet_audio_recorder as far
-
-async def main(page: ft.Page):
-    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER
-    page.appbar = ft.AppBar(title=ft.Text("Audio Recorder"), center_title=True)
+| Platform | Supported |
+|----------|:---------:|
+| Windows  |     ✅     |
+| macOS    |     ✅     |
+| Linux    |     ✅     |
+| iOS      |     ✅     |
+| Android  |     ✅     |
+| Web      |     ✅     |
 
-    path = "test-audio-file.wav"
+## Usage
 
-    async def handle_start_recording(e):
-        print(f"StartRecording: {path}")
-        await audio_rec.start_recording_async(path)
+### Installation
 
-    async def handle_stop_recording(e):
-        output_path = await audio_rec.stop_recording_async()
-        print(f"StopRecording: {output_path}")
-        if page.web and output_path is not None:
-            await page.launch_url_async(output_path)
+To install the `flet-audio-recorder` package and add it to your project dependencies:
 
-    async def handle_list_devices(e):
-        devices = await audio_rec.get_input_devices_async()
-        print(devices)
+=== "uv"
+    ```bash
+    uv add flet-audio-recorder
+    ```
 
-    async def handle_has_permission(e):
-        try:
-            print(f"HasPermission: {await audio_rec.has_permission_async()}")
-        except Exception as e:
-            print(e)
+=== "pip"
+    ```bash
+    pip install flet-audio-recorder  # (1)!
+    ```
+
+    1. After this, you will have to manually add this package to your `requirements.txt` or `pyproject.toml`.
 
-    async def handle_pause(e):
-        print(f"isRecording: {await audio_rec.is_recording_async()}")
-        if await audio_rec.is_recording_async():
-            await audio_rec.pause_recording_async()
+=== "poetry"
+    ```bash
+    poetry add flet-audio-recorder
+    ```
 
-    async def handle_resume(e):
-        print(f"isPaused: {await audio_rec.is_paused_async()}")
-        if await audio_rec.is_paused_async():
-            await audio_rec.resume_recording_async()
+???+ note
+    On Linux, encoding is provided by [fmedia](https://stsaz.github.io/fmedia/) which must be installed separately.
 
-    async def handle_audio_encoding_test(e):
-        for i in list(far.AudioEncoder):
-            print(f"{i}: {await audio_rec.is_supported_encoder_async(i)}")
-
-    async def handle_state_change(e):
-        print(f"State Changed: {e.data}")
-
-    audio_rec = far.AudioRecorder(
-        audio_encoder=far.AudioEncoder.WAV,
-        on_state_changed=handle_state_change,
-    )
-    page.overlay.append(audio_rec)
-    await page.update_async()
-
-    await page.add_async(
-        ft.ElevatedButton("Start Audio Recorder", on_click=handle_start_recording),
-        ft.ElevatedButton("Stop Audio Recorder", on_click=handle_stop_recording),
-        ft.ElevatedButton("List Devices", on_click=handle_list_devices),
-        ft.ElevatedButton("Pause Recording", on_click=handle_pause),
-        ft.ElevatedButton("Resume Recording", on_click=handle_resume),
-        ft.ElevatedButton("Test AudioEncodings", on_click=handle_audio_encoding_test),
-        ft.ElevatedButton("Has Permission", on_click=handle_has_permission),
-    )
 
+## Example
 
-ft.app(main)
+```python title="main.py"
+--8<-- "examples/audio_recorder_example/src/main.py"
 ```
-
-## Classes
-
-- [AudioRecorder](audiorecorder.md)
-- [AudioEncoder](audioencoder.md)
-
-

docs/license.md

@@ -0,0 +1,3 @@
+```
+--8<-- "LICENSE"
+```

docs/types/android_audio_source.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.AndroidAudioSource

docs/types/android_recorder_configuration.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.AndroidRecorderConfiguration

docs/types/audio_recorder_configuration.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.AudioRecorderConfiguration

docs/types/audio_recorder_state.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.AudioRecorderState

docs/types/audioencoder.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.AudioEncoder

docs/types/audiorecorderstate.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.AudioRecorderState

docs/types/audiorecorderstatechangeevent.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.AudioRecorderStateChangeEvent

docs/types/input_device.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.InputDevice

docs/types/ios_audio_category_option.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.IosAudioCategoryOption

docs/types/ios_recorder_configuration.md

@@ -0,0 +1 @@
+::: flet_audio_recorder.types.IosRecorderConfiguration

examples/audio_recorder_example/pyproject.toml

@@ -1,34 +1,19 @@
 [project]
-name = "audio_recorder_example"
+name = "flet-audio-recorder-example"
 version = "1.0.0"
-description = ""
+description = "Flet AudioRecorder Example"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 dependencies = [
-  "flet-audio-recorder @ git+https://github.com/flet-dev/flet-audio-recorder.git",
-  "flet>=0.25.2",
+  "flet-audio-recorder",
+  "flet",
 ]
-
-
+# Docs: https://flet.dev/docs/publish
 [tool.flet]
-# org name in reverse domain name notation, e.g. "com.mycompany".
-# Combined with project.name to build bundle ID for iOS and Android apps
 org = "com.mycompany"
-
-# project display name that is used as an app title on Android and iOS home screens,
-# shown in window titles and about app dialogs on desktop.
-product = "Flet Audio Example"
-
-# company name to display in about app dialogs
+product = "flet-audio-recorder-example"
 company = "Flet"
-
-# copyright text to display in about app dialogs
 copyright = "Copyright (C) 2024 by Flet"
 
 [tool.flet.app]
 path = "src"
-
-[tool.uv]
-dev-dependencies = [
-    "flet[all]>=0.25.2",
-]