EchoScript Documentation

High-fidelity background audio recording application and concurrent AI transcription engine.

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

  1. Audio Acquisition: Background isolate captures 16kHz mono PCM stream with software gain adjustment.
  2. 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.
  3. Local Persistence: Audio metadata is committed to the embedded Isar database with state PENDING.
  4. 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.
  5. 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:

AI Transcription Engine

EchoScript integrates with the Google Gemini API using the Gemini Files upload endpoint.

Model Options

Error Handling & Backoff Strategy

Transcription requests classify errors into fatal and transient categories:

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:

Export System

Transcripts can be shared in two standardized formats:

Unicode Typography Sanitization:

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:

Setup & Build Guide

Prerequisites

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