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:
- Docker & Docker Compose installed and running
- Internet connection for downloading images and models
- 8GB+ RAM (16GB+ recommended)
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:
-
HuggingFace Token (optional but recommended)
- Used for the speaker-detection and voiceprint models that run on this server
- Get a free token at huggingface.co/settings/tokens
-
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 Englishmedium- 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 VRAMbase- Fast (recommended on CPU-only systems)
The installer also offers
tinyandlarge-v2.
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:
- Web Interface: http://localhost:5173
- API Documentation: http://localhost:5174/api/docs (disabled on production deployments unless
ENABLE_API_DOCS=trueis set in.env) - Task Monitor (Flower): http://localhost:5175/flower
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_PASSWORDin.envbefore the first start, a random password is generated and written once to the backend log. Read it with./opentranscribe.sh logs backendand look forCreated 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
- Click the "Add Media" button in the gallery
- Drag and drop a file or click to browse
- Supported formats: MP3, WAV, MP4, MOV, etc.
- 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:
- Click on the file in your library
- View the interactive transcript with speaker labels
- Click on any word to jump to that moment in the audio
- 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.
Advanced Search
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-filesshould listdocker-compose.gpu.yml, andFORCE_CPU_MODEin.envshould not betrue - 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:
- Check the FAQ
- Search GitHub Issues
- Ask in GitHub Discussions
- Read the Installation Guide for detailed setup
Next Steps
- User Guide: Learn about all features
- Configuration: Customize environment variables
- Development: Learn to contribute
Welcome to OpenTranscribe!