🎙️ Audio Transcriber

A powerful audio/video transcription tool powered by OpenAI's Whisper AI. Supports file transcription and real-time live transcription with both CLI and modern Streamlit web interfaces.

✨ Features

🎬 Video & Audio Support - MP4, MKV, MOV, AVI, WebM, WAV, MP3, FLAC, AAC, OGG, M4A
🎤 Real-Time Transcription - Live transcription with ~2-3 second delay
🧠 Multiple Whisper Models - From tiny (fastest) to large-v3 (most accurate)
🎮 GPU Acceleration - CUDA support for fast transcription
🖥️ Hardware Auto-Detection - Automatically recommends optimal settings
📊 Timestamped Output - Get precise timestamps for each segment
🌐 Web UI - Beautiful Streamlit interface with progress tracking
⌨️ CLI - Full command-line support for automation

📋 Requirements

System Requirements

Component	Minimum	Recommended
Python	3.10+	3.11+
RAM	4GB	8GB+
GPU VRAM	1GB (tiny model)	4GB+ (small/medium)
Storage	2GB	5GB (for larger models)

Software Dependencies

FFmpeg - For audio extraction from video files
PortAudio - For real-time audio capture (Linux)
PulseAudio/PipeWire - For system audio routing (Linux)

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/yourusername/AudioTranscriber.git
cd AudioTranscriber

Step 2: Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

Step 3: Install Python Dependencies

pip install -r requirements.txt

Step 4: Install System Dependencies

Ubuntu/Debian

# FFmpeg for audio/video processing
sudo apt install ffmpeg

# PortAudio for real-time audio capture
sudo apt install libportaudio2 portaudio19-dev

# PulseAudio tools for audio routing
sudo apt install pulseaudio-utils pavucontrol

macOS

brew install ffmpeg portaudio

Windows

Download FFmpeg from https://ffmpeg.org/download.html
Add to PATH

Step 5: Verify Installation

# Check FFmpeg
ffmpeg -version

# Check Python packages
python -c "import faster_whisper; import sounddevice; print('All packages installed!')"

🎮 GPU Setup (CUDA)

GPU acceleration significantly speeds up transcription (5-10x faster than CPU).

Option A: Install CUDA Libraries via pip (Recommended)

# Install CUDA/cuDNN libraries
pip install nvidia-cublas-cu12 nvidia-cudnn-cu12

Then use the run.sh script which automatically sets up the library path:

./run.sh live  # or any other command

Option B: Manual Library Path Setup

If not using run.sh, set the library path before running:

export LD_LIBRARY_PATH=$(python -c "import nvidia.cublas.lib, nvidia.cudnn.lib; print(nvidia.cublas.lib.__path__[0] + ':' + nvidia.cudnn.lib.__path__[0])")

Add to ~/.bashrc for persistence:

echo 'export LD_LIBRARY_PATH=$(python -c "import nvidia.cublas.lib, nvidia.cudnn.lib; print(nvidia.cublas.lib.__path__[0] + '\'':'\'' + nvidia.cudnn.lib.__path__[0])" 2>/dev/null):$LD_LIBRARY_PATH' >> ~/.bashrc

Option C: System-Wide CUDA Installation

For system-wide CUDA (useful for other CUDA applications):

# Download CUDA 12.4 runfile
wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda_12.4.0_550.54.14_linux.run

# Install (skip driver if already installed)
sudo sh cuda_12.4.0_550.54.14_linux.run --toolkit --silent

# Add to PATH
echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

Verify GPU Setup

# Check NVIDIA driver
nvidia-smi

# Check CUDA
nvcc --version

# Test in Python
python -c "from faster_whisper import WhisperModel; m = WhisperModel('tiny', device='cuda'); print('CUDA working!')"

🎤 Real-Time Audio Setup (Linux)

To capture system audio (from videos, music, etc.) for real-time transcription, you need to set up audio routing.

Step 1: Create Virtual Audio Sink

# Create a virtual sink for capturing audio
pactl load-module module-null-sink sink_name=VirtualSink sink_properties=device.description="Virtual_Audio_Sink"

Step 2: Set Up Audio Routing

Option A: Capture Only (no audio output)

pactl set-default-sink VirtualSink
pactl set-default-source VirtualSink.monitor

Option B: Capture AND Hear Audio (Recommended)

# Create combined sink that outputs to both speakers and virtual sink
pactl load-module module-combine-sink sink_name=CombinedSink slaves=<YOUR_ACTUAL_SINK>,VirtualSink sink_properties=device.description="Combined_Output"

# Find your actual sink name
pactl list short sinks

