🎙️ OpenPlaud

Self-hosted AI transcription interface for Plaud Note devices

Replace Plaud's $20/month AI subscription with your own OpenAI-compatible API keys

Quick Start • Features • Configuration • Contributing • License

---

✨ Features

🔐 Privacy & Control

• Self-Hosted - Complete control over your data and API keys
• Encrypted Credentials - AES-256-GCM encryption for all sensitive data
• No Vendor Lock-in - Your recordings, your infrastructure

🤖 AI & Transcription

• Universal AI Support - Works with ANY OpenAI-compatible API:
  • OpenAI, Groq, Together AI, OpenRouter
  • Local models: LM Studio, Ollama
  • And any other OpenAI-compatible endpoint
• Browser Transcription - Client-side transcription using Transformers.js (zero API costs!)
• AI Title Generation - Automatically generate descriptive titles from transcriptions
• Multiple AI Providers - Configure and switch between different providers

💾 Storage & Sync

• Flexible Storage - Local filesystem OR S3-compatible storage:
  • AWS S3, Cloudflare R2, MinIO
  • DigitalOcean Spaces, Wasabi, Backblaze B2
• Auto-Sync - Automatically download recordings from Plaud devices
• Configurable Intervals - Set your own sync schedule

📤 Export & Notifications

• Multiple Export Formats - JSON, TXT, SRT, VTT subtitle formats
• Full Backups - Export all your data with one click
• Browser Notifications - Real-time alerts for new recordings
• Email Notifications - SMTP support for email alerts

🚀 Deployment & UX

• Zero-Config Deployment - Up and running with one Docker Compose command
• Guided Onboarding - Interactive setup wizard for new users
• Modern UI - Clean, hardware-inspired design with dark theme support
• Comprehensive Error Handling - Graceful failures with helpful error messages

🚀 Quick Start

Prerequisites

• 🐳 Docker & Docker Compose
• 🎙️ Plaud Note device with account at plaud.ai
• 🤖 OpenAI API key (or any OpenAI-compatible provider)

Installation

OpenPlaud ships as a Docker image on GitHub Container Registry. You don't need to clone the repo to self-host — just grab the compose file and env template from the latest release.

1. Create a directory and download the install files

mkdir openplaud && cd openplaud

curl -fLO https://github.com/openplaud/openplaud/releases/latest/download/docker-compose.yml
curl -fL  https://github.com/openplaud/openplaud/releases/latest/download/.env.example -o .env

2. Generate secrets and edit .env

# Print two fresh secrets — paste them into .env
echo "BETTER_AUTH_SECRET=$(openssl rand -hex 32)"
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"

Open .env and set at minimum:

BETTER_AUTH_SECRET=<paste>
ENCRYPTION_KEY=<paste>
APP_URL=http://localhost:3000

# Optional — pin a specific OpenPlaud version for reproducible deploys.
# Leave as `latest` for newest stable, or use e.g. `0.1.0` / `dev`.
OPENPLAUD_VERSION=latest

3. Start the application

docker compose up -d

4. Access OpenPlaud

Open http://localhost:3000 and create your account. The onboarding wizard will guide you through connecting your Plaud device, configuring AI providers, storage, and sync preferences.

Upgrading

docker compose pull && docker compose up -d

Database migrations run automatically on container start. To pin a version (recommended for production), set OPENPLAUD_VERSION=0.1.0 in .env. To roll back, set it to the previous tag and re-run the command above.

Image tags

Tag	What you get	Use when
latest	Newest stable release	Default — most users
0.1.0, 0.1	Specific version / minor line	Production — pin for reproducibility
dev	Rolling build from main	You want bleeding edge, accept breakage

⚠️ main is a rolling integration branch. Do not deploy by cloning and building from main — use the image tags above. See BRANCHING.md for details.

📖 Configuration Guide

🔑 Connecting Your Plaud Account

OpenPlaud signs into Plaud directly using your email — the same way the official Plaud app does:

1. Enter the email address you use on plaud.ai
2. Plaud sends you a verification code
3. Enter the code in OpenPlaud — that's it

Your verification code is forwarded directly to Plaud's servers and never stored by OpenPlaud. Your Plaud email is stored alongside the connection so you can see which account is linked and switch accounts later — it lives only on your self-hosted instance. After login, the access token is encrypted (AES-256-GCM) and stored the same way. Your account region (Global, EU, Asia Pacific) is detected automatically.

🔓 Open Source: Every line that handles your credentials is available for inspection — send-code route · verify route · encryption

💾 Storage Options

📁 Local Filesystem (Default)

Recordings are stored in Docker volume /app/audio. No additional configuration needed.

Pros: Zero setup, works out of the box
Cons: Limited to host machine storage

☁️ S3-Compatible Storage

OpenPlaud supports ANY S3-compatible service. Configure through the settings UI or via environment variables.

🗄️ AWS S3

