feat: Add opt-in History audio attachments with playback (addresses infiniV/VoiceFlow#2) by EffortlessSteven · Pull Request #5 · infiniV/VoiceFlow

EffortlessSteven · 2025-12-17T17:24:03Z

Addresses #2.

Adds saveAudioToHistory setting (default: OFF) so VoiceFlow keeps its “RAM-only by default” behavior.
When enabled, after a successful transcription we persist that session’s audio as WAV (16kHz mono, 16-bit PCM) to ~/.VoiceFlow/audio/history_{id}.wav using temp-write + atomic replace, then attach per-row metadata on history.
Extends get_history to always return has_audio; include_audio_meta=true returns duration/size/mime when requested.
Adds get_history_audio(history_id) RPC returning { mime, base64, fileName?, sizeBytes?, durationMs? }; frontend plays via Blob URL and revokes URLs on close/unmount.

Privacy / lifecycle / safety

Audio save is best-effort and does not block transcript persistence (if audio write fails, the text history still saves).
Deleting a History entry, retention cleanup, and “Reset All Data” remove associated audio files.
Read/delete paths are guarded to stay under ~/.VoiceFlow/audio (prevents path traversal / escape).

Testing

pnpm tsc --noEmit
uv run -p .venv pytest src-pyloid/tests/

Summary by CodeRabbit

New Features
- Audio history support: Save and attach audio recordings to history entries for future reference.
- Audio playback: Play back recorded audio directly from history entries with visual indicators.
- Audio storage setting: New toggle in Settings to enable or disable automatic audio storage with history.
- Audio badges: Visual markers display on history entries that contain audio attachments.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

…ation chore: harden audio attachment validation

coderabbitai · 2025-12-17T17:24:13Z

Walkthrough

This PR implements a complete audio attachment feature for the application. Users can enable audio persistence in settings, and when enabled, dictation audio is automatically saved to history alongside transcription metadata. The feature includes backend storage with metadata tracking, database schema migration, new RPC endpoints for audio retrieval, and frontend UI for playback with base64-encoded audio streaming and cleanup.

Changes

Cohort / File(s)	Summary
Backend Audio Storage & Persistence `src-pyloid/app_controller.py`, `src-pyloid/services/database.py`	Added `_save_audio_attachment()` method to serialize WAV audio with metadata; introduced `get_history_audio()` RPC endpoint; extended `get_history()` to support `include_audio_meta` flag; database schema migration adds audio columns (`audio_relpath`, `audio_duration_ms`, `audio_size_bytes`, `audio_mime`); new `update_history_audio()` and `get_history_entry()` methods; audio file cleanup on history deletion and reset.
Settings Infrastructure `src-pyloid/services/settings.py`	Added new `save_audio_to_history: bool` field to `Settings` dataclass; updated `update_settings()` to accept and persist audio persistence flag; refactored to keyword-only parameters with `Optional[...]` types.
Server RPC Layer `src-pyloid/server.py`	Extended `get_history()` signature with `include_audio_meta` parameter; added new `get_history_audio()` RPC endpoint; wired `saveAudioToHistory` setting into `update_settings()` call.
Frontend Settings UI `src/components/SettingsTab.tsx`, `src/lib/types.ts`	Added new `saveAudioToHistory: boolean` field to Settings interface; introduced Audio History toggle card in settings with FileAudio icon and explanatory description.
Frontend API Layer `src/lib/api.ts`	Added `include_audio_meta` parameter to `getHistory()` call; introduced new `getHistoryAudio()` method returning base64-encoded audio with metadata (mime, fileName, sizeBytes, durationMs).
Frontend Audio Utilities `src/lib/audio.ts`	New module exporting audio helper functions: `INVALID_AUDIO_PAYLOAD` constant, `isInvalidAudioPayload()` error detector, `base64ToBlobUrl()` converter with error handling, `revokeUrl()` cleanup utility.
Frontend History Playback UI `src/components/HistoryPage.tsx`, `src/components/HomePage.tsx`	Added audio playback support with state management (showPlayer, audioUrl, audioMeta, loadingAudioFor); implemented `handlePlayAudio()` to fetch audio and open modal player; UI displays Audio badges on entries with audio and Play buttons for triggering playback; integrated HTML5 audio element in Dialog-based modal; includes blob URL cleanup on unmount.

Sequence Diagram(s)

sequenceDiagram
    participant User as User
    participant Frontend as Frontend (React)
    participant Server as Server (RPC)
    participant Controller as AppController
    participant DB as Database
    participant FileSystem as File System

    rect rgb(100, 150, 200)
    Note over User,FileSystem: Audio Save Flow (on successful transcription)
    User->>Frontend: Record/Paste Audio
    Frontend->>Server: transcribe()
    Server->>Controller: transcribe()
    Controller->>DB: add_history(text)
    DB->>DB: save history entry
    DB-->>Controller: history_id

    alt saveAudioToHistory enabled
        Controller->>Controller: _save_audio_attachment(audio)
        Controller->>FileSystem: write WAV file
        FileSystem-->>Controller: audio_relpath, metadata
        Controller->>DB: update_history_audio(metadata)
        DB->>DB: update audio fields
    end
    
    Controller-->>Server: success response
    Server-->>Frontend: transcription + has_audio flag
    Frontend->>Frontend: display history entry with Audio badge
    end

    rect rgb(150, 180, 100)
    Note over User,FileSystem: Audio Playback Flow
    User->>Frontend: Click Play Audio button
    Frontend->>Server: get_history_audio(history_id)
    Server->>Controller: get_history_audio(history_id)
    Controller->>DB: get_history_entry(history_id)
    DB->>DB: fetch audio metadata
    DB-->>Controller: audio_relpath, metadata
    Controller->>FileSystem: read WAV file
    FileSystem-->>Controller: audio bytes
    Controller->>Controller: encode to base64
    Controller-->>Server: base64 + mime + metadata
    Server-->>Frontend: audio payload
    Frontend->>Frontend: base64ToBlobUrl()
    Frontend->>Frontend: display modal with HTML5 player
    User->>Frontend: listen to audio
    Frontend->>Frontend: revokeUrl() on close
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Audio file persistence logic in app_controller.py and database.py: WAV serialization, metadata tracking, and path safety checks require careful verification
Database migration and schema changes: new columns and fallback handling in _ensure_history_audio_columns() need validation
State management complexity in React components: multiple audio-related state variables and cleanup effects across HomePage.tsx and HistoryPage.tsx
Base64 encoding/decoding with error handling in base64ToBlobUrl() and _save_audio_attachment()
File cleanup logic: deletion of audio files during history purge and reset operations must be robust and safe

Possibly related issues

Audio attachment persistence feature request aligns with the described opt-in "save dictation audio to History" functionality, including WAV storage, metadata tracking, get_history_audio RPC endpoint, base64 playback, and file cleanup on deletion/reset.

Poem

🎵 A rabbit hops through history's hall,
Recording voice for one and all,
With WAV files tucked in database deep,
Audio playback—memories to keep! 🎧
No setting left unchecked, no byte unplayed,
Our audio dreams are finally made! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.91% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main feature added: opt-in audio attachments for history with playback capability, with a reference to the associated issue.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 3

🧹 Nitpick comments (6)

src-pyloid/services/settings.py (1)
1-4: Unused Literal import.

The Literal type is imported but not used in this file. Consider removing it to keep imports clean.
-from typing import Literal, Optional
+from typing import Optional
src/components/HomePage.tsx (1)
74-97: Potential redundant URL revocation in error handler.

At line 78, you revoke the previous audioUrl before fetching new audio. If an error occurs, line 90 attempts to revoke audioUrl again using the closure value (which is the old URL, already revoked). This is harmless but redundant.

Consider simplifying the error handler since the cleanup effect at lines 45-47 will handle revocation when audioUrl is set to null:
     } catch (error) {
       console.error("Failed to load audio recording:", error);
       toast.error(isInvalidAudioPayload(error) ? "Audio file is corrupted" : "Audio file not found");
-      revokeUrl(audioUrl);
       setAudioUrl(null);
       setShowPlayer(false);
       setAudioMeta(null);
     } finally {
src-pyloid/services/database.py (1)
157-163: Use explicit Optional[str] for the search parameter.

Per PEP 484, using str = None implies an implicit Optional which is prohibited. This aligns with the static analysis hint.
     def get_history(
         self,
         limit: int = 100,
         offset: int = 0,
-        search: str = None,
+        search: Optional[str] = None,
         include_audio_meta: bool = False,
     ) -> list:
src-pyloid/app_controller.py (3)
257-258: Use explicit Optional[str] for the search parameter.

Same as in database.py, use explicit Optional[str] for type correctness.
-    def get_history(self, limit: int = 100, offset: int = 0, search: str = None, include_audio_meta: bool = False) -> list:
+    def get_history(self, limit: int = 100, offset: int = 0, search: Optional[str] = None, include_audio_meta: bool = False) -> list:
353-360: Use exception chaining for clarity.

When re-raising an exception inside an except block, use raise ... from None to explicitly suppress the chain or raise ... from exc to preserve it. This makes the intent clear.
         try:
             audio_path.relative_to(audio_root)
         except ValueError:
-            raise FileNotFoundError("Audio path is invalid")
+            raise FileNotFoundError("Audio path is invalid") from None
335-341: Consider adding a cache invalidation method to SettingsService.

Directly accessing self.settings_service._cache breaks encapsulation. Consider adding a public method like invalidate_cache() to SettingsService.

In settings.py:
def invalidate_cache(self) -> None:
    """Clear the settings cache."""
    self._cache = None
Then in app_controller.py:
-        self.settings_service._cache = None
+        self.settings_service.invalidate_cache()

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between aae9cb7 and 63a7f6e.

📒 Files selected for processing (10)

src-pyloid/app_controller.py (9 hunks)
src-pyloid/server.py (4 hunks)
src-pyloid/services/database.py (7 hunks)
src-pyloid/services/settings.py (3 hunks)
src/components/HistoryPage.tsx (5 hunks)
src/components/HomePage.tsx (7 hunks)
src/components/SettingsTab.tsx (4 hunks)
src/lib/api.ts (2 hunks)
src/lib/audio.ts (1 hunks)
src/lib/types.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

src/**/*.{ts,tsx}: Use pyloid-js RPC for frontend-backend communication to call Python methods exposed by the PyloidRPC server
Use @/ path alias for imports in frontend TypeScript files to reference the src/ directory
Use hash-based routing for frontend navigation between /popup, /onboarding, and /dashboard pages
Use React 18 with TypeScript for frontend development with Vite as the build tool
Define TypeScript interfaces for all data structures in lib/types.ts (Settings, HistoryEntry, Stats, Options)

Files:

src/lib/types.ts
src/lib/audio.ts
src/components/HistoryPage.tsx
src/components/HomePage.tsx
src/components/SettingsTab.tsx
src/lib/api.ts

src/components/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Use shadcn/ui (New York style) components with Tailwind CSS v4 for UI development, adding components via npx shadcn@latest add <component>

Files:

src/components/HistoryPage.tsx
src/components/HomePage.tsx
src/components/SettingsTab.tsx

src-pyloid/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

src-pyloid/**/*.py: Backend sends events to popup window via popup_window.invoke('popup-state', {...}) to notify frontend of state changes
Use singleton controller pattern: access the app controller via get_controller() for orchestrating all services
Run model loading and transcription operations in daemon background threads to avoid blocking the main thread

Files:

src-pyloid/services/database.py
src-pyloid/services/settings.py
src-pyloid/app_controller.py
src-pyloid/server.py

src-pyloid/services/database.py

📄 CodeRabbit inference engine (CLAUDE.md)

Store application data (settings and history) in SQLite database at ~/.VoiceFlow/VoiceFlow.db

Files:

src-pyloid/services/database.py

src-pyloid/server.py

📄 CodeRabbit inference engine (CLAUDE.md)

Expose Python backend methods via PyloidRPC server to be called by the frontend (get_settings, update_settings, get_history, etc.)

Files:

src-pyloid/server.py

🧠 Learnings (6)