For AI agents

muvid ships artifacts for coding agents alongside its code. This page lists them, says where each lives in the repository, and points at the machine-readable copies of this documentation.

Skills

Skills are folders holding a SKILL.md (the Agent Skills format): a description that tells an agent when to use it and a body with the procedure. Install one into your agent with gh skill (any host: --agent claude-code, copilot, cursor, codex, gemini), or use the copy bundled in the wheel.

muvid-lyric-video

Make a lyric video — a typographic music video where the words appear in time with the singing — from a song, using muvid. Use when the user has an audio file and wants the lyrics animated, a karaoke video, kinetic typography, a “words on screen” music video, or wants a poem/lyric laid out in a shape that fills in as it is sung. Covers CONCRETE POETRY and CALLIGRAMS — a poem whose shape on the page is the point (Apollinaire’s “Il pleut”, shaped text, word art, ASCII-art-style layouts) — via the calligram and shape_fill archetypes. Also use to inspect or hand-edit an existing treatment, to choose between treatment options, or when a lyric video came out badly and you need to work out why (usually: the word timings were interpolated rather than measured). Triggers on “lyric video”, “karaoke video”, “animate these lyrics”, “words in time with the music”, “kinetic typography”, “put the lyrics on screen”, “calligram”, “concrete poem”, “concrete poetry”, “shaped text”, “word art”, “make a video of this poem”. If the user has a poem but NO audio, muvid cannot make the song — generate it first with arioso (see “You need a song first” below), then come back here.

gh skill install thorwhalen/muvid muvid-lyric-video --agent claude-code

Source: muvid/data/skills/muvid-lyric-video (bundled with the pip package).

muvid-montage

Cut a person’s own videos and photos to a song — the “memories” kind of music video, where the footage does NOT contain the song (a day out, a trip, a party filmed in clips, a folder of photos) and the audio is the song itself. Use when someone has a song plus footage and photos and wants them “put to music”, “cut to the beat”, “made into a memories video”, a slideshow to music, a montage, a recap; when a music video came out mostly black or oddly placed because the clips have no song in their sound; or when deciding whether a clip should be synced to the song or cut to the music. Covers the studio flow, the Python and MCP calls, how each clip’s role is decided (and overridden), photos with Ken Burns moves, the pace knob, how the picture is aligned to the beat, and the research behind it (methods, libraries and licences, apps and market, UX).

gh skill install thorwhalen/muvid muvid-montage --agent claude-code

Source: muvid/data/skills/muvid-montage (bundled with the pip package).

muvid

Use when the user wants to make a music video from a song. Triggers on “make a music video”, “turn this song into a video”, “/muvid”, or any work inside a muvid project folder (look for project.json with muvid schema_version). Drives muvid’s NARRATIVE, shot-by-shot pipeline: transcribing the lyrics off the audio, aligning them, casting characters, establishing environments, writing the script, rendering shots. Also the router to muvid’s one-command surfaces — song in, video out, no project folder: lyric video, karaoke, kinetic typography, concrete poem, CALLIGRAM, audio visualizer, and assembling N phone recordings of one gig. If the user has no audio file, muvid cannot make one — see “muvid needs a song” below.

Source: .claude/skills/muvid.

muvid-choose-footage-segments

Use when choosing WHICH uploaded footage clip to show over each span of a fixed song in muvid’s music_video genre — the scoring + selection layer on top of audio alignment. Triggers on “which clip should be on-air”, “score footage segments”, “auto-choose footage”, “pick the best take”, “footage selection strategy”, “multichannel editor view”, “lip-sync score”, “motion-to-beat / dance-match score”, or building the auto composer / human-editor timeline for aligned footage. ALSO covers what happens to the pixels once a clip is chosen — the per-cut crop window and the look seam onto the looks package: “punch in”, “in-shot zoom”, “push-in”, “Ken Burns on footage”, “colour grade a cut”, “apply a LUT”, “stylize the edit”. The concrete per-metric scoring recipes live in muvid-score-footage; this skill owns the score MENU, the song-time data model, the two-consumer principle, the selection strategy, and the crop/look spatial half.

Source: .claude/skills/muvid-choose-footage-segments.

muvid-score-footage

Concrete recipes for computing per-clip score curves for muvid’s music_video footage selection — the lip-sync score, the motion-to-beat / dance-match score, and the cheap CPU quality tier — each resolved onto the shared song-time grid. Use when IMPLEMENTING a footage score. Triggers on “compute lip-sync score”, “SyncNet / LSE-C”, “motion beat alignment / BAS”, “optical flow motion envelope”, “sharpness / blur / shake / exposure score”, “face framing score”, “beat grid on the master”. The overall menu + selection + data model is muvid-choose-footage-segments.

Source: .claude/skills/muvid-score-footage.

muvid-visualize

Turn a song (+ optional cover) into a video with muvid.visualize — the lightweight, ffmpeg-only half of muvid: a still cover, a Ken Burns pan, or an audio-reactive visualizer (cqt/spectrum/waves/bars/scope) on a 16:9 canvas, loudness-normalized, plus a matching thumbnail. Use when the user wants to render an audio-visualizer or cover video from audio (no AI, no upload), pick or tune a visual, add a custom visualizer, or verify a rendered video. For publishing the result to YouTube, see yb’s music2video skill (it ships at yb/data/skills/music2video/, so it may not appear in an enabled-skill list).

Source: .claude/skills/muvid-visualize.

The bundled skills are also on disk after pip install muvid, under the package’s data/skills/ directory; link them into an agent without network access with skill link-skills <that directory>.

Instruction files

Files agents read before working in this repository.

Machine-readable documentation

This site publishes the same documentation in forms that fit an agent’s context window:

  • llms.txt: an index of every page with a one-line description (llms.txt format)

  • muvid.md: the whole documentation as one Markdown file

  • <page>.html.md: a rendered Markdown twin of every page, advertised from each page’s <head> with <link rel="alternate" type="text/markdown">

  • objects.inv: the Sphinx inventory: a symbol-to-URL index (sphobjinv convert plain objects.inv -)