Youtube Downloader

YouTube Downloader

Download YouTube videos or extract audio. Files are named after the video title, saved to the user's preferred location, and remuxed to play correctly as video on iOS.

How This Skill Works

This skill runs yt-dlp + ffmpeg inside the Minis Linux sandbox (iSH). Two iSH-specific workarounds are required:

1. Manual DASH merge: yt-dlp's built-in video+audio merger crashes in iSH. For high-quality formats (1080p, 1440p), the script downloads video and audio separately using -k (keep video), lets the merger fail, then merges them with a direct ffmpeg call.

2. iOS container fix: YouTube's MP4 files use the mp42 brand, which iOS may treat as audio-only. The script remuxes to M4V (for H.264) or standard mp4 (for AV1/VP9) with +faststart so iOS Files plays them as video.

First Run — Onboarding

On the FIRST time this skill triggers, run onboarding before downloading anything.

Step 1: Check status

sh /var/minis/skills/youtube-downloader/scripts/yt-config.sh status

If onboarded: true, skip to Normal Operation. If onboarded: false (or config doesn't exist), continue onboarding.

Step 2: Install dependencies

If yt-dlp: no or ffmpeg: no in the status output, install them:

apk add yt-dlp ffmpeg py3-pip
pip install --upgrade --break-system-packages yt-dlp

The pip upgrade is essential — Alpine's yt-dlp package is stale and YouTube's player changes frequently. This takes ~30 seconds.

Step 3: Ask the user two questions

Present as a friendly numbered list. Wait for answers.

Question 1 — Quality preference:

What quality do you want by default?

1. 1080p video — Full HD, best balance of quality and size (default)
2. 1440p video — 2K, highest quality, large files (~300 MB per 10 min)
3. 720p video — HD, smaller file size
4. Audio only — best for music/podcasts, smallest file
5. Ask me every time — no default, I'll pick per video

Question 2 — Where to save:

Where should I save your downloads?

1. iOS Files app (Downloads folder) — appears in Files → Downloads
2. iOS Photos (YouTube Downloads album) — appears in Photos
3. Keep in Minis — stays in the app's attachments folder

Step 4: Set up Files mount (if user chose option 1)

Check if the Downloads mount already exists via the status command. If downloads_mount: yes, skip. If downloads_mount: no, tell the user:

To save videos to your Files app, I need you to mount your Downloads folder:

1. Tap this link: Mount External Folders
2. Tap "Add Mount"
3. Navigate to the folder you want (e.g., iCloud Drive → Downloads, or On My iPhone → Downloads)
4. Name it "Downloads"
5. Come back here and tell me when you're done

After the user confirms, re-run the status check to verify downloads_mount: yes.

Step 5: Save config

sh /var/minis/skills/youtube-downloader/scripts/yt-config.sh set quality "<chosen_quality>"
sh /var/minis/skills/youtube-downloader/scripts/yt-config.sh set save_mode "<chosen_save_mode>"
sh /var/minis/skills/youtube-downloader/scripts/yt-config.sh complete

• Quality: "1080p", "1440p", "720p", "360p", "audio", or "" (empty string for "ask every time")
• save_mode: "files", "photos", or "minis"

Step 6: Offer a test download

Tell the user setup is complete. Offer to download a short test video at 360p so they can verify the flow:

sh /var/minis/skills/youtube-downloader/scripts/yt-download.sh "https://www.youtube.com/watch?v=aqz-KE-bpKQ" 360p <save_mode>

Replace <save_mode> with whatever the user chose (files, photos, or minis). 360p is used for the test because it's the most reliable quality — higher quality works the same way once configured.

Confirm the file appeared where they expected. Then proceed with whatever they originally asked for.