TranscriptionAI

A command-line tool that transcribes YouTube videos automatically: you pass just the video URL and it downloads the audio as mp3 (yt-dlp), transcribes it with AI running fully on your machine (Whisper, GPU-accelerated with a CPU fallback) and keeps everything tidy: each video becomes a subfolder holding its .mp3 and the .txt transcript, with per-step progress bars and timings right in the terminal.

✨ Features

• Fully local transcription, nothing is sent to external servers
• GPU acceleration (NVIDIA/CUDA) with an automatic CPU fallback
• Progress bars per step (download and transcription) and total time at the end
• Automatic language detection (or forced with -l pt)
• 6 Whisper models to choose from, from the fastest to the most accurate
• Automatic retry on temporary download failures
• Detailed logs of every run saved to logs/

📦 Dependencies

Dependency	What for
Python 3.12+	Running the project
ffmpeg	Converting the audio to mp3
Node.js	JS runtime yt-dlp needs for YouTube

Python libraries (installed from requirements.txt):

• yt-dlp: downloads the audio from the videos
• faster-whisper: transcription with the optimized Whisper model
• rich: progress bars and terminal interface
• nvidia-cublas-cu12 / nvidia-cudnn-cu12 / nvidia-cuda-runtime-cu12: CUDA libraries for GPU support (optional; without a GPU the script uses the CPU)

🚀 Installing

There are two ways to install: with a project-local virtual environment (the transcribe command only works from inside the venv, or after activating it), or globally with pipx (the transcribe command works from any folder, in any terminal, no activation needed).

Option A: virtual environment

Linux

# 1. System dependencies
sudo apt install ffmpeg nodejs

# 2. Clone the repository
git clone https://github.com/MaykeESA/transcription-ai.git
cd transcription-ai

# 3. Create the virtual environment and install the project
python3 -m venv .venv
.venv/bin/python -m pip install -e .

Windows

# 1. System dependencies
winget install ffmpeg
winget install OpenJS.NodeJS.LTS

# 2. Clone the repository
git clone https://github.com/MaykeESA/transcription-ai.git
cd transcription-ai

# 3. Create the virtual environment and install the project
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .

pip install -e . installs every dependency and also registers a transcribe command inside the venv, so you can call it directly instead of python transcribe.py. If you'd rather skip that and only install the dependencies, use pip install -r requirements.txt instead.

Calling the venv interpreter by its path means you never have to activate the environment. If you prefer activating it to shorten the commands, use source .venv/bin/activate on Linux or .venv\Scripts\Activate.ps1 on PowerShell, the latter requiring you to allow scripts once with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Option B: pipx (global command)

pipx installs the tool in its own isolated environment and puts the transcribe command on your PATH, so it works from any folder, in any terminal, without activating anything.

# Install pipx once, if you don't have it yet
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Clone the repository and install with pipx
git clone https://github.com/MaykeESA/transcription-ai.git
cd transcription-ai
pipx install --editable .

--editable keeps the command pointing at your local clone, so any change you make to the code is picked up right away. Without it, pipx install . copies the code, and you'd need to run pipx install . --force again after every change. If you just want the tool as an end user and don't plan on touching the code, pipx install . alone is simpler.

On Windows the steps are the same, replacing python3 with python.

💻 Usage

The transcribe command works the same way regardless of how you installed it. If you used the virtual environment without an editable install, prefix commands with the venv's Python instead: .venv/bin/python transcribe.py (Linux) or .venv\Scripts\python.exe transcribe.py (Windows).

# Basic: just pass the URL (language is detected automatically)
transcribe "https://www.youtube.com/watch?v=VIDEO_ID"

# Forcing Portuguese
transcribe "URL" -l pt

# More accurate model
transcribe "URL" -m medium -l pt

# Long videos: low priority, the machine stays responsive (Linux/macOS only)
nice -n 19 transcribe "URL" -l pt

# Networks where IPv6 is broken
transcribe "URL" -l pt --force-ipv4

# Choose (and remember) where output goes, instead of ./transcriptions
transcribe "URL" -o ~/Videos/transcriptions

The result lands in <output dir>/<video title>/, with the .mp3, the .txt and a logs/ folder all grouped together. By default <output dir> is ./transcriptions, created in whichever folder you ran the command from. Passing -o once remembers that location for every future run, from any folder, until you pass -o again with a different path.

Every option: transcribe --help

Model (-m)	Speed	Accuracy
tiny / base	very fast	basic
small (default)	fast	good
medium	slower	great
large-v3 / turbo	slow / fast	excellent (wants a strong GPU)

📄 Copyright and license

Code and documentation copyright 2026 Mayke Erick. Code released under the MIT License.