Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mr-sunset/youtube-rip/llms.txt

Use this file to discover all available pages before exploring further.

Most YouTube Rip failures come down to one of a handful of root causes — an outdated yt-dlp build, a missing Homebrew installation, or a transient YouTube API change. The accordions below cover every common failure mode with a specific fix for each one.
Start here for any download failure: run brew upgrade yt-dlp before anything else. YouTube changes its internal API frequently, and yt-dlp releases fixes within hours. Keeping yt-dlp up to date resolves the majority of download errors without any further debugging.
Cause: yt-dlp is either not installed, or Homebrew’s bin directory is not on the PATH that the script is using.Fix:
  1. Install yt-dlp via Homebrew if you haven’t already: 
    brew install yt-dlp
  2. Verify the installation path: 
    which yt-dlp
    The output should be one of:
    • /opt/homebrew/bin/yt-dlp — Apple Silicon (M-series) Mac
    • /usr/local/bin/yt-dlp — Intel Mac
The script already exports both paths at runtime (/opt/homebrew/bin and /usr/local/bin), so if which yt-dlp returns one of those locations the script should find it automatically.If yt-dlp still can’t be found after installation, run brew doctor to check for Homebrew configuration issues:
brew doctor
Follow any recommendations it prints before trying again.
Cause: YouTube rejected the download request. This most commonly happens when yt-dlp is outdated and tries to use a deprecated or blocked player client.The script already passes --extractor-args "youtube:player_client=default,-android_sdkless" to explicitly disable the android_sdkless client, which can cause 403 errors. If you are still seeing a 403, yt-dlp likely needs to be updated to a newer version that knows how to handle YouTube’s current player API.Fix:
  1. Update yt-dlp to the latest version: 
    brew upgrade yt-dlp
  2. Run the script again and check the output dialog.
If the 403 persists after upgrading, copy the full error text from the output dialog and search yt-dlp’s GitHub issues — there is usually an open issue tracking the current YouTube API change with a workaround or an in-progress fix.
Cause: A slow network connection, an unusually long video, or yt-dlp stalling during format selection can all cause the script to appear frozen.Because YouTube Rip is a GUI AppleScript with no streaming output, there is no progress indicator while the shell command runs. The script is not frozen — it is waiting for do shell script to return, which only happens once yt-dlp exits. For videos longer than 30 minutes, waiting several minutes is normal.What to do:
  • Wait at least 2–3 minutes for standard-length videos before assuming something is wrong.
  • For videos 1 hour or longer, consider running yt-dlp directly in Terminal where you can watch live progress output: 
    yt-dlp -x --audio-format mp3 -P "$HOME/Downloads" \
  --extractor-args "youtube:player_client=default,-android_sdkless" \
  "https://youtu.be/YOUR_VIDEO_ID"
  • If the script dialog never returns and Terminal yt-dlp also stalls, check your network connection and try again.
Cause: The .applescript file may have been corrupted during download, had its line endings altered by a text editor, or was opened in an application other than Script Editor.Fix:
  1. Re-download the script from the official repository: 
    https://github.com/mr-sunset/youtube-rip
  2. Open the freshly downloaded file in Script Editor (located at /Applications/Utilities/Script Editor.app). Do not open it in a plain text editor such as TextEdit, VS Code, or BBEdit before running — those applications may alter line endings or encoding in ways that confuse the AppleScript compiler.
  3. Click the Compile button (the hammer icon) in Script Editor to verify there are no syntax errors before clicking Run.
Cause: yt-dlp may have exited with an error (silently from the script’s perspective), or the file was saved with an unexpected name that makes it hard to spot.Fix:
  1. Re-read the Shell stdout dialog that appeared after the run. If it contains a line starting with ERROR:, the download did not complete — address that error first using the other entries in this guide.
  2. If the stdout dialog showed a normal download log, search ~/Downloads for recently modified files. In Finder:
    • Open ~/Downloads
    • Click the Date Modified column header to sort by newest first
    • Look for an .mp3 file at the top of the list
  3. You can also search from Terminal: 
    find ~/Downloads -name "*.mp3" -mmin -10
    This lists any MP3 files in Downloads that were modified in the last 10 minutes.
Keep in mind that yt-dlp names the output file after the video title, which can result in long filenames or filenames containing special characters. The file is definitely an .mp3 — searching by extension is the most reliable way to find it.
The source code includes the comment: “This may only work on M series Macs.” This note refers to the primary Homebrew path used by the script.On Apple Silicon (M-series) Macs, Homebrew installs to /opt/homebrew/bin. On Intel Macs, Homebrew installs to /usr/local/bin. The script exports both paths:
set envPath to "export PATH=\"/opt/homebrew/bin:/usr/local/bin:$PATH\"; "
This means the script should work on Intel Macs as long as yt-dlp was installed via Homebrew. To confirm:
which yt-dlp
On an Intel Mac, this should return /usr/local/bin/yt-dlp. If it returns a different path (for example a pyenv or pip-managed installation), the script will not find it, and you should reinstall yt-dlp via Homebrew:
brew install yt-dlp

Build docs developers (and LLMs) love

Get started for freeTalk to us