Linux_post_install/DOC/howto/media.md

How-To: pos media

Download audio and video from the web via yt-dlp, and sync your library to a USB stick. Tools: mp3, mp4, sync.

Tool	What it does
pos media mp3	Download audio, convert to MP3
pos media mp4	Download video with smart/interactive format selection
pos media sync	Incrementally copy ~/Music onto a USB stick (mp3/mp4)

Requires yt-dlp and ffmpeg (sudo apt install yt-dlp ffmpeg); the tools fail with a clean error message instead of a raw command not found if either is missing.

---

pos media mp3 — audio as MP3

pos media mp3 <url>

Extracts and converts the audio track to MP3 in ~/Music/. With --by-artist files land in ~/Music/<artist>/<title>.mp3 (falls back to the uploader name when there's no artist tag), so a library stays organized.

pos media mp3 https://youtube.com/watch?v=dQw4w9WgXcQ
pos media mp3 --by-artist https://youtu.be/dQw4w9WgXcQ

MP3s are encoded at best quality with title/artist/album/date/chapters embedded (--embed-metadata --embed-chapters, artist falls back to uploader) plus the cover art as a JPEG thumbnail. Existing files are never overwritten.

Flag	Meaning
-o, --output <dir>	Output directory (default ~/Music)
--by-artist	Organize as <dir>/<artist>/<title>.mp3
--no-playlist	Download only the single video, not the playlist
--cookies <file>	Netscape cookies.txt for age-gated content
--dry-run	Print the yt-dlp command without running it

Recipe: batch — loop over a list of URLs:

while read -r url; do pos media mp3 --by-artist "$url"; done < urls.txt

---

pos media mp4 — video with smart format choice

pos media mp4 <url>

Without a format flag, the available formats are shown as a short curated list (grouped [audio] / [video] / [combo], with the raw dump's clutter dropped) and you pick one — the id is validated before downloading. Entering nothing (or best) picks the best video+audio automatically.

Non-interactive (scripting-friendly):

Flag	Meaning
-f, --format <id>	Download that format id directly (no prompt)
--best	Best video + audio, no prompt
--worst	Lowest quality, no prompt
-o, --output <dir>	Output directory (default ~/Videos)
--no-playlist	Download only the single video
--cookies <file>	Netscape cookies.txt for age-gated content
--dry-run	Print the yt-dlp command without running it

pos media mp4 --best https://youtube.com/watch?v=dQw4w9WgXcQ
pos media mp4 -f 22 https://youtube.com/watch?v=dQw4w9WgXcQ

Videos merge to MP4 with metadata, chapters, subtitles (all languages) and the thumbnail embedded (--embed-metadata --embed-chapters --embed-subs --sub-langs all --embed-thumbnail); existing files are never overwritten.

Recipe: grab a 4K stream for later — --best already picks the best video+audio and merges them.

---

pos media sync — music onto a USB stick

pos media sync          # copy everything (mp3 + mp4) from ~/Music to the stick
pos media sync --mp3    # only the .mp3 files
pos media sync --mp4    # only the .mp4 files

Detects connected USB storage exactly like pos system backup (same shared lib/usb-lib.sh): a plugged-in but unmounted stick is offered a mount first (/media/<label>, world-writable, mirrors usb-automount), multiple sticks are listed for you to pick, and if nothing is plugged in it re-scans after you press Enter. Files are mirrored into <usb>/Music/ (change with MEDIA_SYNC_DEST) preserving the artist/album tree.

Sync semantics — add/update only, never delete. Files missing on the stick are copied; files whose size or mtime changed are overwritten; everything identical is skipped. Files on the stick that are no longer in the source are left alone — a playback stick can never lose files to a mirror mistake. Copies keep the source timestamps (cp --preserve=timestamps), so a re-run is a no-op. Preview before copying with --dry-run:

pos media sync --mp4 --dry-run   # shows "would copy" list + counts, copies nothing

The source folder may be a symlink to a library elsewhere (~/Music -> /mnt/data/music) — it is followed, the artist/album tree is mirrored under the symlink's target.

Flag	Meaning
--mp3	Sync only *.mp3 (neither flag = both)
--mp4	Sync only *.mp4 (neither flag = both)
--source <dir>	Source folder (default ~/Music)
--dry-run	Preview what would be copied, copy nothing

When it finishes it announces the result via lib/notify.sh (Music sync completed: N added, M updated → <usb>/Music).

Recipes:

pos media sync                    # keep the car stick up to date (both formats)
pos media sync --mp3 --dry-run    # check what a new batch will bring first
pos media sync --source /data/Music   # sync a library that lives elsewhere

Config (all in ~/.config/linux_post_install/system.env or exported): MEDIA_SYNC_SOURCE (default $HOME/Music), MEDIA_SYNC_DEST (default Music), plus the shared USB_MOUNT_BASE / USB_BYID seams.

---

Troubleshooting

• Format list is empty / download fails → the site or age-gate requires cookies; pass --cookies ~/cookies.txt (export it from your browser), or update yt-dlp (sudo apt upgrade yt-dlp).
• Error about a missing postprocessor → sudo apt install ffmpeg.
• --by-artist leaves files loose → the source has no artist/uploader tag; it falls back to the uploader name in the artist slot.
• Very large downloads: ensure free space; files land in ~/Music/~/Videos (or your -o directory).

---

Related

• Reference: DOC/POS.md → media