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/davidamacey/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

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 diarization to work, you'll need a free HuggingFace token. The installer will prompt you for it. See HuggingFace Setup for details.

Installation Steps​

Step 1: Run the Installer​

curl -fsSL https://raw.githubusercontent.com/davidamacey/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: auto-detected based on hardware)

    • large-v2 - Best accuracy (NVIDIA GPU recommended)
    • medium - Good balance (8GB+ GPU or Apple Silicon)
    • base - Fast (CPU-only systems)

Step 3: Start OpenTranscribe​

cd opentranscribe
./opentranscribe.sh start

Step 4: Access the Application​

Open your browser and navigate to:

First Transcription​

1. Create an Account​

When you first access OpenTranscribe, you'll see the registration page:

  1. Enter your email and password
  2. Click "Sign Up"
  3. You're automatically logged in

2. Upload a Media File​

  1. Click the "Upload Files" button in the navbar
  2. Drag and drop a file or click to browse
  3. Supported formats: MP3, WAV, MP4, MOV, etc.
  4. Files up to 4GB are supported

3. Monitor Processing​

Watch the progress in real-time:

  • Upload progress shows in the floating upload manager
  • Processing stages display 13 detailed steps
  • 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 User Settings → LLM Configuration
  • Choose a provider (OpenAI, Claude, vLLM, Ollama)
  • Enter your API key
  • Test the connection

See LLM Integration for details.

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​

# Pull latest images
docker compose pull

# Restart services
./opentranscribe.sh restart

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:11.8-base-ubuntu22.04 nvidia-smi

Permission Errors​

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

Slow Transcription​

  • Ensure GPU acceleration is enabled (USE_GPU=true in .env)
  • 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! 🎉