vxbeamer is a self-hosted, personal speech transcriber with a real-time web interface.

I speak into my phone. The voice message is instantly transcribed. Then I can swipe on my phone to beam the transcription to my laptop.

For most of my transcription needs, I use Google Gemini (through the @lsnr LINE bot) as it provides the highest accuracy. However, it comes with high latency, which makes it somewhat frustrating to use for voice typing scenarios. (It has very high throughput though, e.g., 15 minutes of audio content can be transcribed in less than 20 seconds.)

vxbeamer uses a different workflow: Qwen3-ASR-Flash handles real-time speech recognition, and gpt-oss-120b (an open-source model by OpenAI, served on Groq for fast inference) does post-processing. This trades some accuracy for significantly faster feedback.

The frontend is a PWA that can be added to the home screen. Tap the record button to transcribe, swipe right to broadcast a transcription as an event (for custom integrations), and swipe left to delete it.

This project is primarily for personal use and is not designed to be particularly flexible. That said, the setup is documented below.

1. Deploy and configure the backend URL
2. Sign in with OIDC
3. To start transcribing, click the start recording button
4. To stop, click the same button
5. Click on the transcript bubble to copy, swipe left to delete, swipe right to beam to custom integrations

• Frontend — React PWA (apps/website), deployed statically (hosted on Vercel)
• Backend — Node.js/Hono server (apps/backend), deployed via Docker (self-hosted)
• Desktop app — Tauri desktop client (apps/desktop) that receives backend events and integrates with the local machine (basically, it’s the frontend web app with extra desktop integrations)
• ASR — Qwen3-ASR-Flash via DashScope (Alibaba Cloud)
• Post-processing — gpt-oss-120b via Groq

vxbeamer comes with 2 two authentication methods:

• User authentication via OIDC, for interactive use from the frontend.
• API keys (via API_KEYS), for integration with scripts.

The OIDC provider must support:

1. PKCE flow — the frontend performs the authorization code flow with PKCE and exchanges the resulting ID token for a session with the backend.
2. Discovery document — the provider must expose its configuration at the standard /.well-known/openid-configuration path.
3. CORS — cross-origin requests must be allowed, since the frontend will contact the provider directly from the browser.
4. Restricted token issuance — the provider must only issue ID tokens to authorized users. There is no built-in user whitelist in vxbeamer itself, so access control must be enforced at the provider level.

Authentik is a self-hosted, open-source identity provider that meets all of these requirements.

Set the API_KEYS environment variable in the format <sub>:<key>. In case of multiple keys, separate by commas:

API_KEYS=your-sub-claim:my-secret-key,your-sub-claim:another-secret

To find your sub claim:

1. Sign in to the web app with OIDC
2. Open Settings (⚙️ icon)
3. Copy your sub from the "Signed in" section

The <sub> must match the sub claim of your OIDC user. You can have multiple keys for the same user (useful for key rotation or different integrations).

API keys are not used directly for authenticated requests. Instead, scripts exchange them for short-lived access tokens via POST /auth/token. This keeps all authentication consistent: protected endpoints only accept session tokens, regardless of whether they came from OIDC or API key exchange.

A full deployment consists of three parts:

1. OIDC provider — an OIDC-compatible identity provider such as Authentik (see Authentication above).
2. Backend — a self-hosted server you run yourself (see below).
3. Frontend — the web application, available at vxbeamer.vercel.app. This hosted instance is provided as-is and connects to whichever backend URL you configure in its settings. Only the frontend is hosted; you must run your own backend.

The backend is distributed as a Docker image.

services:
  backend:
    image: ghcr.io/dtinth/vxbeamer:latest
    pull_policy: always
    restart: unless-stoppped
    expose:
      - 8787
    environment:
      - DASHSCOPE_API_KEY
      - GROQ_API_KEY
      - BYTEPLUS_API_KEY
      - OIDC_DISCOVERY_URL
      - OIDC_CLIENT_ID
      - OIDC_SECRET
      - API_KEYS

The backend exposes a REST + SSE + WebSocket API on port 8787. All endpoints (except /healthz and /auth/*) require an access token, obtained by exchanging OIDC id_tokens or API keys.

Connect to /sse to receive real-time events. Pass ?events=<type> to filter, e.g. ?events=swiped to receive only swipe events (the initial snapshot is skipped when a filter is active).

Connect to /ws?access_token=<token>. Send raw PCM audio as binary frames (16 kHz, 16-bit signed, mono, little-endian). Send { "type": "stop" } as a text frame to end the session gracefully.

All protected endpoints require an access token. Pass it as:

• Authorization: Bearer <token> header, or
• ?access_token=<token> query parameter

For OIDC users (interactive frontend):

1. Exchange OIDC id_token for access & refresh tokens: POST /auth/session with id_token
2. Access token (15 min TTL) is used for protected endpoints
3. When access token < 10 minutes remaining, refresh both tokens: POST /auth/refresh with refresh_token
4. Refresh token is valid for 3 days from the last refresh

For API keys (scripts/integrations):

1. Exchange API key for access token: POST /auth/token with api_key
2. Access token (15 min TTL) is used for protected endpoints
3. No refresh token is issued; obtain a new access token by exchanging the API key again