Skip to main content

Quick Start Guide

Get OpenTranscribe up and running in less than 5 minutes with our one-line installer.

One-Line Installation​

Run this single command on any platform (Linux, macOS, Windows WSL2):

curl -fsSL https://raw.githubusercontent.com/attevon-llc/OpenTranscribe/master/setup-opentranscribe.sh | bash

The installer will: ✅ Detect your hardware automatically (NVIDIA GPU, Apple Silicon, CPU) ✅ Configure optimal settings for your platform ✅ Download Docker images from Docker Hub ✅ Generate secure configuration ✅ Set up management scripts

By default it installs the full image (local transcription and speaker detection, on the GPU when one is found). Add --cpu (curl ... | bash -s -- --cpu) to run the full image on CPU only, or --lite for the cloud-only image. On an arm64 host such as Apple Silicon it defaults to the lite image, the only one published for arm64. Add --version vX.Y.Z to install a specific release instead of the latest one. See Deployment Variants to choose.

Prerequisites​

Before running the installer, ensure you have:

  1. Docker & Docker Compose installed and running
  2. Internet connection for downloading images and models
  3. 8GB+ RAM (16GB+ recommended)
HuggingFace Token Required

For speaker detection on this server (the full image's default), you'll need a free HuggingFace token. The installer will prompt you for it. Speakers detected by a cloud provider do not need it, but the voiceprint model is exported from the same gated repository, so set it on a lite install too if you run the diar-native sidecar. See HuggingFace Setup for details.

Installation Steps​

Step 1: Run the Installer​

curl -fsSL https://raw.githubusercontent.com/attevon-llc/OpenTranscribe/master/setup-opentranscribe.sh | bash

Step 2: Follow the Prompts​

The installer will ask for:

  1. HuggingFace Token (optional but recommended)

  2. Whisper Model Size (default: large-v3-turbo — auto-detected based on hardware)

    • large-v3-turbo - 6x faster, excellent accuracy (default, NVIDIA GPU recommended)
    • large-v3 - Best accuracy; use it rather than the turbo model if you need translation to English
    • medium - Good balance (the installer's pick for NVIDIA GPUs with 4-8GB VRAM)
    • small - The installer's pick on Apple Silicon and GPUs under 4GB VRAM
    • base - Fast (recommended on CPU-only systems)

    The installer also offers tiny and large-v2.

CPU-only installs and speaker detection

On a host with no GPU (or with --cpu), speaker detection is not switched off for you: each user's setting in Settings → Speaker Identification decides, and on a CPU-only install speaker detection on this server runs on the CPU. To skip it, choose Off there or skip speaker detection for a file. See Environment Variables.

Step 3: Start OpenTranscribe​

cd opentranscribe
./opentranscribe.sh start

Step 4: Access the Application​

Open your browser and navigate to:

First Transcription​

1. Sign In as the Bootstrap Administrator​

On first start the backend creates one super_admin account, admin@example.com (or the address in INITIAL_ADMIN_EMAIL). What its password is depends on the deployment:

  • Installer or production install (the default): unless you set INITIAL_ADMIN_PASSWORD in .env before the first start, a random password is generated and written once to the backend log. Read it with ./opentranscribe.sh logs backend and look for Created bootstrap admin ... with a GENERATED password. A generated password must be changed at first sign-in.
  • Development stack (./opentr.sh start dev): admin@example.com / password.

Other people can create their own accounts from the registration page (email, password, then "Create Account") unless self-registration is turned off (ALLOW_OPEN_REGISTRATION=false, or Settings → Authentication). Administrators can also require approval of new accounts.

Guided First-Run Setup Wizard​

The bootstrap super_admin sees a one-time guided setup wizard on first login instead of the empty gallery. Rather than leaving you to discover dozens of auth-related environment variables and several admin tabs on your own, it surfaces the three things a first-time operator actually needs:

  • Change your password from whatever was used during account creation
  • Deployment type, which points you at SSO (OIDC) or LDAP setup if you're connecting an identity provider
  • Security defaults — MFA-required, login banner, and approval-on-signup

The wizard presents OpenTranscribe's real settings screens rather than a separate duplicate flow, so anything you configure here is the same configuration you'd reach from Settings → Authentication later. It's shown once; skipping or finishing it won't bring it back automatically, but you can run it again from Settings → Authentication.

2. Upload a Media File​

  1. Click the "Add Media" button in the gallery
  2. Drag and drop a file or click to browse
  3. Supported formats: MP3, WAV, MP4, MOV, etc.
  4. Files up to 15 GB are supported by default (MAX_UPLOAD_BYTES)

3. Monitor Processing​

Watch the progress in real-time:

  • Upload progress shows in the floating upload manager
  • Processing stages show the current step (see Your First Transcription)
  • Notifications appear when transcription completes

4. View Your Transcript​

Once processing completes:

  1. Click on the file in your library
  2. View the interactive transcript with speaker labels
  3. Click on any word to jump to that moment in the audio
  4. Use the waveform visualization for precise navigation

What's Next?​

Now that you have OpenTranscribe running, explore these features:

Configure AI Features​

Set up LLM integration for AI-powered summarization:

  • Go to Settings → AI & Chat → LLM Provider Configuration
  • Choose a provider (OpenAI, Claude, vLLM, Ollama)
  • Enter your API key
  • Test the connection

See LLM Integration for details.

Enterprise Authentication (Optional)​

For enterprise deployments, OpenTranscribe supports:

  • LDAP/Active Directory - Integrate with existing AD
  • Keycloak/OIDC - Single Sign-On
  • PKI/X.509 - Certificate-based authentication
  • MFA - TOTP-based multi-factor authentication

See Authentication Overview for setup guides.

Manage Speakers​

OpenTranscribe automatically detects speakers, but you can improve accuracy:

  • Edit speaker names in any transcript
  • Create global speaker profiles
  • Let AI suggest speaker identities across videos

See Speaker Management for more.

Organize with Collections​

Group related media files:

  • Create collections for projects, topics, or events
  • Add files to multiple collections
  • Filter your library by collection

See Collections for details.

Find content across all your transcriptions:

  • Keyword search - Find exact words or phrases
  • Semantic search - Find similar concepts
  • Filters - By speaker, date, duration, tags
  • Speaker analytics - See who speaks most across your library

See Search & Filters for tips.

Common Commands​

Management Commands​

# Start OpenTranscribe
./opentranscribe.sh start

# Stop all services
./opentranscribe.sh stop

# View logs
./opentranscribe.sh logs

# Check status
./opentranscribe.sh status

# Restart services
./opentranscribe.sh restart

# Access database
./opentranscribe.sh shell postgres

Updating OpenTranscribe​

# Check current version and available updates
./opentranscribe.sh version

# Update containers only (quick)
./opentranscribe.sh update

# Full update including config files (recommended)
./opentranscribe.sh update-full

Troubleshooting​

Services Won't Start​

# Check Docker is running
docker ps

# Check logs for errors
./opentranscribe.sh logs backend

GPU Not Detected​

# Check GPU availability
nvidia-smi

# Test GPU in Docker
docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

Permission Errors​

# Fix model cache permissions
./scripts/fix-model-permissions.sh

Slow Transcription​

  • Ensure GPU acceleration is enabled: ./opentranscribe.sh compose-files should list docker-compose.gpu.yml, and FORCE_CPU_MODE in .env should not be true
  • Reduce model size if running out of memory
  • Check GPU memory usage with nvidia-smi

See Troubleshooting Guide for more solutions.

Getting Help​

If you encounter issues:

  1. Check the FAQ
  2. Search GitHub Issues
  3. Ask in GitHub Discussions
  4. Read the Installation Guide for detailed setup

Next Steps​

Welcome to OpenTranscribe!