Update AudioFlinger docs

Author: ThomasFarstrike

docs/frameworks/audioflinger.md

@@ -1,25 +1,27 @@
 # AudioFlinger
 
-MicroPythonOS provides a centralized audio service called **AudioFlinger**, inspired by Android's architecture. It manages audio playback across different hardware outputs with priority-based audio focus control.
+MicroPythonOS provides a centralized audio service called **AudioFlinger**, inspired by Android's architecture. It manages audio playback and recording across different hardware outputs with priority-based audio focus control.
 
 ## Overview
 
 AudioFlinger provides:
 
 - **Priority-based audio focus** - Higher priority streams interrupt lower priority ones
 - **Multiple audio devices** - I2S digital audio, PWM buzzer, or both
-- **Background playback** - Runs in separate thread
+- **Background playback/recording** - Runs in separate thread
 - **WAV file support** - 8/16/24/32-bit PCM, mono/stereo, auto-upsampling
+- **WAV recording** - 16-bit mono PCM from I2S microphone
 - **RTTTL ringtone support** - Full Ring Tone Text Transfer Language parser
 - **Thread-safe** - Safe for concurrent access
 - **Hardware-agnostic** - Apps work across all platforms without changes
 
 ## Supported Audio Devices
 
-- **I2S**: Digital audio output for WAV file playback (Fri3d badge, Waveshare board)
+- **I2S Output**: Digital audio output for WAV file playback (Fri3d badge, Waveshare board)
+- **I2S Input**: Microphone recording (Fri3d badge only)
 - **Buzzer**: PWM-based tone/ringtone playback (Fri3d badge only)
 - **Both**: Simultaneous I2S and buzzer support
-- **Null**: No audio (desktop/Linux)
+- **Null**: No audio (desktop/Linux - simulated for testing)
 
 ## Quick Start
 