Endpoint: (leave blank)
Bucket: your-bucket-name
Region: us-east-1
Access Key ID: YOUR_KEY
Secret Access Key: YOUR_SECRET

🌐 Cloudflare R2

Endpoint: https://<account-id>.r2.cloudflarestorage.com
Bucket: openplaud
Region: auto
Access Key ID: YOUR_KEY
Secret Access Key: YOUR_SECRET

Note: R2 offers 10GB free storage with no egress fees!

🐳 MinIO (Self-hosted)

Endpoint: http://minio:9000
Bucket: openplaud
Region: us-east-1
Access Key ID: minioadmin
Secret Access Key: minioadmin

Perfect for self-hosted deployments!

🌊 DigitalOcean Spaces

Endpoint: https://<region>.digitaloceanspaces.com
Bucket: your-space-name
Region: <region>
Access Key ID: YOUR_KEY
Secret Access Key: YOUR_SECRET

💧 Backblaze B2

Endpoint: https://s3.<region>.backblazeb2.com
Bucket: your-bucket-name
Region: <region>
Access Key ID: YOUR_KEY
Secret Access Key: YOUR_SECRET

Excellent pricing for long-term storage!

🤖 AI Provider Setup

OpenPlaud uses the OpenAI SDK with custom baseURL support, making it compatible with any OpenAI-compatible API.

💡 Configure multiple providers and switch between them based on your needs!

OpenAI (Official)

• Base URL: (leave blank)
• API Key: Your OpenAI key
• Models: whisper-1, gpt-4o, gpt-4-turbo, gpt-3.5-turbo

Best for: Production quality, latest models

🚀 Groq (Free Whisper API!)

• Base URL: https://api.groq.com/openai/v1
• API Key: Your Groq key
• Models: whisper-large-v3, llama-3.1-70b-versatile

Best for: Free transcription, ultra-fast inference

Together AI

• Base URL: https://api.together.xyz/v1
• API Key: Your Together AI key
• Models: whisper-large-v3, meta-llama/Llama-3-70b-chat-hf

Best for: Cost-effective, diverse model selection

OpenRouter (Access to Claude, GPT-4, Llama)

• Base URL: https://openrouter.ai/api/v1
• API Key: Your OpenRouter key
• Models: anthropic/claude-3.5-sonnet, openai/gpt-4-turbo, meta-llama/llama-3-70b-instruct

Best for: Access to multiple providers through one API

🏠 LM Studio (Local Models)

• Base URL: http://localhost:1234/v1
• API Key: lm-studio (or any string)
• Models: Name of your loaded model

Best for: 100% private, offline transcription

🦙 Ollama (Local Models)

• Base URL: http://localhost:11434/v1
• API Key: ollama (or any string)
• Models: whisper, llama3, mistral, etc.

Best for: Easy local model management

📚 Azure OpenAI

• Base URL: https://<resource>.openai.azure.com/openai/deployments/<deployment>
• API Key: Your Azure OpenAI key
• Models: Your deployment name

Best for: Enterprise compliance, Azure integration

🌐 Browser-Based Transcription (Free!)

OpenPlaud supports client-side transcription using Transformers.js, running Whisper models directly in your browser:

Feature	Description
💰 Zero API Costs	Runs entirely in the browser
🔒 Privacy-First	Audio never leaves your device
🤖 Models Available	whisper-tiny, whisper-base, whisper-small
🎯 Auto-Detected	Automatically available in transcription UI

⚠️ Note: Browser transcription is slower than server-side but completely free and private. Perfect for sensitive recordings!

🏗️ Architecture

Tech Stack

Frontend Next.js 16 (App Router) TypeScript Tailwind CSS Framer Motion Wavesurfer.js (audio visualization) Backend PostgreSQL Drizzle ORM Better Auth

AI & Transcription OpenAI SDK (universal compatibility) Transformers.js (browser transcription) Storage Local filesystem S3-compatible (AWS, R2, MinIO, etc.) Deployment Docker & Docker Compose Single-container architecture

Database Schema

Table	Purpose
users & sessions	Authentication (Better Auth)
plaud_connections	Encrypted Plaud bearer tokens
plaud_devices	Connected Plaud devices
recordings	Recording metadata + storage paths
transcriptions	AI-generated transcriptions
ai_enhancements	Summaries, action items, key points
api_credentials	Encrypted AI API keys (multiple providers)
storage_config	User storage preferences (local/S3)
user_settings	Sync, notifications, playback, export preferences

🔒 Security

• 🔐 AES-256-GCM encryption for all sensitive data (API keys, tokens)
• 🛡️ Better Auth for secure session management
• 🗄️ PostgreSQL for reliable data persistence
• 🐳 Docker isolation for secure deployment
• 🚫 No telemetry - Your data stays yours

🎨 Design Philosophy

OpenPlaud features a hardware-inspired design that brings the tactile feel of audio equipment to the web:

