# yt-dlp Installation on ZimaOS/CasaOS

Installing yt-dlp (YouTube downloader) on ZimaOS has specific quirks because the standard installation methods fail.

## Problem

| Method | Why It Fails |
|--------|-------------|
| `pip install yt-dlp` | Python `pip` not available in system Python |
| Official install script (`install.sh`) | Tries `~/.local/bin` → `/DATA/.local` is root-owned |
| `apt install youtube-dl` | No root access, system package manager locked |

## Verified Method

### 1. Download pre-built binary directly

```bash
install_dir="/DATA/AppData/hermes/bin"

curl -sL -o /tmp/yt-dlp 'https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp'
```

Alternative if latest-redirect fails: query GitHub API for URL.

### 2. Install

```bash
cp /tmp/yt-dlp "$install_dir/yt-dlp"
chmod +x "$install_dir/yt-dlp"
```

### 3. Verify

```bash
/DATA/AppData/hermes/bin/yt-dlp --version
```

## Dependencies

- **ffmpeg**: Already present on most ZimaOS installations (used for audio extraction/conversion)
- **Python**: yt-dlp is standalone, but can also run as Python script if needed

## Usage Examples

```bash
# Download video (best quality)
/DATA/AppData/hermes/bin/yt-dlp "URL"

# Audio only (MP3)
/DATA/AppData/hermes/bin/yt-dlp -x --audio-format mp3 "URL"

# Best audio only
/DATA/AppData/hermes/bin/yt-dlp -f "bestaudio[ext=m4a]" -x "URL"

# Playlist
/DATA/AppData/hermes/bin/yt-dlp "PLAYLIST_URL"

# Metadata only
/DATA/AppData/hermes/bin/yt-dlp --write-info-json --skip-download "URL"
```

## Costs

€0 — Open source, no API key needed.

## When to Use

- Downloading YouTube videos for offline viewing
- Extracting audio from YouTube videos
- Downloading entire playlists
- Archiving content

## Integration with Agent

The agent can invoke yt-dlp via `terminal` tool or Python `subprocess`:

```python
import subprocess

result = subprocess.run(
    ["/DATA/AppData/hermes/bin/yt-dlp", "-x", "--audio-format", "mp3", url],
    capture_output=True, text=True, timeout=300
)
```