laurence/openscribe
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
openscribe/app/README.md
Laurence 031074c9a9
Some checks failed
ci / firmware (push) Failing after 2s
Details
ci / server (push) Failing after 45s
Details
scaffold: OpenScribe open-source self-hosted AI voice recorder 
Bootstrap of the project (M0). Sets up the monorepo, design docs, hardware BOM,
the open API contract, component skeletons, licensing and CI, following the
Default Workflow SOP.

What changed:
- CLAUDE.md + docs/: copied the Default Workflow so sessions load the SOP.
- state/: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES filled in for OpenScribe.
  ARCHITECTURE captures the four-part design (firmware, server, app, case) and the
  three sync paths; DECISIONS records the hardware, AI-stack, storage, app and
  licensing choices; TODO lays out milestones M1-M9.
- hardware/BOM.md: two build options (compact XIAO ESP32-S3 Sense; dev ESP32-S3 +
  I2S mic + SD), wiring/pinout, indicative cost.
- api/openapi.yaml: the completely open API (device + server surfaces), including
  recording list/download/delete and exports (wav/ogg/txt/srt/vtt/md/json).
- firmware/: PlatformIO ESP32-S3 project, two board profiles, pin map, boot scaffold
  with module seams for M1-M4.
- server/: FastAPI skeleton mirroring the OpenAPI, config for self-hosted MinIO,
  faster-whisper and Ollama; stub routes browsable at /docs.
- app/, case/: Flutter app plan; parametric OpenSCAD enclosure.
- Licensing: GPL-3.0 (code), CERN-OHL-S-2.0 (hardware), CC-BY-SA-4.0 (case/docs),
  REUSE-style LICENSES/ with SPDX headers; LICENSING.md explains the split.
- CI: Forgejo Actions workflow builds firmware (both profiles) and lints/imports server.

Why:
- Everything self-hosted and openly licensed per the user's requirements: an open
  API, three sync paths (BLE control, WiFi transfer, independent WiFi upload on
  charge to generic cloud storage), and a full self-hosted transcription+summary stack.

Notes:
- No custom PCB in v1; off-the-shelf modules. Physical verification waits on parts.
- Component code is stubs at M0; features land milestone by milestone, each as its
  own branch/PR per the workflow.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-03 10:21:37 +01:00

1.6 KiB
Raw Blame History

OpenScribe app

Flutter mobile app (Android + iOS): provision the device, browse the library, play audio, read transcripts and summaries, export and share.

Status: planned (M7). The full Flutter project is generated when M7 starts, to avoid committing a large generated tree before there is code to run. This README is the plan.

Responsibilities

  • Provisioning (BLE): connect to the device, send WiFi credentials and the upload target, read status. BLE is used for control/provisioning only (iOS restricts background BLE), so bulk transfer goes over WiFi.
  • Device dashboard: battery, storage, recording state; start/stop; trigger a WiFi sync.
  • Library: list recordings from the server API, with sync/transcription state.
  • Playback: stream/download audio (device REST API on the LAN, or server).
  • Transcript + summary: show the faster-whisper transcript and the Ollama summary.
  • Export/share: audio, TXT, SRT, VTT, Markdown, JSON via the export endpoint.
  • Settings: server URL + API token, device management.

Planned stack

  • Flutter (Dart), state management to be chosen at M7 (likely Riverpod).
  • BLE: flutter_reactive_ble or flutter_blue_plus.
  • HTTP: dio or http, generated against ../api/openapi.yaml.
  • Audio: just_audio.

API

The app talks to two surfaces defined in ../api/openapi.yaml: the device on the LAN (provisioning/transfer) and the self-hosted server (library, transcripts, summaries, exports).

Create the project (at M7)

flutter create --org casa.discworld.openscribe --project-name openscribe_app .
flutter pub get
flutter run