Component	Description
🎛️ Rotary Knobs	Draggable 360° rotation with LED ring indicators
💡 LED Indicators	Animated glow effects for status feedback
🎚️ Hardware Rack Modules	Authentic audio equipment aesthetic with mounting holes
📊 Waveform Display	Real-time audio visualization (Wavesurfer.js)
🌙 Dark Theme	Easy on the eyes for long listening sessions
🧭 Guided Onboarding	Interactive setup wizard for new users

💡 The UI is inspired by professional audio workstations, combining functionality with aesthetics.

🔧 Development

See CONTRIBUTING.md for local setup, code standards, and the PR workflow. See BRANCHING.md for the branching and release model.

Database Management

Command	Description
pnpm db:generate	Generate new migration from schema changes
bun db:migrate	Apply migrations to database
pnpm db:studio	Open Drizzle Studio (visual database browser)

Testing

Unit Tests

# Run all tests
bun test

# Run specific test file
bun test src/tests/plaud.test.ts

Integration Tests

Live Plaud API tests are opt-in to avoid credential leaks and rate limits:

export PLAUD_BEARER_TOKEN="Bearer eyJhbGciOi..."
bun test src/tests/plaud.integration.test.ts

💡 Integration tests run against the real Plaud API. Leave PLAUD_BEARER_TOKEN unset in CI to skip them.

Project Structure

src/
├── app/              # Next.js App Router pages
│   ├── (app)/       # Authenticated routes
│   ├── (auth)/      # Authentication pages
│   └── api/         # API routes
├── components/       # React components
│   ├── ui/          # shadcn/ui components
│   └── dashboard/   # Feature components
├── lib/             # Core business logic
│   ├── ai/          # AI integration
│   ├── plaud/       # Plaud API client
│   ├── storage/     # Storage abstraction
│   └── transcription/ # Transcription logic
├── db/              # Database schema & migrations
└── types/           # TypeScript type definitions

📊 API Reference

🔐 Authentication

Method	Endpoint	Description
POST	/api/auth/sign-up	Create account
POST	/api/auth/sign-in	Login
POST	/api/auth/sign-out	Logout

🎙️ Plaud Integration

Method	Endpoint	Description
POST	/api/plaud/auth/send-code	Send OTP verification code to Plaud email
POST	/api/plaud/auth/verify	Verify OTP and store encrypted connection
GET	/api/plaud/connection	Check connection status
DELETE	/api/plaud/connection	Disconnect Plaud account (preserves recordings)
POST	/api/plaud/sync	Manual sync recordings

🎵 Recordings

Method	Endpoint	Description
GET	/api/recordings	List all recordings
GET	/api/recordings/[id]	Get recording details
GET	/api/recordings/[id]/audio	Stream audio file
POST	/api/recordings/[id]/transcribe	Transcribe recording

⚙️ Settings

Method	Endpoint	Description
GET	/api/settings/user	Get user settings
PUT	/api/settings/user	Update user settings
PUT	/api/settings/storage	Configure storage
GET	/api/settings/ai/providers	List AI providers
POST	/api/settings/ai/providers	Add AI provider
PUT	/api/settings/ai/providers/[id]	Update AI provider
DELETE	/api/settings/ai/providers/[id]	Delete AI provider

📤 Export & Backup

Method	Endpoint	Description
GET	/api/export?format=json|txt|srt|vtt	Export recordings
POST	/api/backup	Create backup of all user data

🏥 Health

Method	Endpoint	Description
GET	/api/health	Health check endpoint

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Ways to Contribute

• 🐛 Report bugs - Found an issue? Open a bug report
• 💡 Request features - Have an idea? Create a feature request
• 📝 Improve docs - Documentation PRs are always welcome
• 🔧 Submit PRs - See CONTRIBUTING.md for guidelines
• ⭐ Star the repo - Show your support!

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following our code standards
4. Test your changes (bun test)
5. Commit with Gitflow conventions (git commit -m 'feat: add amazing feature')
6. Push to your fork (git push origin feature/amazing-feature)
7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📝 License

AGPL-3.0 License – see LICENSE file for details

This means:

• ✅ Free to use, modify, and distribute
• ✅ Can use for commercial purposes
• ⚠️ Must open-source any modifications if you run it as a service
• ⚠️ Must include original license and copyright

🙏 Acknowledgments

Originally created by Perier. Now developed and maintained by the OpenPlaud community.

Made with ❤️ for Plaud Note users who want full control over their transcriptions.

📚 Resources

• 📖 Documentation - Detailed guides and API references
• 🐛 Issues - Bug reports and feature requests
• 💬 Discussions - Community discussions
• 📝 Changelog - Version history and release notes

⭐ Support the Project

If OpenPlaud is useful to you, consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs and suggesting features
• 📝 Contributing code or documentation
• 💬 Helping others in discussions

---

⬆ Back to Top