tscherrie/vmcast

Pro voice messenger for long-form, end-to-end encrypted voice messages with audiobook/podcast-grade playback and on-device AI (transcription, summaries, table of contents).

See SPECS.md for the full product and technical specifications.

• M1 — Local core (in progress)
  • DONE: Flutter app scaffold; routing; Contacts/VM List/VM Detail/Record/Settings screens
  • DONE: Basic recording service (AAC mono 16 kHz), permissions; basic playback service
  • NEXT: Local storage of recordings and simple in-app listing
• M2 — Transport + E2EE
  • Decentralized relays (store-and-forward), resumable media upload/download
  • libsignal (X3DH + Double Ratchet), encrypted receipts, push wake-ups
• M3 — On-device AI
  • Model manager; post-recording transcription (Whisper.cpp), FTS search
  • Summaries + LLM-first table of contents (Llama.cpp/MLC)
• M4 — UX polish
  • Mini-player, continuous play, iOS glass accents, Android dynamic color, accessibility
• M5 — Hardening
  • Storage warnings, relay redundancy, perf/thermal tuning, optional key export/import

This repository uses Flutter for a shared codebase targeting Android and iOS. For day-to-day development:

• macOS: primary for iOS builds and Android emulation
• Windows: primary for Android builds; iOS testing via TestFlight/App Distribution (once CI is set up)

• Git
• Flutter SDK (stable channel)
• Dart (bundled with Flutter)

macOS (Homebrew):

brew install --cask flutter
flutter doctor

Windows:

1. Download Flutter for Windows (stable) and add flutter\bin to PATH.
2. In PowerShell:

flutter doctor

Prerequisites:

• macOS 13+
• Xcode (latest stable)
• CocoaPods
• Android Studio (optional, for Android emulator)

Steps:

1. Install Xcode from App Store, then run:

xcode-select --install || true
sudo xcodebuild -runFirstLaunch

2. Accept licenses by opening Xcode once and launching a Simulator.
3. Install CocoaPods:

sudo gem install cocoapods || brew install cocoapods

4. Install Android tooling (optional):

brew install --cask android-studio

5. Clone and bootstrap:

git clone https://github.com/your-org/vmcast.git
cd vmcast
flutter pub get
flutter doctor -v

6. Run on iOS Simulator:

open -a Simulator
flutter devices
flutter run -d ios

7. Build iOS (for release later):

flutter build ios --release

Prerequisites:

• Windows 10/11
• Android Studio (SDK, Platform-Tools, Emulator)
• Java JDK 17 (installed via Android Studio or separately)

Steps:

1. Install Android Studio and components (SDK Platforms, SDK Tools, AVD).
2. Ensure environment variables (if needed): ANDROID_HOME and add platform-tools to PATH.
3. Clone and bootstrap:

git clone https://github.com/your-org/vmcast.git
cd vmcast
flutter pub get
flutter doctor -v

4. Create and launch an Android emulator, or connect a device with USB debugging.
5. Run on Android:

flutter run -d emulator-5554

6. Build Android APK/AAB:

flutter build apk --release
flutter build appbundle --release

• ASR (transcription): use Whisper.cpp models (e.g., tiny/base/small). Download from the official sources and place them under assets/models/whisper/. See whisper.cpp releases.
• LLM (summary/ToC): use a small quantized model (e.g., 3–7B Q4). Place under assets/models/llm/. See llama.cpp or MLC LLM.
• The app will provide a model manager UI to download/verify models in-app (planned in M3).

Directory convention (planned):

assets/
  models/
    whisper/
      ggml-base.bin
    llm/
      model-q4_k_m.gguf

• The app ships with a hardcoded bootstrap list of public relays for easy onboarding (configurable later in Settings).
• Developers can override via an environment file (planned):

.env
RELAYS_DEFAULT=wss://relay1.example.org,wss://relay2.example.org

• Unit tests: flutter test
• Integration tests: flutter test integration_test
• Golden tests and E2E: will be added alongside implementation milestones

iOS Simulator (focus first):

open -a Simulator
flutter run -d ios

macOS desktop (optional):

flutter run -d macos

Android Emulator

flutter devices
flutter run -d <your-android-device-id>

Recording note:

• On first record attempt, the app will prompt for microphone permission.
• Saved recording paths are shown on the Record screen (temporary stub). Local storage listing will be added next.

• If flutter doctor shows iOS toolchain issues, ensure Xcode Command Line Tools are selected in Preferences → Locations.
• For CocoaPods issues: run pod repo update inside the ios directory after flutter clean.
• On Windows, ensure Hyper-V/WSL is configured correctly if using certain emulator images.

• Please read SPECS.md before starting work. Align contributions with the current milestone.
• Use conventional commits and open small, focused PRs.

TBD