---
name: download-video
description: Download a video or media post from a user-provided URL to the local computer using yt-dlp. Use when the user invokes $download-video or asks only to download media from TikTok, YouTube, Instagram, Facebook, X/Twitter, Vimeo, or another yt-dlp-supported site. Do not analyze, transcribe, upload, or archive the media unless explicitly requested.
---

# Download Video

Download the requested media locally and return the exact saved path.

## Workflow

1. Require a direct post or video URL. If none is present, ask for it.
2. Default the destination to `~/Downloads`. Honor a user-specified local folder instead.
3. Run `scripts/download-video.sh URL [OUTPUT_DIR]`.
4. If the first attempt reports login, age, bot, or authentication restrictions, retry with `--cookies-from-browser` through the script's `DOWNLOAD_VIDEO_BROWSER` environment variable. Prefer `chrome`, then `arc`, then `safari`, based on what is installed and logged in. Do not use Playwright.
5. For a single post, never download a playlist or adjacent posts. Download a playlist only when the user explicitly requests it.
6. Report the final file path, title, and basic media properties when available. Do not run content analysis.

## Rules

- Use the best available video and audio and merge to MP4 when needed.
- Preserve meaningful metadata and subtitles when available without creating unnecessary sidecar files.
- Use filesystem-safe, readable filenames; include the media ID to avoid collisions.
- Do not overwrite an existing completed download. Let yt-dlp reuse or skip it.
- Do not download DRM-protected media or bypass access controls.
- Do not expose cookies, signatures, tokens, or other credentials in output.
- Treat the user's provided URL and destination as the authorized scope.

## Script

```bash
scripts/download-video.sh "https://example.com/video"
scripts/download-video.sh "https://example.com/video" "/path/to/folder"
DOWNLOAD_VIDEO_BROWSER=chrome scripts/download-video.sh "https://example.com/video"
```

The script prints a final `SAVED_PATH=` line for every downloaded or already-existing media file.