# OpenScribe

An open-source, self-hosted AI voice recorder in the style of the Plaud Note / NotePin.
A small wearable device records audio to local storage, syncs to a mobile app and to a
server you run, and produces transcripts and summaries, through a completely open API.
No proprietary cloud, no lock-in.

> Status: **early scaffold (M0)**. The design, hardware BOM, and open API are defined;
> component code is being built milestone by milestone. See `state/TODO.md`.

## Why

Commercial AI recorders send your conversations to a vendor's cloud. OpenScribe keeps the
whole pipeline (capture, storage, transcription, summarisation, export) on hardware you
own, under open licences, with an API documented so you can build against it.

## What it does

- Records voice to microSD on a small ESP32-S3 device (button start/stop, LED status).
- Syncs three ways:
  1. **BLE** for control, status and WiFi provisioning.
  2. **WiFi** to the mobile app for fast bulk transfer.
  3. **Independent WiFi upload** to your storage when on charge / hard-powered, with no
     phone present.
- Transcribes (faster-whisper) and summarises (local LLM via Ollama) on a server you host.
- Exposes a **completely open REST API** with exports: audio, TXT, SRT, VTT, Markdown, JSON.
- Ships a **Flutter** app (Android + iOS) and a **3D-printed** parametric case.

## Architecture at a glance

```
mic -> ESP32-S3 (record to microSD)
         |  BLE: control / provision
         |  WiFi REST API: transfer to app
         |  WiFi uploader (on charge) -> object storage (MinIO / WebDAV / NAS)
                                              |
                                    self-hosted server (FastAPI)
                                    faster-whisper -> Ollama -> open API + exports
                                              |
                              Flutter app (Android + iOS)
```

Full detail: [`state/ARCHITECTURE.md`](state/ARCHITECTURE.md). The API contract:
[`api/openapi.yaml`](api/openapi.yaml).

## Repository layout

```
firmware/   ESP32-S3 recorder firmware (PlatformIO, Arduino-ESP32)
server/     Self-hosted FastAPI server: ingest, transcribe, summarise, serve API
app/        Flutter mobile app (Android + iOS)
hardware/   BOM, wiring/pinout, build notes (off-the-shelf modules, no PCB in v1)
case/       Parametric 3D-printed enclosure (OpenSCAD)
api/        openapi.yaml - the single source of truth for the open API
docs/       Workflow docs (this project follows the Default Workflow SOP)
state/      Project memory: PROJECT, ARCHITECTURE, DECISIONS, TODO, NOTES
LICENSES/   Full licence texts
```

## Hardware

You build the device from off-the-shelf parts. See [`hardware/BOM.md`](hardware/BOM.md)
for the shopping list, wiring and pinout. Core: an ESP32-S3 board with PSRAM, an I2S MEMS
microphone, a microSD card, a LiPo battery and a charge IC.

## Self-hosted stack

Everything runs on hardware you own: Forgejo for the forge, faster-whisper for
transcription, Ollama for summaries, MinIO (or WebDAV / NAS) for storage. Plain recording
and transfer work without any server; the server adds transcription and summaries.

## Getting started

Nothing to run end to end yet (M0 scaffold). To follow along:

- Read [`state/PROJECT.md`](state/PROJECT.md) and [`state/TODO.md`](state/TODO.md).
- Per-component build/run commands are in [`state/NOTES.md`](state/NOTES.md) and each
  component's `README.md`.

## Licensing

Multi-part, copyleft. Code is GPL-3.0-only, hardware is CERN-OHL-S-2.0, case and docs are
CC-BY-SA-4.0. See [`LICENSING.md`](LICENSING.md).

OpenScribe is an independent open-source project inspired by the Plaud class of device. It
is not affiliated with or endorsed by Plaud.