Video Downloader and Transcriber with Whisper

This Python script allows you to download videos from various platforms and automatically transcribe the audio into text using OpenAI's Whisper model. The transcript includes timestamps and is saved in a Markdown file alongside the video information.

• Download videos from multiple supported platforms using yt-dlp.
• Transcribe local audio or video files (e.g. MP3, MP4, WAV, M4A) in addition to downloaded videos.
• Transcribe local Audible .aax / .aaxc files (decode with AAXtoMP3, then Whisper).
• Transcribe video audio to text with timestamps using OpenAI's Whisper model.
• Save the transcription, complete with timestamps, in a Markdown file.
• Automatically detects and uses GPU if available.

This script supports downloading videos from a wide variety of platforms via yt-dlp, including but not limited to:

• YouTube
• Reddit
• TED Talks
• And many more...

For a full list of supported platforms, refer to the official yt-dlp supported sites.

PyTorch requires Python 3.10–3.12. If your default python3 is newer (e.g. 3.14), use the project virtual environment instead of installing globally.

One-time setup:

./setup.sh

This creates .venv/ and installs torch, openai-whisper, and yt-dlp from requirements.txt.

Manual setup (equivalent):

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

1. Clone this repository:

git clone https://github.com/ykon-cell/whisper-video-tool.git
cd whisper-video-tool

2. Run the script (with the venv activated, or use .venv/bin/python):

source .venv/bin/activate
python download_and_transcribe.py

3. When prompted, enter either:
   • A video URL from any supported platform — the script will download it, transcribe it, and save the transcription in a folder named after the video.
   • A path to a local file (e.g. ./my_audio.mp3 or ~/Music/podcast.mp4) — the script will transcribe it and save a .md file with the same name in the same directory (e.g. my_audio.md).
4. yt-dlp is only required when using a video URL; local files can be transcribed without it.

./run_gui.sh

Or with the venv activated: python gui.py

Enter a video URL and/or choose a local file, then click Start.

python download_and_transcribe.py --aax /path/to/book.aax
python download_and_transcribe.py --aax book.aax --output transcript.md --keep-mp3
python download_and_transcribe.py ./podcast.mp3 -o ./out/

Transcribe audiobooks you already own on your Audible account. The tool decodes the file to MP3, then runs Whisper. Use only for your own purchases; activation bytes are tied to your account.

macOS (Homebrew):

pip install audible-cli
brew install ffmpeg jq grep gnu-sed findutils
git clone https://github.com/KrumpetPirate/AAXtoMP3.git
export AAXTOMP3_SCRIPT="$HOME/AAXtoMP3/AAXtoMP3"   # adjust path

On macOS, AAXtoMP3 expects GNU grep, sed, and find on your PATH (e.g. from Homebrew).

1. Log in to Audible:

   audible quickstart

2. Confirm activation bytes:

   audible activation-bytes

3. Set the path to the AAXtoMP3 script (add to your shell profile to persist):

   export AAXTOMP3_SCRIPT="/absolute/path/to/AAXtoMP3"

Secrets via .env (recommended for GUI):

cp .env.example .env
# Edit .env — use AUDIBLE_PASSWORD for your quickstart encryption password,
# or AUDIBLE_AUTHCODE for the 8-character hex activation bytes (not both meanings in one field)

The app loads .env from the project folder on startup (.env is gitignored). Shell variables already set take precedence.

Other optional env vars:

• AUDIBLE_AUTHCODE — use these bytes directly (skip audible-cli).
• AUDIBLE_PASSWORD — password for your encrypted ~/.audible auth file.
• Or save bytes once: audible -p 'YOUR_PASSWORD' activation-bytes | tr -d '\\n' > ~/.authcode

.aaxc must be downloaded with audible-cli so chapter, cover, and voucher files sit in the same folder as the .aaxc (names must match what audible-cli creates). Example:

audible download --asin B012345678 --aaxc --chapter --cover

ffmpeg 4.4+ is required for .aaxc.

• CLI: Enter a path to .aax or .aaxc when prompted, or use --aax.
• GUI: Browse for an .aax / .aaxc file under Local file, then Start.

The transcript is saved as .md next to the audiobook (or at Output if set). Decoded MP3 is removed after transcribing unless you pass --keep-mp3.

After running the script, a Markdown file will be created in a folder with the following format:

00:00:00,000 --> 00:00:05,000 This is the transcription text for the first segment.
00:00:05,000 --> 00:00:10,000 This is the transcription text for the second segment.
...
Original Video URL: https://www.example.com/example

• Support for multiple languages in transcription.
• Improve error handling for different platforms.