Skip to content

Media Grab ​

A thin skill wrapped around yt-dlp and ffmpeg for pulling audio and video off the web, tagging what lands, and turning a scattered list of track names into real files. It exists because picking the right yt-dlp flags by hand is fiddly and repetitive – the skill's whole value is choosing those flags, fuzzy-matching names to search results, and not hammering the user with confirmation prompts they don't need. It never invents metadata or pretends a download happened; a failed grab shows the real yt-dlp error rather than a vague excuse.

It needs yt-dlp and ffmpeg on PATH and does not ship either. The skill's own first step is checking for them before doing anything else, and it is not for streaming or playing music – that is the spotify connector's job, this one only ever writes files to disk.

In Practice ​

Every request resolves to one of three modes depending on what you hand it, and the fuzzy-match mode always stops for a yes before it writes anything.

Check the tools first. Before anything else the skill confirms both binaries exist on the box the session is running on:

yt-dlp --version
ffmpeg -version

No yt-dlp and it stops dead and points at winget install yt-dlp.yt-dlp. No ffmpeg and it warns that extraction, conversion, and cover-art embedding all die – listing candidates still works, but it won't try to rip.

Grab a url. One link, audio-only by default, mp3 at 320k with metadata and cover art embedded:

yt-dlp -x --audio-format mp3 --audio-quality 0 --embed-metadata --embed-thumbnail -P "downloads" -o "%(artist,uploader)s - %(title)s.%(ext)s" "URL"

For more than about two urls they go into a batch file instead of a shell loop, so it survives both nushell and cmd:

yt-dlp -x --audio-format mp3 --audio-quality 0 --embed-metadata --embed-thumbnail -P "downloads" -o "%(artist,uploader)s - %(title)s.%(ext)s" --batch-file links.txt

Asking for video instead drops -x --audio-format ... --audio-quality 0 and adds -f "bv*+ba/b".

Hand it names instead of urls. This is the search-and-match job – a scattered list of artist - title lines with no links. The skill does not download the top hit blind. It first lists candidates without downloading, one search per line in a batch file, prefixed to pick the engine (ytsearch5:artist - title or scsearch5:artist - title, soundcloud favoured for underground or bootleg stuff):

yt-dlp --skip-download --no-playlist --print "%(title)s | %(uploader)s | %(duration_string)s | %(webpage_url)s" --batch-file queries.txt

It then fuzzy-matches each wanted track against its candidates by reasoning over the text – artist and title, ignoring case, punctuation, and noise like "(official audio)" or "[prod. x]", and watching for a 10-minute mix or a 30-second snippet standing in for the real track. The matches come back as a wanted-to-picked table, anything it couldn't confidently match flagged as no good match, and it always shows the final list and waits for a yes before writing the chosen urls to links.txt and running mode 1.

Fix tags on files you already have. No re-encode, -c copy just rewrites the container:

ffmpeg -i "in.mp3" -metadata artist="X" -metadata title="Y" -metadata album="Z" -c copy "out.mp3"

A whole folder reaches for music-tag (pip install music-tag) rather than a fragile hand-rolled loop, and the skill only writes that python pass if the user actually wants a batch retag.

An example outcome. A soundcloud grab lands with the artist jammed into the title, exactly the mush the skill expects from that source – the report says so and offers a mode-3 cleanup pass rather than shipping bad tags silently.

Defaults ​

Unless told otherwise, every grab makes the same choices:

SettingDefault
KindAudio only, not video
Formatmp3 @ 320k (m4a or opus on request)
MetadataEmbedded, plus cover art, on every grab
Output dir./downloads/, created if missing
Filenameartist - title.ext, falling back to uploader - title when there is no artist tag

Edge Cases ​

  • Soundcloud metadata is mush – artist often lands in uploader or gets jammed into the title, so a soundcloud grab gets eyeballed and offered a mode-3 cleanup pass.
  • A playlist url when only one track was wanted gets --no-playlist; the whole set gets --yes-playlist; ambiguous cases get asked.
  • Geo-blocked, private, or removed videos surface the real error rather than retrying forever, with a suggestion to try --cookies-from-browser or a different source.
  • Duplicate tracks in a wanted list collapse to one before the search runs, so nothing gets grabbed twice.
  • Big batches get slowed on purpose – --sleep-requests 1 and --retries 3 go on so a long list doesn't get throttled or banned.
  • Filename clashes are silent by design – yt-dlp won't overwrite, so a re-grab of something already on disk looks like it did nothing.
  • Youtube auth (age-restricted or "sign in to confirm you're not a bot") needs --cookies-from-browser chrome (or firefox, edge, brave), and cookie auth itself needs deno installed – without it, yt-dlp throws "n challenge solving failed" even with the cookie flag on.

Key Files ​

SKILL.md ​

The procedure – the prereq check, the defaults, the three modes with their exact yt-dlp and ffmpeg invocations, the edge-case list, and the report format. It fixes the voice too: never invent metadata, never paste raw yt-dlp spam unless something broke, and never download a fuzzy-matched result without a confirmation.

USAGE.md ​

The thin end-user reference – no slash command, since this fires on how the request is phrased ("download this url", "find n rip these", "fix the tags on these"), plus the same gotcha list distilled to plain warnings, and a note that it reads no config file at all – every default is overridable just by saying so in the ask.

Connects to ​

  • A sibling under the skills bucket alongside Find-todos and Prompt-engineer – all three install as loose, single-job skills with nothing shared between them.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/skills/media-grab/USAGE.md – that one is the thin phrasing and gotcha reference, this page is the fuller depth of the same module.
  • Distinct from the spotify connector, which handles streaming and playback – media-grab only ever writes files to disk, it never plays anything.