@@ -88,6 +90,130 @@ print(f"Current volume: {volume}")
 AudioFlinger.stop()
 ```
 
+## Recording Audio
+
+AudioFlinger supports recording audio from an I2S microphone to WAV files.
+
+### Basic Recording
+
+```python
+import mpos.audio.audioflinger as AudioFlinger
+
+# Check if microphone is available
+if AudioFlinger.has_microphone():
+    # Record for 10 seconds
+    success = AudioFlinger.record_wav(
+        file_path="data/my_recording.wav",
+        duration_ms=10000,
+        sample_rate=16000,
+        on_complete=lambda msg: print(msg)
+    )
+    
+    if success:
+        print("Recording started...")
+    else:
+        print("Recording failed to start")
+```
+
+### Recording Parameters
+
+- **file_path**: Path to save the WAV file
+- **duration_ms**: Maximum recording duration in milliseconds (default: 60000 = 60 seconds)
+- **sample_rate**: Sample rate in Hz (default: 16000 - good for voice)
+- **on_complete**: Callback function called when recording finishes
+
+### Stopping Recording
+
+```python
+# Stop recording early
+AudioFlinger.stop()
+```
+
+### Recording Constraints
+
+1. **Cannot record while playing**: I2S can only be TX (output) or RX (input) at one time
+2. **Cannot start new recording while recording**: Only one recording at a time
+3. **Microphone required**: `has_microphone()` must return `True`
+
+```python
+# Check recording state
+if AudioFlinger.is_recording():
+    print("Currently recording...")
+
+# Check playback state
+if AudioFlinger.is_playing():
+    print("Currently playing...")
+```
+
+### Complete Recording Example
+
+```python
+from mpos.apps import Activity
+import mpos.audio.audioflinger as AudioFlinger
+import lvgl as lv
+import time
+
+class SoundRecorderActivity(Activity):
+    def onCreate(self):
+        self.screen = lv.obj()
+        self.is_recording = False
+        
+        # Status label
+        self.status = lv.label(self.screen)
+        self.status.set_text("Ready")
+        self.status.align(lv.ALIGN.TOP_MID, 0, 20)
+        
+        # Record button
+        self.record_btn = lv.button(self.screen)
+        self.record_btn.set_size(120, 50)
+        self.record_btn.align(lv.ALIGN.CENTER, 0, 0)
+        self.record_label = lv.label(self.record_btn)
+        self.record_label.set_text("Record")
+        self.record_label.center()
+        self.record_btn.add_event_cb(self.toggle_recording, lv.EVENT.CLICKED, None)
+        
+        # Check microphone availability
+        if not AudioFlinger.has_microphone():
+            self.status.set_text("No microphone")
+            self.record_btn.add_flag(lv.obj.FLAG.HIDDEN)
+        
+        self.setContentView(self.screen)
+    
+    def toggle_recording(self, event):
+        if self.is_recording:
+            AudioFlinger.stop()
+            self.is_recording = False
+            self.record_label.set_text("Record")
+            self.status.set_text("Stopped")
+        else:
+            # Generate timestamped filename
+            t = time.localtime()
+            filename = f"data/recording_{t[0]}{t[1]:02d}{t[2]:02d}_{t[3]:02d}{t[4]:02d}.wav"
+            
+            success = AudioFlinger.record_wav(
+                file_path=filename,
+                duration_ms=60000,  # 60 seconds max
+                sample_rate=16000,
+                on_complete=self.on_recording_complete
+            )
+            
+            if success:
+                self.is_recording = True
+                self.record_label.set_text("Stop")
+                self.status.set_text("Recording...")
+            else:
+                self.status.set_text("Failed to start")
+    
+    def on_recording_complete(self, message):
+        # Called from recording thread - update UI safely
+        self.update_ui_threadsafe_if_foreground(self._update_ui_after_recording, message)
+    
+    def _update_ui_after_recording(self, message):
+        self.is_recording = False
+        self.record_label.set_text("Record")
+        self.status.set_text(message)
+```
+
 ## Audio Focus Priority
 
 AudioFlinger implements a 3-tier priority-based audio focus system inspired by Android:
@@ -125,20 +251,29 @@ AudioFlinger.play_wav("alarm.wav", stream_type=AudioFlinger.STREAM_ALARM)
 
 ## Hardware Support Matrix
 
-| Board | I2S | Buzzer | Notes |
-|-------|-----|--------|-------|
-| **Fri3d 2024 Badge** | ✅ GPIO 2, 47, 16 | ✅ GPIO 46 | Both devices available |
-| **Waveshare ESP32-S3** | ✅ GPIO 2, 47, 16 | ❌ | I2S only |
-| **Linux/macOS** | ❌ | ❌ | No audio (desktop builds) |
+| Board | I2S Output | I2S Microphone | Buzzer | Notes |
+|-------|------------|----------------|--------|-------|
+| **Fri3d 2024 Badge** | ✅ | ✅ | ✅ | Full audio support |
+| **Waveshare ESP32-S3** | ✅ | ❌ | ❌ | I2S output only |
+| **Linux/macOS** | ❌ | ✅ (simulated) | ❌ | Simulated recording for testing |
 
-**I2S Pins:**
-- **BCLK** (Bit Clock): GPIO 2
+**I2S Output Pins (DAC/Speaker):**
+- **BCK** (Bit Clock): GPIO 2
 - **WS** (Word Select): GPIO 47
 - **DOUT** (Data Out): GPIO 16
 
+**I2S Input Pins (Microphone):**
+- **SCLK** (Serial Clock): GPIO 17
+- **WS** (Word Select): GPIO 47 (shared with output)
+- **DIN** (Data In): GPIO 15
+
 **Buzzer Pin:**
 - **PWM**: GPIO 46 (Fri3d badge only)
 
+!!! note "I2S Limitation"
+    The ESP32 I2S peripheral can only be in TX (output) or RX (input) mode at one time.
+    You cannot play and record simultaneously.
+
 ## Configuration
 
 Audio device preference is configured in the Settings app under **"Advanced Settings"**:
@@ -222,7 +357,7 @@ class SimpleMusicPlayerActivity(Activity):
 
 ## API Reference
 
-### Functions
+### Playback Functions
 
 **`play_wav(path, stream_type=STREAM_MUSIC, volume=None, on_complete=None)`**
 
@@ -246,6 +381,39 @@ Play an RTTTL ringtone.
 
 - **Returns:** `bool` - `True` if playback started, `False` if rejected
 
+### Recording Functions
+
+**`record_wav(file_path, duration_ms=None, on_complete=None, sample_rate=16000)`**
+
+Record audio from I2S microphone to WAV file.
+
+- **Parameters:**
+  - `file_path` (str): Path to save WAV file (e.g., `"data/recording.wav"`)
+  - `duration_ms` (int, optional): Recording duration in milliseconds. Default: 60000 (60 seconds)
+  - `on_complete` (callable, optional): Callback function called when recording finishes
+  - `sample_rate` (int, optional): Sample rate in Hz. Default: 16000 (good for voice)
+
+- **Returns:** `bool` - `True` if recording started, `False` if rejected
+
+- **Rejection reasons:**
+  - No microphone available (`has_microphone()` returns `False`)
+  - Currently playing audio (I2S can only be TX or RX)
+  - Already recording
+
+**`is_recording()`**
+
+Check if audio is currently being recorded.
+
+- **Returns:** `bool` - `True` if recording active, `False` otherwise
+
+**`has_microphone()`**
+
+Check if I2S microphone is available for recording.
+
+- **Returns:** `bool` - `True` if microphone configured, `False` otherwise
+
+### Volume and Control Functions
+
 **`set_volume(volume)`**
 
 Set playback volume.
@@ -261,7 +429,27 @@ Get current playback volume.
 
 **`stop()`**
 
-Stop currently playing audio.
+Stop currently playing audio or recording.
+
+**`is_playing()`**
+
+Check if audio is currently playing.
+
+- **Returns:** `bool` - `True` if playback active, `False` otherwise
+
+### Hardware Detection Functions
+
+**`has_i2s()`**
+
+Check if I2S audio output is available for WAV playback.
+
+- **Returns:** `bool` - `True` if I2S configured, `False` otherwise
+
+**`has_buzzer()`**
+
+Check if buzzer is available for RTTTL playback.
+
+- **Returns:** `bool` - `True` if buzzer configured, `False` otherwise
 
 ### Stream Type Constants
 
@@ -387,6 +575,45 @@ ffmpeg -i input.wav -acodec pcm_s16le -ar 22050 -ac 1 output.wav
 - RTTTL requires hardware buzzer (Fri3d badge only)
 - I2S cannot produce RTTTL tones
 
+### Recording Not Working
+
+**Symptom**: `record_wav()` returns `False` or no audio recorded
+
+**Possible causes:**
+
+1. **No microphone available**
+   ```python
+   if not AudioFlinger.has_microphone():
+       print("No microphone on this device")
+   ```
+
+2. **Currently playing audio**
+   ```python
+   # I2S can only be TX or RX, not both
+   if AudioFlinger.is_playing():
+       AudioFlinger.stop()
+       time.sleep_ms(100)  # Wait for cleanup
+   AudioFlinger.record_wav("recording.wav")
+   ```
+
+3. **Already recording**
+   ```python
+   if AudioFlinger.is_recording():
+       print("Already recording")
+   ```
+
+4. **Wrong board** - Waveshare doesn't have a microphone
+
+### Recording Quality Issues
+
+**Symptom**: Recording sounds distorted or has noise
+
+**Solutions:**
+
+1. **Use appropriate sample rate**: 16000 Hz is good for voice, 44100 Hz for music
+2. **Check microphone placement**: Keep microphone away from noise sources
+3. **Verify I2S pin configuration**: Check board file for correct pin assignments
+
 ## Performance Tips
 
 ### Optimizing WAV Files
@@ -425,6 +652,23 @@ AudioFlinger.play_wav(
 - Buffers are allocated during playback and freed after
 - Multiple simultaneous streams not supported (priority system prevents this)
 
+## Desktop Testing
+
+On desktop builds (Linux/macOS), AudioFlinger provides simulated recording for testing:
+
+- **Microphone simulation**: Generates a 440Hz sine wave instead of real audio
+- **WAV file generation**: Creates valid WAV files that can be played back
+- **Real-time simulation**: Recording runs at realistic speed
+
+This allows testing the Sound Recorder app and other recording features without hardware.
+
+```python
+# Desktop simulation is automatic when machine.I2S is not available
+# The generated WAV file contains a 440Hz tone
+AudioFlinger.record_wav("test.wav", duration_ms=5000)
+# Creates a valid 5-second WAV file with 440Hz sine wave
+```
+
 ## See Also
 
 - [Creating Apps](../apps/creating-apps.md) - Learn how to create MicroPythonOS apps