A self-hosted web application for managing, transcribing, and summarizing audio recordings from HiDock devices. Connect your HiDock via WebUSB, transcribe recordings using VoxHub, rename speakers from diarization, and chat with an LLM about your transcripts.
- WebUSB device connection β browse, download, and manage audio files directly from HiDock H1, H1E, P1, and P1 Mini devices in the browser
- Server-side transcription β audio is uploaded to the FastAPI backend, which proxies to a VoxHub API server (OpenAI-compatible)
- VoxHub Job Mode β async transcription with real-time progress streaming via SSE for long recordings
- Speaker diarization & renaming β color-coded speakers with inline click-to-edit renaming
- Voice fingerprinting β users record a voice sample; speakers are automatically identified by name during transcription (AES-256-GCM encrypted at rest)
- Summary templates β admins define reusable prompt templates; users generate summaries from any transcription with one click
- LLM chat β send any transcript as context to an OpenAI-compatible endpoint and ask questions (streaming)
- Authentication & roles β JWT-based auth with admin and user roles, registration controls, domain whitelisting, admin approval flow
- SSO / OIDC β single sign-on via any OpenID Connect provider (Google, Microsoft Entra ID, Keycloak, Okta, Auth0, etc.), multiple providers simultaneously
- Collections & sharing β organize transcriptions into collections, share with users or groups
- Dark mode β system-aware theme with manual toggle, glass-morphism UI
- Fully dockerized β Docker Compose with PostgreSQL, FastAPI, and Vite/Nginx β designed to sit behind an existing reverse proxy (Caddy, Nginx, Traefik, etc.) over a shared Docker network
ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ
β Browser β WebUSBβ HiDock β β VoxHub API β
β (React + ββββββββΊβ Device β β Server β
β Vite) β ββββββββββββββββ ββββββββββ²ββββββββββ
β β β
β uploads audio via /api β
β β β
ββββββββ¬ββββββββ β
β HTTPS β
ββββββββΌββββββββ ββββββββββββββββ β
β Your reverseββββββββΊβ FastAPI βββββββββββββββββββ
β proxy β β Backend β
β (Caddy / β β βββββββββΊ LLM API (chat/summaries)
β Nginx / β ββββββββ¬ββββββββ
β Traefik) ββββββββΊββββββββΌββββββββ
ββββββββββββββββ β React/Nginx β
β² β Frontend β
β ββββββββββββββββ
proxy-net β
(Docker network) ββββββββΌββββββββ
β PostgreSQL β
ββββββββββββββββ
OpenHiNotes does not bundle a reverse proxy. The frontend container joins an external Docker network (proxy-net) so your existing proxy can reach it by container name (hinotes-frontend). The db and backend containers are isolated on an internal network and are never exposed to the host.
Just want to try it out? See docs/STANDALONE_QUICKSTART.md for a one-command setup with a bundled self-signed Caddy β no external reverse proxy needed.
The instructions below assume you already run a reverse proxy on your server (Caddy, Nginx, Traefik, etc.) and want to integrate OpenHiNotes into it.
- Docker and Docker Compose
- A VoxHub server for transcription
- A reverse proxy (Caddy, Nginx, Traefik, etc.) serving HTTPS β required for WebUSB
- An external Docker network named
proxy-netthat your reverse proxy already uses
Why a separate reverse proxy? WebUSB requires a secure context (HTTPS). OpenHiNotes is designed to sit behind whatever proxy you already run on your server, keeping the compose file simple and avoiding bundled certificate management.
docker network create proxy-netgit clone https://github.com/ghecko/OpenHiNotes.git
cd OpenHiNotes
cp .env.example .env
# Edit .env β at minimum set VOXHUB_API_URL, LLM_API_URL, and SITE_HOST
docker compose up -d --buildThe frontend container is named hinotes-frontend and listens on port 80. Example Caddy block:
hinotes.yourdomain.com {
handle /api/* {
reverse_proxy backend:8000
}
handle {
reverse_proxy hinotes-frontend:80
}
}For Nginx or Traefik, route
/api/*to the backend container on port 8000 and everything else tohinotes-frontend:80.
Open your configured domain in a browser. HTTPS is required for WebUSB to function.
Default admin credentials (override in .env before first startup):
| Field | Default |
|---|---|
admin@openhinotes.local |
|
| Password | admin |
Any Linux host with Docker and Docker Compose installed. The server must be reachable on ports 80 and 443 via your reverse proxy.
cp .env.example .envFill in every variable β pay special attention to the ones marked required:
| Variable | Required | Description |
|---|---|---|
SITE_HOST |
β | Your domain name or IP (e.g. hinotes.company.com) |
SECRET_KEY |
β | Random string for JWT signing β generate with python -c "import secrets; print(secrets.token_hex(32))" |
POSTGRES_PASSWORD |
β | Strong database password |
ADMIN_EMAIL |
β | Initial admin account email |
ADMIN_PASSWORD |
β | Initial admin password β change after first login |
VOXHUB_API_URL |
β | URL of your VoxHub instance |
LLM_API_URL |
β | OpenAI-compatible LLM endpoint |
LLM_API_KEY |
β | API key if required by your LLM |
LLM_MODEL |
β | Model name (default: gpt-3.5-turbo) |
VOICE_EMBEDDING_KEY |
β | AES-256 key for voice fingerprinting encryption. Generate: python -c "import os; print(os.urandom(32).hex())" |
OIDC_ENCRYPTION_KEY |
β | AES-256 key for OIDC client secret encryption. Generate: same command. Required if you use SSO. |
CORS_ORIGINS |
β | Allowed CORS origins (default: *) |
Security note:
VOICE_EMBEDDING_KEYandOIDC_ENCRYPTION_KEYdefault to a derivation ofSECRET_KEYif left empty. Set them explicitly in production so that rotatingSECRET_KEYdoesn't break encrypted data.
Point your existing proxy at the hinotes-frontend container (port 80) for the UI and backend container (port 8000) for /api/*. Both are reachable via the shared proxy-net Docker network.
Example Caddy block for production:
hinotes.company.com {
handle /api/* {
reverse_proxy backend:8000
}
handle {
reverse_proxy hinotes-frontend:80
}
}If your proxy runs outside Docker, expose the frontend port in docker-compose.yml and proxy to localhost:<port> instead.
docker compose up -d --build- Open
https://your-domainin a browser. - Log in with
ADMIN_EMAIL/ADMIN_PASSWORD. - Change the admin password immediately via your profile settings.
- Configure any remaining settings (VoxHub model, LLM, registration policy) from Administration β API Settings.
If you want users to sign in with Google, Microsoft, Keycloak, or another provider:
- Set
OIDC_ENCRYPTION_KEYin.envand restart. - Register an OIDC client with your provider (redirect URI:
https://your-domain/api/auth/oidc/{slug}/callback). - Go to Administration β SSO / OIDC β Add Provider.
Full setup guide: docs/SSO_OIDC_SETUP.md
All configuration is through environment variables. See .env.example for defaults and comments.
| Variable | Description | Default |
|---|---|---|
SITE_HOST |
Domain/IP for Caddy TLS and Vite allowedHosts | localhost |
SECRET_KEY |
JWT signing key | change-me-... |
POSTGRES_PASSWORD |
PostgreSQL password | postgres |
ADMIN_EMAIL |
Initial admin email | admin@openhinotes.local |
ADMIN_PASSWORD |
Initial admin password | admin |
VOXHUB_API_URL |
VoxHub transcription API URL | http://voxhub:8000 |
VOXHUB_MODEL |
Whisper model name | large-v3 |
VOXHUB_JOB_MODE |
Enable async Job Mode (true/false) |
false |
VOXHUB_FREE_AFTER_QUEUE |
Once the queue is empty, ask VoxHub to free its GPU memory (POST /models/free). Also an admin toggle |
false |
VOXHUB_VAD_MODE |
VAD strategy: silero, pyannote, hybrid, none |
silero |
VOXHUB_VERIFY_SSL |
SSL verification for VoxHub (true/false/path) |
true |
LLM_API_URL |
OpenAI-compatible LLM endpoint | http://host.docker.internal:11434/v1 |
LLM_API_KEY |
LLM API key | (empty) |
LLM_MODEL |
LLM model name | gpt-3.5-turbo |
LLM_VERIFY_SSL |
SSL verification for LLM (true/false/path) |
true |
VOICE_EMBEDDING_KEY |
AES-256 key for voice embedding encryption | (derived from SECRET_KEY) |
VOICE_EMBEDDING_KEY_OLD |
Previous key during rotation only | (empty) |
SPEAKER_MATCH_THRESHOLD |
Cosine distance threshold for speaker matching (same voice β 0.1-0.3, different people β₯ 0.35) | 0.3 |
OIDC_ENCRYPTION_KEY |
AES-256 key for OIDC client secret encryption | (derived from SECRET_KEY) |
CORS_ORIGINS |
Allowed CORS origins | * |
The *_VERIFY_SSL settings accept:
"true"β use the system CA store (default)"false"β disable verification (dev only, self-signed certs)- A file path β use a custom CA bundle (e.g.
/etc/ssl/certs/ca-bundle.crt)
OpenHiNotes/
βββ backend/ # Python FastAPI application
β βββ app/
β β βββ models/ # SQLAlchemy ORM models
β β βββ schemas/ # Pydantic request/response schemas
β β βββ routers/ # API route handlers
β β βββ services/ # Business logic (auth, OIDC, transcription, LLM)
β β βββ main.py # FastAPI app entry point
β β βββ config.py # Settings from environment variables
β β βββ database.py # Async SQLAlchemy setup
β β βββ dependencies.py # Auth dependencies
β βββ alembic/ # Database migrations (auto-applied on startup)
β βββ requirements.txt
β βββ Dockerfile
βββ frontend/ # React + Vite + TypeScript application
β βββ src/
β β βββ api/ # Backend API client modules
β β βββ components/ # Reusable UI components
β β βββ pages/ # Route pages (including admin panel)
β β βββ store/ # Zustand state management
β β βββ types/ # TypeScript type definitions
β βββ package.json
β βββ Dockerfile
βββ docs/ # Feature documentation
β βββ SSO_OIDC_SETUP.md # SSO/OIDC provider setup guide
β βββ VOICE_FINGERPRINTING.md
βββ docker-compose.yml # Development orchestration
βββ docker-compose.prod.yml # Production orchestration
βββ Caddyfile # Dev reverse proxy (self-signed TLS)
βββ Caddyfile.prod # Production reverse proxy
βββ .env.example # Environment variable template
| Device | Product IDs |
|---|---|
| HiDock H1 | 0xAF0C |
| HiDock H1E | 0xAF0D, 0xB00D |
| HiDock P1 | 0xAF0E, 0xB00E |
| HiDock P1 Mini | 0xAF0F |
Run services locally without Docker:
# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Set DATABASE_URL to a local PostgreSQL instance
uvicorn app.main:app --reload --port 8000
# Frontend
cd frontend
npm install
npm run devThe Vite dev server proxies /api requests to http://localhost:8000 automatically.
| Layer | Technology |
|---|---|
| Frontend | React 18, Vite 5, TypeScript, Tailwind CSS 3, Zustand, React Router 6 |
| Backend | Python 3.11, FastAPI, SQLAlchemy 2 (async), Alembic, Pydantic v2 |
| Database | PostgreSQL 16 |
| Auth | JWT (python-jose), bcrypt (passlib), OIDC (authlib) |
| Encryption | AES-256-GCM (cryptography) |
| Device | WebUSB API (browser-native) |
| Transcription | VoxHub (OpenAI-compatible) |
| Deployment | Docker Compose, Caddy 2 |
This project is a full rewrite of HiDock Next, the original open-source web client for HiDock recording devices. The WebUSB protocol implementation and device communication layer are derived from that project. OpenHiNotes replaces the client-only architecture with a FastAPI backend, adds server-side transcription via VoxHub, authentication, SSO/OIDC, summary templates, voice fingerprinting, and LLM chat capabilities.
See LICENSE for details.