EchoScript Documentation
Introduction
EchoScript is an offline-first mobile application engineered for continuous, high-fidelity background audio capture and automated AI transcription. Built for meetings, lectures, and field interviews, EchoScript records speech in continuous time-sliced audio chunks, writes to local persistent storage, and transcribes recordings asynchronously using the Google Gemini API.
The core design philosophy is zero data loss, high battery efficiency, and local hardware independence. The application functions uninterrupted whether the screen is locked, the app is backgrounded, or internet connectivity is temporarily unavailable.
System Architecture
EchoScript implements a clean domain-driven architecture with reactive state management powered by Flutter Riverpod and code generation.
Processing Flow
- Audio Acquisition: Background isolate captures 16kHz mono PCM stream with software gain adjustment.
- Atomic Chunk Rotation: At scheduled intervals (15, 30, or 60 minutes), the active audio file is rotated and sealed with a valid 44-byte WAV header in under 50ms without dropping audio frames.
- Local Persistence: Audio metadata is committed to the embedded Isar database with state
PENDING. - Remote Processing: Background worker uploads audio chunks to the Gemini Files API, triggers transcription using Gemini 1.5 Flash or Pro, and receives verbatim text.
- Atomic Cleanup: Remote files on Gemini servers are deleted immediately after completion, and local audio files are removed once the transcription is safely written to the local database.
Technology Stack
| Component | Technology | Role |
|---|---|---|
| UI & Framework | Flutter 3.x / Dart | Cross-platform interface and business logic |
| State Management | flutter_riverpod / riverpod_generator | Reactive UI state and dependency injection |
| Local Database | Isar NoSQL Engine | Offline storage for transcripts, chunks, and settings |
| Background Services | flutter_background_service | Persistent background execution isolate |
| Hardware Wakelock | wakelock_plus | CPU execution guarantee during device sleep |
| Audio Session | audio_session / flutter_sound | Low-latency PCM audio stream capture |
| AI Engine | google_generative_ai / Gemini API | Multilingual speech-to-text generation |
| Key Storage | flutter_secure_storage | Hardware-backed key encryption |
| Document Export | pdf / share_plus | PDF and plaintext file generation and sharing |
Audio Pipeline & Chunks
The audio pipeline operates at 16,000 Hz, 16-bit linear PCM, single channel (mono). This standard matches Gemini speech processing requirements while optimizing file size and upload speed.
Software Gain Multiplication
Audio samples arriving through the microphone stream are transformed sample-by-sample via little-endian 16-bit integer scaling with hard clamping to avoid digital clipping:
Uint8List applyGain(Uint8List rawBytes, double gain) {
if (gain == 1.0) return rawBytes;
final data = ByteData.sublistView(rawBytes);
final length = rawBytes.length ~/ 2;
final output = Uint8List(rawBytes.length);
final outputData = ByteData.sublistView(output);
for (int i = 0; i < length; i++) {
final sample = data.getInt16(i * 2, Endian.little);
double adjusted = sample * gain;
if (adjusted > 32767) adjusted = 32767;
if (adjusted < -32768) adjusted = -32768;
outputData.setInt16(i * 2, adjusted.toInt(), Endian.little);
}
return output;
}
WAV Header Finalization
When an audio chunk is initialized, a 44-byte placeholder is reserved. Upon rotation or session completion, a canonical RIFF/WAVE header is written in-place using FileMode.append with offset seeking to 0, ensuring the audio sample payload is never truncated.
Background Resilience
Mobile operating systems aggressively terminate idle background processes. EchoScript implements a multi-layer resilience strategy:
- Foreground Service Notification: Runs as a high-priority Android foreground service with real-time status updates showing duration and queue state.
- Partial CPU Wakelock: Acquires a partial wakelock via
wakelock_plusduring recording to keep the CPU awake even when the screen is powered off. - Audio Session Configuration: Requests spoken audio mode with Bluetooth input support and default routing.
- iOS Background Modes: Configured with
audioandfetchbackground execution keys inInfo.plist. - Low Disk Guard: Continuously checks available storage space every 10 seconds. If free disk space drops below 500 MB, recording is safely paused to prevent system storage exhaustion.
AI Transcription Engine
EchoScript integrates with the Google Gemini API using the Gemini Files upload endpoint.
Model Options
- Gemini 1.5 Flash (Default): Fast, lightweight, and highly cost-effective for everyday meetings and conversations.
- Gemini 1.5 Pro: Advanced reasoning model offering higher precision on complex technical jargon, heavy accents, and multi-speaker separation.
Error Handling & Backoff Strategy
Transcription requests classify errors into fatal and transient categories:
- Fatal Errors: Invalid API keys, missing files, or authentication failures (HTTP 400, 401, 403) fail immediately without blocking the processing queue.
- Transient Errors: Network drops, rate limits (HTTP 429), and gateway timeouts trigger adaptive exponential backoff (5s, 10s, 20s, 40s, 60s) up to 5 attempts before marking the chunk as failed.
Isar Database Schema
EchoScript uses Isar NoSQL for fast, indexed, zero-overhead storage. Two collections govern data storage:
AudioChunk Schema
| Field | Type | Indexing | Description |
|---|---|---|---|
id |
Id | Auto-increment | Unique chunk identifier |
filePath |
String | Unique Index | Absolute path to temporary recording file |
status |
String | Indexed | State: PENDING, PROCESSING, DONE, FAILED |
transcript |
String? | None | Generated transcript text |
createdAt |
DateTime | Indexed | Session start timestamp |
durationSeconds |
int | None | Chunk recording length in seconds |
wordCount |
int | None | Total word count computed from transcript |
retryCount |
int | None | Failed transcription attempt counter |
AppSettings Schema
| Field | Type | Default | Description |
|---|---|---|---|
id |
Id | 0 | Singleton record identifier |
gainMultiplier |
double | 1.0 | Software microphone gain multiplier (0.25x to 16.0x) |
chunkIntervalMinutes |
int | 30 | Audio chunk duration limit (1, 15, 30, 60 min) |
systemPrompt |
String | Verbatim prompt | System instructions supplied to Gemini model |
selectedModel |
String | gemini-1.5-flash | Selected Gemini model identifier |
isFirstLaunch |
bool | true | First-run onboarding flag |
Security & Privacy
EchoScript is architected to protect user audio data and API credentials:
- Hardware Keystore Encryption: API keys are stored in encrypted form using Android KeyStore (via
EncryptedSharedPreferences) and iOS Keychain. - Ephemeral Remote Storage: Remote audio files uploaded to Google servers via the Files API are explicitly deleted immediately after the transcription payload is received.
- 24-Hour Privacy Purge: An automated routine cleans up local recording files on disk that are older than 24 hours, ensuring audio does not persist indefinitely on the device.
Export System
Transcripts can be shared in two standardized formats:
- Formatted Plaintext (.txt): Includes timestamp header, duration, word count metadata, and complete transcript text.
- Structured PDF Report (.pdf): Multi-page styled document generated on-device with header blocks, metadata indicators, and automatic pagination.
The PDF export engine automatically sanitizes smart quotes, em-dashes, en-dashes, bullets, and ellipses into Latin-1 compatible glyphs before document compilation, preventing font layout crashes.
Error & Crash Recovery
Real-world mobile applications encounter sudden kills, battery exhaustion, and system restarts. EchoScript handles these situations through automated recovery routines:
- Orphaned Chunk Recovery: On startup, the background service calls
recoverOrphanedProcessingChunks()to scan for any chunks left inPROCESSINGstate and reverts them toPENDINGfor immediate re-queueing. - Safe File Rotation: Atomic file swaps ensure that if an audio write fails, the previous chunk remains intact on disk.
- Atomic Local Cleanup: Local audio files are only deleted after the database write transaction has succeeded.
Setup & Build Guide
Prerequisites
- Flutter SDK 3.x and Dart SDK
- Android Studio / Xcode with platform SDKs installed
- Google Gemini API Key from Google AI Studio
Installation
# 1. Clone repository
git clone https://github.com/zihaaaad/EchoScript.git
cd EchoScript
# 2. Install dependencies
flutter pub get
# 3. Run code generation (Isar & Riverpod)
dart run build_runner build --delete-conflicting-outputs
# 4. Launch application
flutter run
Testing Strategy
EchoScript includes automated unit test suites covering domain models, file I/O safety, text export sanitization, and diagnostic metrics:
# Run all test suites
flutter test
# Run static analysis
flutter analyze
| Test Suite | Path | Verification Scope |
|---|---|---|
| WAV Header Safety | test/wav_header_test.dart |
Validates header generation and non-truncating file updates |
| Export Sanitization | test/export_service_test.dart |
Validates unicode-to-Latin1 conversion and line ending normalization |
| Settings Domain | test/app_settings_test.dart |
Validates default configuration and model constants |
| Audio Chunk Lifecycle | test/audio_chunk_test.dart |
Validates status transitions and word count calculation |
| Diagnostic Metrics | test/diagnostic_metrics_test.dart |
Validates success rate, average duration, and metric calculations |