CLAUDE.md@plugins/media-tools git:20260630.9028055A

Immutable. This exact content never changes and is served at /api/v1/blob/87a3d6b0ebe80910.

# media-tools

> YouTube audio download, iOS device media transfer, and image conversion + photo-share workflows.

**Hub**: [Root CLAUDE.md](../../CLAUDE.md) | **Sibling**: [plugins/CLAUDE.md](../../plugins/CLAUDE.md)

**Skills**: [youtube-to-bookplayer](./skills/youtube-to-bookplayer/SKILL.md) — YouTube audio → BookPlayer on iPhone · [heic-to-jpeg-bundle](./skills/heic-to-jpeg-bundle/SKILL.md) — HEIC → JPEG gallery + password ZIP (sips) · [photo-gallery-delivery](./skills/photo-gallery-delivery/SKILL.md) — end-to-end deliver-a-photo-set playbook.

---

## Skills

- [youtube-to-bookplayer](./skills/youtube-to-bookplayer/SKILL.md)
- [heic-to-jpeg-bundle](./skills/heic-to-jpeg-bundle/SKILL.md) — convert HEIC → JPEG and package a gallery + size-capped, optionally password-protected ZIP (macOS `sips`/`zip`, zero install)
- [photo-gallery-delivery](./skills/photo-gallery-delivery/SKILL.md) — orchestrator: pull a cloud album → convert/bundle → host unlisted → share via a gist gateway (ties together `amazon-photos-album-download`, `heic-to-jpeg-bundle`, `cloudflare-workers-publish`)

## Dependencies

All tools are installed via Homebrew or pip/uvx. The skill runs preflight checks and fails fast with install commands if anything is missing.

| Tool              | Purpose                                            | Install                                                           |
| ----------------- | -------------------------------------------------- | ----------------------------------------------------------------- |
| `yt-dlp`          | YouTube audio extraction                           | `brew install yt-dlp`                                             |
| `ffmpeg`          | Audio format conversion (auto-invoked by yt-dlp)   | `brew install ffmpeg`                                             |
| `exiftool`        | M4A metadata tagging (title, artist, album)        | `brew install exiftool`                                           |
| `pymobiledevice3` | iOS device communication via USB (HouseArrest API) | `uvx --python 3.14 --from pymobiledevice3 pymobiledevice3 --help` |

## Critical: VendDocuments vs VendContainer

**BookPlayer uses VendDocuments mode**, not VendContainer.

- The CLI command `pymobiledevice3 apps push` uses VendContainer mode internally and **fails silently** on BookPlayer
- The **Python API** with `documents_only=True` uses VendDocuments mode and **works correctly**
- This is the single most important implementation detail in this plugin — see the skill's Phase 4 for the correct Python approach

## Conventions

- **Python**: 3.14 only, via `uvx --python 3.14`
- **Temp files**: `mktemp -d` for working directories, cleaned up after success
- **Device selection**: `create_using_usbmux()` auto-selects first connected device
- **No hardcoded paths**: Use `$HOME`, `command -v`, auto-detection throughout