Your Name
2e57634877
Both tools: yt-dlp calls via spawn (honor DRY_RUN; --dry-run prints the command and skips dep checks), -o/--output, --no-playlist, --cookies (with file check), clean ffmpeg/yt-dlp guards, POS_FLAGS for completion, full embedded metadata (--embed-metadata --embed-chapters --embed-thumbnail --no-overwrites; mp3 adds --convert-thumbnails jpg + artist-from-uploader parse-metadata). mp3 gains --by-artist (~/Music/<artist>/<title>.mp3). mp4: -f <id>/--best/--worst skip the prompt (mutual-exclusion validated), and the interactive picker now shows a curated [audio]/[video]/[combo] format table on stderr (stdout carries only the chosen id — ui_pick lesson), validates the id against the real -F output, and defaults empty input to best. Docs: howto/media.md rewritten.
3.4 KiB
How-To: pos media
Download audio and video from the web via yt-dlp. Tools: mp3, mp4.
| Tool | What it does |
|---|---|
pos media mp3 |
Download audio, convert to MP3 |
pos media mp4 |
Download video with smart/interactive format selection |
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.
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-artistleaves 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-odirectory).
Related
- Reference: DOC/POS.md → media