Skip to content

README.md

Latest commit

 

History

History
343 lines (222 loc) · 11.9 KB

README.md

File metadata and controls

343 lines (222 loc) · 11.9 KB
Raw

YouTube Audio and Text Transcriber

A local command-line tool that downloads audio from YouTube videos and creates text transcripts using faster-whisper.

By default, one command creates two useful outputs:

  1. A local MP3 audio file converted from the video's audio stream.
  2. A local text transcript in both plain-text and Markdown formats.

You can keep both outputs, keep only the audio, or create transcripts without retaining the downloaded audio.

Supported platforms

The project is verified on macOS with Python 3.10 or newer. Linux and Windows are not currently verified.

CPU transcription is the default. NVIDIA CUDA can be selected, but installing and configuring the required NVIDIA software is outside this project's scope.

Install on macOS

The recommended installation requires Homebrew, a package manager for macOS.

First, check whether Homebrew is already installed:

brew --version

If Terminal prints a Homebrew version, continue to Install YouTube Transcriber below.

If Terminal reports:

zsh: command not found: brew

install Homebrew with its official installer:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

When the installer finishes, find the Next steps section in Terminal. Run the exact commands shown there before continuing. These commands make brew available in new Terminal sessions.

Verify that Homebrew now works:

brew --version

Install YouTube Transcriber

brew install jn-root/tap/youtube-transcriber

Verify the installation:

yt-transcribe --version

Create your first audio file and transcripts:

yt-transcribe "https://www.youtube.com/watch?v=VIDEO_ID"

Replace VIDEO_ID with the ID from a public YouTube video URL.

Individual video URLs copied from a YouTube playlist are also supported:

yt-transcribe "https://www.youtube.com/watch?v=VIDEO_ID&list=PLAYLIST_ID&index=4"

Keep the complete URL inside quotation marks because characters such as & have special meaning in the shell. The tool preserves the selected video, ignores the surrounding playlist context, and processes only that one video. It does not download the rest of the playlist.

By default, the finished files are easy to find in:

~/Downloads/YouTube Transcriber/

Homebrew automatically installs everything required:

  • the yt-transcribe command
  • Python
  • ffmpeg
  • yt-dlp
  • faster-whisper
  • all required Python dependencies

You do not need to install Python, pip, pipx, ffmpeg, yt-dlp, Whisper, faster-whisper, or a virtual environment manually. Those manual steps are only relevant if you intentionally use the source installation section.

Upgrade the installed formula:

brew update
brew upgrade youtube-transcriber

Uninstall the formula:

brew uninstall youtube-transcriber

Requirements

  • Apple Silicon Mac
  • macOS 14 Sonoma or newer
  • Internet connection
  • Homebrew

The first transcription may download the selected Whisper model. Later runs can reuse the model stored in the local cache.

Install from source

Source installation is intended for contributors and advanced users. It requires Python 3.10 or newer and ffmpeg:

git clone https://github.com/jn-root/youtube-transcriber.git
cd youtube-transcriber
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

The yt-transcribe command is available while the virtual environment is active.

To update an existing clone:

git pull
source .venv/bin/activate
python -m pip install --upgrade .

Basic usage

Save the default MP3 audio and create text transcripts:

yt-transcribe "https://www.youtube.com/watch?v=VIDEO_ID"

Process an individual video URL copied from a playlist:

yt-transcribe "https://www.youtube.com/watch?v=VIDEO_ID&list=PLAYLIST_ID&index=4"

The selected v video ID is preserved and processed. Playlist parameters such as list and index, along with extra watch parameters such as si, feature, pp, t, and start_radio, are ignored. The rest of the playlist is not downloaded. Keep URLs containing & inside quotation marks so the shell passes the complete URL to the command.

Choose a custom output directory:

yt-transcribe "https://www.youtube.com/watch?v=VIDEO_ID" --output-dir "./output"

Create transcripts without retaining an audio file:

yt-transcribe "https://youtu.be/VIDEO_ID" --mode transcript-only

Save audio without creating transcripts:

yt-transcribe "https://youtu.be/VIDEO_ID" --mode audio-only

Save WAV audio instead of MP3:

yt-transcribe "https://youtu.be/VIDEO_ID" --audio-format wav

Include segment timestamps and specify the spoken language:

yt-transcribe "https://youtu.be/VIDEO_ID" --timestamps --language en

Output files

The default output directory is ~/Downloads/YouTube Transcriber/. The Downloads folder is easy for first-time users to find. The directory and its subdirectories are created automatically.

For a video titled Example Video Title, the default both mode creates:

~/Downloads/YouTube Transcriber/
├── audio/
│   └── example-video-title.mp3
└── transcripts/
    ├── example-video-title.txt
    └── example-video-title.md

The outputs are:

  • audio/example-video-title.mp3: retained audio encoded as a 192 kbps MP3
  • transcripts/example-video-title.txt: transcript text only
  • transcripts/example-video-title.md: video title, source URL, generation time, and transcript text

