By Greyhaven

What is Reflector?

Reflector is a web application that utilizes local models to process audio content, providing:

• Real-time Transcription: Convert speech to text using Whisper (multi-language) or Parakeet (English) models
• Speaker Diarization: Identify and label different speakers using Pyannote 3.1
• Live Translation: Translate audio content in real-time to many languages with Facebook Seamless-M4T
• Topic Detection & Summarization: Extract key topics and generate concise summaries using LLMs
• Meeting Recording: Create permanent records of meetings with searchable transcripts

Architecture

The project consists of three primary components:

• Back-End: Python FastAPI server with async database operations and background processing, found in server/.
• Front-End: Next.js 14 React application with Chakra UI, located in www/.
• GPU Models: Specialized ML models for transcription, diarization, translation, and summarization.

Currently, Reflector supports two input methods:

• Screenshare capture: Real-time audio capture from your browser via WebRTC
• Audio file upload: Upload pre-recorded audio files for processing

Installation

For full deployment instructions, see the Self-Hosted Production Guide and the Architecture Reference.

Self-Hosted Deployment

The self-hosted setup script configures and launches everything on a single server:

# GPU with local Ollama LLM, local S3 storage, and Caddy reverse proxy
./scripts/setup-selfhosted.sh --gpu --ollama-gpu --garage --caddy

# With a custom domain (enables Let's Encrypt auto-HTTPS)
./scripts/setup-selfhosted.sh --gpu --ollama-gpu --garage --caddy --domain reflector.example.com

# CPU-only mode (slower, no NVIDIA GPU required)
./scripts/setup-selfhosted.sh --cpu --ollama-cpu --garage --caddy

# With password authentication
./scripts/setup-selfhosted.sh --gpu --ollama-gpu --garage --caddy --password mysecretpass

The script is idempotent and safe to re-run. See ./scripts/setup-selfhosted.sh --help for all options.

Authentication

Reflector supports three authentication modes:

• Password authentication (recommended for self-hosted / single-user): Use the --password flag in the setup script. This creates an admin@localhost user with the provided password. Users must log in to create, edit, or delete transcripts.

  ./scripts/setup-selfhosted.sh --gpu --ollama-gpu --garage --caddy --password mysecretpass
  

• Authentik OIDC: For multi-user or enterprise deployments, Reflector supports Authentik as an OAuth/OIDC provider. This enables SSO, LDAP/AD integration, and centralized user management. Requires configuring AUTH_BACKEND=jwt on the backend and AUTH_PROVIDER=authentik on the frontend. See the Self-Hosted Production Guide for details.

• Public mode (default when no auth is configured): If neither password nor Authentik is set up, Reflector runs in public mode. In this mode, no login is required — anyone with access to the URL can use the application. Transcripts are created anonymously (not tied to any user account), which means they cannot be edited or deleted through the UI or API. Anonymous transcripts are automatically cleaned up after 7 days. This mode is suitable for demos or testing but not recommended for production use.

Development Setup

# Backend
cd server
uv sync
docker compose up -d redis
uv run alembic upgrade head
uv run -m reflector.app --reload

# In a separate terminal — start the worker
cd server
uv run celery -A reflector.worker.app worker --loglevel=info

# Frontend
cd www
pnpm install
cp .env_template .env
pnpm dev

Modal.com GPU (Optional)

Reflector also supports deploying specialized models (transcription, diarization) to Modal.com for serverless GPU processing. This is not integrated into the self-hosted setup script and must be configured manually.

See Modal.com Setup Guide for deployment instructions.

Audio Processing Commands

Process a local audio file

cd server
uv run python -m reflector.tools.process path/to/audio.wav

Reprocess an existing transcription

Re-run the processing pipeline on a previously uploaded transcription by its UUID:

cd server
uv run -m reflector.tools.process_transcript <transcript-uuid> --sync

Usage

To record both your voice and the meeting you're taking part in, you need:

• For an in-person meeting, make sure your microphone is in range of all participants.
• If using several microphones, make sure to merge the audio feeds into one with an external tool.
• For an online meeting, if you do not use headphones, your microphone should be able to pick up both your voice and the audio feed of the meeting.
• If you want to use headphones, you need to merge the audio feeds with an external tool.

Permissions:

You may have to add permission for browser's microphone access to record audio in System Preferences -> Privacy & Security -> Microphone System Preferences -> Privacy & Security -> Accessibility. You will be prompted to provide these when you try to connect.

How to Install Blackhole (Mac Only)

This is an external tool for merging the audio feeds as explained in the previous section of this document. Note: We currently do not have instructions for Windows users.

• Install Blackhole-2ch (2 ch is enough) by 1 of 2 options listed.
• Setup "Aggregate device" to route web audio and local microphone input.
• Setup Multi-Output device
• Then goto System Preferences -> Sound and choose the devices created from the Output and Input tabs.
• The input from your local microphone, the browser run meeting should be aggregated into one virtual stream to listen to and the output should be fed back to your specified output devices if everything is configured properly.

Build-time env variables

Next.js projects are more used to NEXT_PUBLIC_ prefixed buildtime vars. We don't have those for the reason we need to serve a customizable prebuilt docker container.

Instead, all the variables are runtime. Variables needed to the frontend are served to the frontend app at initial render.

It also means there's no static prebuild and no static files to serve for js/html.

Feature Flags

Reflector uses environment variable-based feature flags to control application functionality. These flags allow you to enable or disable features without code changes.

Available Feature Flags

Setting Feature Flags

Feature flags are controlled via environment variables using the pattern FEATURE_{FEATURE_NAME} where {FEATURE_NAME} is the SCREAMING_SNAKE_CASE version of the feature name.

Examples:

# Enable user authentication requirement
FEATURE_REQUIRE_LOGIN=true

# Disable browse functionality
FEATURE_BROWSE=false

# Enable Zulip integration
FEATURE_SEND_TO_ZULIP=true

Contribution Guidelines

All new contributions should be made in a separate branch, and goes through a Pull Request. Conventional commits must be used for the PR title and commits.

Future Plans

• Multi-language support enhancement: Default language selection per room/user, automatic language detection improvements, multi-language diarization, and RTL language UI support
• Jitsi integration: Self-hosted video conferencing rooms with no external API keys, full control over video infrastructure, and enhanced privacy
• Calendar integration: Google Calendar and Microsoft Outlook synchronization, automatic meeting room creation, and post-meeting transcript delivery
• Enhanced analytics: Meeting insights dashboard, speaker participation metrics, topic trends over time, and team collaboration patterns
• Advanced AI features: Real-time sentiment analysis, emotion detection, meeting quality scores, and automated coaching suggestions
• Integration ecosystem: Slack/Teams notifications, CRM integration (Salesforce, HubSpot), project management tools (Jira, Asana), and knowledge bases (Notion, Confluence)
• Performance improvements: WebAssembly for client-side processing, edge computing support, and network optimization

Legacy Documentation

The docs/ folder contains an older Docusaurus-based documentation site. These docs are no longer actively maintained and may be outdated. For current installation and deployment instructions, refer to the docsv2/ folder instead.