Laurence
031074c9a9
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>
65 lines
3.3 KiB
Markdown
65 lines
3.3 KiB
Markdown
# Project: OpenScribe
|
|
|
|
> The anchor document. A session that reads only this, TODO.md and DECISIONS.md should
|
|
> understand what the project is and what to do next. Keep it current.
|
|
|
|
## Objective
|
|
|
|
An open-source, self-hosted AI voice recorder in the style of the Plaud Note / NotePin:
|
|
a small wearable device that records audio to local storage, syncs to a mobile app and
|
|
to a self-hosted server, and produces transcripts and summaries, with a completely open
|
|
API so the owner controls their data end to end. No proprietary cloud, no lock-in.
|
|
|
|
## Scope
|
|
|
|
- In scope:
|
|
- Firmware for an ESP32-S3 recorder (audio capture, storage, power, controls).
|
|
- Three sync paths: BLE control, WiFi bulk transfer to the app, and independent WiFi
|
|
upload to cloud storage when on charge / hard-powered (no phone present).
|
|
- A completely open, documented REST API (device and server) with an OpenAPI spec.
|
|
- A self-hosted AI stack: transcription (faster-whisper) and summarisation (local LLM
|
|
via Ollama), plus export in multiple formats.
|
|
- A Flutter mobile app (Android + iOS).
|
|
- A parametric 3D-printed case (OpenSCAD) plus a hardware BOM and wiring guide.
|
|
- Out of scope (for now):
|
|
- A custom PCB (v1 uses off-the-shelf modules on protoboard / carrier).
|
|
- Cloud SaaS hosting. Everything runs on hardware the user owns.
|
|
- Real-time on-device transcription (server does the AI; device just records + syncs).
|
|
- Speaker diarisation (deferred; noted as a later enhancement).
|
|
|
|
## Audience
|
|
|
|
Makers and privacy-minded users who want a Plaud-like capture-and-summarise workflow
|
|
they fully own: build the device from the BOM, print the case, run the server on a NAS
|
|
or mini-PC, install the app, keep every recording and transcript on their own kit.
|
|
|
|
## Description
|
|
|
|
The device records voice to microSD as WAV (compressed codecs optional later). On
|
|
battery it advertises over BLE for control and hands bulk transfers to WiFi. When placed
|
|
on charge or hard-powered it becomes autonomous: it joins configured WiFi, serves its
|
|
REST API on the LAN, and uploads new recordings to generic cloud storage (S3-compatible,
|
|
e.g. self-hosted MinIO, or WebDAV/NAS). A self-hosted server ingests recordings,
|
|
transcribes them with faster-whisper, summarises with a local LLM, and exposes an open
|
|
API with exports (audio, TXT, SRT/VTT, Markdown, JSON). The Flutter app provisions the
|
|
device, browses the library, plays audio and shows transcripts and summaries.
|
|
|
|
## Success criteria
|
|
|
|
- A person can build the device from `hardware/BOM.md`, flash `firmware/`, print
|
|
`case/`, run `server/`, install `app/`, and capture -> transcribe -> summarise -> export
|
|
a recording without any proprietary service.
|
|
- Every recording is retrievable and exportable through the open API.
|
|
- The device syncs three ways as specified (BLE, WiFi-to-app, independent WiFi upload).
|
|
- The whole stack is self-hostable and licensed for open reuse.
|
|
|
|
## Key facts
|
|
|
|
- Trunk branch: `main`
|
|
- Forge / remote: https://git.discworld.casa/laurence/openscribe
|
|
- Runtime / stack:
|
|
- Firmware: C++ (Arduino-ESP32) via PlatformIO, target ESP32-S3.
|
|
- Server: Python (FastAPI) + faster-whisper + Ollama + object storage (MinIO/local).
|
|
- App: Flutter (Dart), Android + iOS.
|
|
- Case: OpenSCAD. CI: Forgejo Actions (self-hosted runner).
|
|
- How to run it: see `state/NOTES.md` (per-component build/run commands).
|