{
  "markdown": "# open-plaud\n\nAn open reference stack for a Plaud-like recorder: DIY ESP32-S3 hardware, firmware that records and syncs WAV files, and a self-hosted transcription/summarization server you control.\n\nNo per-minute limits. No forced cloud lock-in. No subscription. You own the recordings and the pipeline.\n\n> This project is independent and is not affiliated with, endorsed by, or\n> sponsored by Plaud. See `docs/PRIOR_ART.md` for naming and positioning notes.\n\n## Why\n\nCommercial AI recorders ship cheap hardware and monetize a cloud subscription that caps your transcription minutes and processes your private audio on someone else's servers. `open-plaud` inverts that: the value lives in an open pipeline you run yourself.\n\n| | Plaud (commercial) | open-plaud |\n|---|---|---|\n| Hardware | Closed, ~$159+ | Open, ~₩40–70k DIY |\n| Transcription | Cloud-only, minute-capped | Pluggable: cloud (OpenAI) or local (whisper.cpp) |\n| Summarization | Their templates | Claude or local Ollama |\n| Recordings | Their cloud | Your storage |\n| Cost model | Subscription | Pay-per-use or free (local) |\n\n## Repository layout\n\n```\nopen-plaud/\n├── firmware/      ESP32-S3 firmware (ESP-IDF) — record, sync over Wi-Fi\n├── hardware/      BOM, 3D-print case files, pilot PCB notes\n├── mobile/        iOS on-device transcription package\n├── okf/           Open Knowledge Format bundle for agent-readable project context\n├── server/        Python pipeline: ingest → transcribe → diarize → summarize\n├── docs/          Architecture, roadmap, hardware decisions, prior art, research\n└── .github/       CI for server checks\n```\n\n## Status\n\nThe server loop works end to end: upload → transcribe → summarize → browse.\nCloud transcription (OpenAI Whisper), local desktop transcription\n(`whisper_cpp`), on-device iOS transcription, cloud summarization (Claude),\nlocal summarization (Ollama), and optional `pyannote` / `whisperx` diarization\nare implemented behind small provider contracts; recordings persist in SQLite\nand survive restarts; a small web UI lists, plays, and exports them. The default\nserver providers are `none` (no key required) so the server runs offline out of\nthe box. See `docs/ARCHITECTURE.md` and `docs/ROADMAP.md`.\n\nRelated-project research and positioning notes live in `docs/PRIOR_ART.md` and\n`docs/POSITIONING.md`.\n\nAgent-readable project knowledge is available as an Open Knowledge Format v0.1\nbundle in `okf/`. It catalogs the system, components, API, provider contracts,\ndata model, and operating workflows with cross-links back to the source docs and\ncode.\n\nCurrent v0 hardware target: **Waveshare ESP32-S3-LCD-1.54 + battery**. It keeps\nthe important recorder pieces under $30: dual mic + ES7210 ADC, battery\ncharging, TF/microSD, Wi-Fi, and a small status LCD.\n\nFirst-board validation is tracked in `docs/BRINGUP.md`. Do not treat the\nhardware reference as public-alpha complete until the bring-up checklist has\nreal serial logs, WAV samples, upload responses, and case-fit evidence.\n\n![Plaud Note vs Waveshare ESP32-S3-LCD-1.54 size comparison](docs/assets/plaud-vs-waveshare-lcd154.png)\n\nPlaud is much thinner and more finished; the Waveshare board is cheaper,\nopen-firmware friendly, and already includes the pieces needed for a working v0\nrecorder prototype.\n\n![open-plaud firmware state transition diagram](docs/assets/open-plaud-state-transition-diagram.png)\n\nThe firmware LCD states and button transitions are documented in\n[`docs/state-transition-diagram.html`](docs/state-transition-diagram.html).\n\n## Quick start (server)\n\nThis project is **uv-managed**. Install [uv](https://docs.astral.sh/uv/), then:\n\n```bash\ncd server\nuv sync                                        # create .venv + install from uv.lock\ncp .env.example .env                           # add your transcription + LLM API keys\nuv run uvicorn open_plaud.api.app:app --reload\n```\n\nThen open **http://127.0.0.1:8000/** for the web UI (list, play, transcript,\nsummary, Markdown export), or use the device upload target directly:\n\n```bash\ncurl -F \"file=@rec_0001.wav;type=audio/wav\" http://127.0.0.1:8000/v1/recordings\n# -> {\"id\":\"...\",\"status\":\"received\",\"filename\":\"rec_0001.wav\",\"size_bytes\":...}\n# the pipeline runs in the background; poll GET /v1/recordings/{id} for the result\n```\n\nBy default the pipeline is a no-op (stores audio, empty transcript) so it runs\nwith no API keys. To actually transcribe + summarize, set the keys in `.env` and\nselect the cloud providers:\n\n```bash\nOP_PIPELINE__TRANSCRIPTION=openai_whisper   # needs OPENAI_API_KEY\nOP_PIPELINE__SUMMARIZATION=claude           # needs ANTHROPIC_API_KEY\n```\n\nLocal desktop transcription uses an installed whisper.cpp CLI and model:\n\n```bash\nOP_PIPELINE__TRANSCRIPTION=whisper_cpp\nOP_WHISPER_CPP_MODEL=/path/to/ggml-model.bin\n# OP_WHISPER_CPP_BIN=whisper-cli            # override if your binary name differs\n```\n\nLocal summarization uses a running Ollama server:\n\n```bash\nOP_PIPELINE__SUMMARIZATION=ollama\nOP_OLLAMA_MODEL=qwen2.5:7b                  # or any model installed in Ollama\n```\n\nSee `server/.env.example` for the `whisper_cpp`, Ollama, and diarization\nsettings.\n\n`uv` reads the pinned interpreter from `.python-version` (installing it if missing).\nDev tools (pytest, ruff, mypy) come with `uv sync` — run them via `uv run pytest`,\n`uv run ruff check .`, `uv run mypy .`.\n\n## License\n\nMIT. See `LICENSE`.\n",
  "bytes": 5360,
  "sha": "63ffe26350161ed8cf14245e380f92e341c40afb4125b1568dbef1a4da9ba08b",
  "repo_slug": "guzus/open-plaud",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_guzus_open_plaud_okf_index_md_013d38e1/readme"
}