# Set combined sink as default
pactl set-default-sink CombinedSink
pactl set-default-source VirtualSink.monitor

Step 3: Make Audio Setup Persistent

Create a script to set up audio on boot:

# Create setup script
cat > ~/setup_audio_capture.sh << 'EOF'
#!/bin/bash
pactl load-module module-null-sink sink_name=VirtualSink sink_properties=device.description="Virtual_Audio_Sink"
pactl load-module module-combine-sink sink_name=CombinedSink slaves=@DEFAULT_SINK@,VirtualSink sink_properties=device.description="Combined_Output"
pactl set-default-sink CombinedSink
pactl set-default-source VirtualSink.monitor
echo "Audio capture setup complete!"
EOF

chmod +x ~/setup_audio_capture.sh

Run before using real-time transcription:

~/setup_audio_capture.sh

Audio Flow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                       AUDIO ROUTING                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Browser/Video Player                                           │
│         │                                                       │
│         ▼                                                       │
│  ┌─────────────────┐                                            │
│  │  CombinedSink   │                                            │
│  └────────┬────────┘                                            │
│           │                                                     │
│     ┌─────┴─────┐                                               │
│     │           │                                               │
│     ▼           ▼                                               │
│ ┌───────┐  ┌─────────────┐                                      │
│ │Speakers│  │ VirtualSink │                                      │
│ │(hear) │  └──────┬──────┘                                      │
│ └───────┘         │                                             │
│                   ▼                                             │
│          ┌───────────────────┐                                  │
│          │ VirtualSink.monitor│                                  │
│          └─────────┬─────────┘                                  │
│                    │                                            │
│                    ▼                                            │
│          ┌───────────────────┐                                  │
│          │   Transcriber     │──▶ Live Text Output              │
│          └───────────────────┘                                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

📖 Usage

Using the Launcher Script (Recommended)

# Make executable (first time only)
chmod +x run.sh

# Show help
./run.sh

# File transcription - Web UI
./run.sh ui

# Real-time transcription - Web UI
./run.sh live

# Real-time transcription - CLI
./run.sh realtime -m tiny

# File transcription - CLI
./run.sh cli input/video.mp4

File Transcription

Web UI

./run.sh ui
# or
streamlit run app_ui.py

Features:

Drag & drop file upload
Select from input/ folder
Model selection with descriptions
Hardware auto-detection & recommendations
Real-time progress tracking
Download transcript button

CLI

# Interactive mode (with menus)
./run.sh cli

# Auto-detect hardware
./run.sh cli -a

# Specify options
./run.sh cli -m small input/video.mp4

# Fast mode (less accurate but faster)
./run.sh cli -m tiny -f input/audio.mp3

# Force CPU
./run.sh cli --cpu input/file.wav

Real-Time Transcription

Web UI

./run.sh live
# or
streamlit run app_live.py

Features:

Audio device selection
Model selection (tiny/base recommended for speed)
Start/Stop controls
Live transcript display
Download transcript

CLI

# Default (tiny model, CUDA)
./run.sh realtime

# List audio devices
./run.sh realtime --list-devices

# Specific model
./run.sh realtime -m base

# CPU mode
./run.sh realtime -m tiny --cpu

# Specific audio device
./run.sh realtime -m tiny -d 0

CLI Options

Option	Description
`-m, --model`	Model: `tiny`, `base`, `small`, `medium`, `large-v2`, `large-v3`
`-f, --fast`	Fast mode (greedy decoding)
`--cpu`	Force CPU mode
`-a, --auto`	Auto-detect hardware settings
`-i, --interactive`	Force interactive menus
`-d, --device`	Audio device index (real-time only)
`--list-devices`	List audio devices (real-time only)

🧠 Model Comparison

Model	Speed	Accuracy	VRAM	Latency*	Best For
`tiny`	⚡⚡⚡⚡⚡	⭐	~1GB	~1-2s	Real-time, testing
`base`	⚡⚡⚡⚡	⭐⭐	~1GB	~2-3s	Real-time, fast drafts
`small`	⚡⚡⚡	⭐⭐⭐	~2GB	~3-5s	Balanced (default)
`medium`	⚡⚡	⭐⭐⭐⭐	~5GB	~5-8s	Good quality
`large-v2`	⚡	⭐⭐⭐⭐⭐	~10GB	~10s+	High accuracy
`large-v3`	⚡	⭐⭐⭐⭐⭐	~10GB	~10s+	Best accuracy

*Latency for real-time transcription with 3-second chunks on GPU

Recommendations