With --audio-format wav, the retained audio is a mono 16 kHz WAV file instead. Transcript formats remain .txt and .md.

The title is normalized to ASCII where possible, converted to lowercase, stripped of unsafe filename characters, changed to hyphen-separated words, and limited to 100 characters. Audio and transcript files use the same base filename.

Existing output files are never silently overwritten. If an expected filename already exists, the command tries -2, -3, and later numeric suffixes until it finds an unused set.

After a successful transcription, the command prints the absolute path of every generated file. It also prints a command that opens the output folder in Finder:

open "$HOME/Downloads/YouTube Transcriber"

Use --output-dir to choose another location. A custom output directory keeps the same audio/ and transcripts/ structure and is created automatically.

Output modes

  • --mode both saves audio and creates .txt and .md transcripts. This is the default.
  • --mode audio-only saves audio and does not load or run faster-whisper.
  • --mode transcript-only creates .txt and .md transcripts without retaining a converted audio file.

All modes temporarily download the selected video's audio stream. The tool does not intentionally download and retain a video file.

Command options

URL                         YouTube video URL
-o, --output-dir DIRECTORY Output directory
--mode MODE                 audio-only, transcript-only, or both
--audio-format FORMAT       mp3 or wav
--model MODEL               faster-whisper model name or local path
--language CODE             Spoken language code, or automatic detection
--device DEVICE             cpu or cuda
--compute-type TYPE         faster-whisper compute type
--timestamps                Include segment timestamps
--version                   Show the installed version
-h, --help                  Show help

The default model is base, the default device is cpu, and the default compute type is int8.

Local processing and privacy

Speech transcription runs on the user's computer with faster-whisper. The project does not use a hosted transcription API. Normal operation does not require API keys or browser cookies. The application does not automatically read browser cookies or access browser profiles, and browser-cookie authentication is not enabled by default. YouTube may still block or challenge some requests.

The retained audio and transcript files remain in the selected output directory until the user removes them. The source audio download and the WAV used for transcription are created in the operating system's temporary directory. Python's temporary-directory manager removes them when the command exits normally or handles an error. An abrupt process termination can leave temporary files for the operating system to clean up.

The tool is not fully offline:

  • yt-dlp contacts YouTube to retrieve video information and audio.
  • On first use of a model, or when a different model is selected, faster-whisper can download model files from Hugging Face.
  • Later runs can reuse a model already present in the local model cache.

Output files can contain sensitive speech, source URLs, and timestamps. Review them before sharing and keep output directories out of source-control repositories.

Troubleshooting

zsh: command not found: brew

Homebrew is not installed, or the Homebrew installer's Next steps commands have not been run.

Install or rerun the official Homebrew installer:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

When it finishes, run the exact commands under Next steps in Terminal. Then verify the installation:

brew --version

ffmpeg is missing

If you installed this project with Homebrew, reinstall the formula:

brew reinstall jn-root/tap/youtube-transcriber

Source installations require ffmpeg to be installed separately.

zsh: command not found: yt-transcribe

Confirm that the Homebrew formula is installed:

brew info jn-root/tap/youtube-transcriber

If needed, reinstall it:

brew reinstall jn-root/tap/youtube-transcriber

For a source installation, activate the virtual environment created during installation with source .venv/bin/activate.

The first transcription is slow

faster-whisper downloads the selected model if it is not already cached. This can make the first run slower. The download size and transcription requirements depend on the model.

Transcription runs out of memory

Try a smaller model:

yt-transcribe "https://youtu.be/VIDEO_ID" --model tiny

YouTube asks me to sign in or confirm I am not a bot

YouTube may occasionally challenge automated requests. This is a YouTube access restriction, not a playlist-processing failure. The application presents a friendlier error when it detects this challenge.

Retry the command later and confirm that the video is public and available in your region. The application does not automatically read browser cookies or browser profiles, and browser-cookie authentication is not part of normal application behavior.

A video is private or unavailable

The tool does not bypass access controls. Private, members-only, age-restricted, region-restricted, removed, or otherwise inaccessible videos may fail. Use a public video that is available from your location.

Support for an individual video URL copied from a playlist does not change these access restrictions.

Limitations

  • Individual YouTube video URLs are supported, including an individual video URL copied from a playlist. Playlist context is ignored and only the selected video is processed. Playlist-only URLs and whole-playlist downloading are not supported.
  • Private, members-only, age-restricted, region-restricted, removed, or otherwise unavailable videos may fail.
  • Transcript accuracy depends on audio quality, language, model size, and available hardware.
  • Speaker identification, subtitle upload, automatic browser-cookie authentication, and hosted transcription are not supported.
  • Linux and Windows have not been verified.

Responsible use

Download or transcribe only content that you are permitted to access and use. Follow applicable laws, platform terms, licenses, and the rights of content creators.

License

YouTube Audio and Text Transcriber is available under the MIT License.