Real-time transcription: Use tiny or base for minimal delay
File transcription: Use small for balance, large-v3 for best quality
Low VRAM (<4GB): Stick to tiny or base
CPU mode: Use tiny with fast mode for acceptable speed

📁 Project Structure

AudioTranscriber/
├── run.sh                  # 🚀 Main launcher script
├── main.py                 # CLI entry point (file transcription)
├── app_ui.py               # Streamlit UI (file transcription)
├── app_live.py             # Streamlit UI (real-time transcription)
├── realtime_transcriber.py # Real-time transcription engine
├── transcriber.py          # Whisper model handling
├── audio_utils.py          # FFmpeg audio processing
├── hardware_utils.py       # Hardware detection & recommendations
├── requirements.txt        # Python dependencies
├── .gitignore              # Git ignore rules
├── README.md               # This file
├── input/                  # Place input files here
├── output/                 # Transcripts saved here
└── venv/                   # Virtual environment (not in git)

📄 Output Format

Transcripts are saved with timestamps:

[0.00 - 2.45] Hello, welcome to the video.
[2.50 - 5.12] Today we're going to talk about machine learning.
[5.20 - 8.34] Let's get started with the basics.

🔧 Troubleshooting

CUDA/cuDNN Errors

Error: Unable to load any of {libcudnn_ops.so.9.1.0, ...}

Solution:

# Option 1: Use CPU mode
./run.sh realtime --cpu

# Option 2: Install CUDA libraries and use run.sh
pip install nvidia-cublas-cu12 nvidia-cudnn-cu12
./run.sh live  # run.sh sets up library path automatically

No Audio Devices Found

Error: sounddevice not installed or no devices listed

Solution:

# Install sounddevice and PortAudio
pip install sounddevice
sudo apt install libportaudio2  # Linux

Real-Time Transcription Not Capturing Audio

Problem: Transcription runs but no text appears

Solution:

Check audio routing:

pactl list short sources
# Should show VirtualSink.monitor

Verify default source:

pactl get-default-source
# Should be VirtualSink.monitor

Play audio and check levels:

# Install pavucontrol for visual monitoring
sudo apt install pavucontrol
pavucontrol

FFmpeg Not Found

Solution:

# Ubuntu/Debian
sudo apt install ffmpeg

# Verify
ffmpeg -version

Out of VRAM

Error: CUDA out of memory

Solution:

# Use smaller model
./run.sh cli -m tiny -f input/video.mp4

# Or use CPU
./run.sh cli --cpu input/video.mp4

Streamlit Port Already in Use

Error: Port 8501 is already in use

Solution:

# Use different port
streamlit run app_ui.py --server.port 8502

📝 License

MIT License - feel free to use and modify.

🙏 Acknowledgments

faster-whisper - Fast Whisper implementation using CTranslate2
OpenAI Whisper - Original Whisper model
Streamlit - Web UI framework
sounddevice - Audio capture library

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app_live.py		app_live.py
app_ui.py		app_ui.py
audio_utils.py		audio_utils.py
hardware_utils.py		hardware_utils.py
main.py		main.py
realtime_transcriber.py		realtime_transcriber.py
requirements.txt		requirements.txt
run.sh		run.sh
transcribe_system.py		transcribe_system.py
transcriber.py		transcriber.py
windows_transcriber.py		windows_transcriber.py

Latest commit

History

Folders and files

Repository files navigation

🎙️ Audio Transcriber

✨ Features

📋 Table of Contents

📋 Requirements

System Requirements

Software Dependencies

🚀 Installation

Step 1: Clone the Repository

Step 2: Create Virtual Environment

Step 3: Install Python Dependencies

Step 4: Install System Dependencies

Ubuntu/Debian

macOS

Windows

Step 5: Verify Installation

🎮 GPU Setup (CUDA)

Option A: Install CUDA Libraries via pip (Recommended)

Option B: Manual Library Path Setup

Option C: System-Wide CUDA Installation

Verify GPU Setup

🎤 Real-Time Audio Setup (Linux)

Step 1: Create Virtual Audio Sink

Step 2: Set Up Audio Routing

Step 3: Make Audio Setup Persistent

Audio Flow Diagram

📖 Usage

Using the Launcher Script (Recommended)

File Transcription

Web UI

CLI

Real-Time Transcription

Web UI

CLI

CLI Options

🧠 Model Comparison

Recommendations

📁 Project Structure

📄 Output Format

🔧 Troubleshooting

CUDA/cuDNN Errors

No Audio Devices Found

Real-Time Transcription Not Capturing Audio

FFmpeg Not Found

Out of VRAM

Streamlit Port Already in Use

📝 License

🙏 Acknowledgments

🤝 Contributing

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages