Skip to content

bitwize-music-studio/claude-ai-music-skills / skills/lyric-video

lyric-video

Unverified

Makes a lyric video for a track through Suno's MCP server - the album cover held under the track's approved take, with the words burned in as they are sung - and saves it beside the album's audio with the mastered audio under it. Rendering was free when measured. Use when the user asks for a lyric video, a video with the lyrics on screen, or a video of a song for YouTube.

Your Task

Input: $ARGUMENTS

Make a lyric video for one track: plan it, give Suno the picture, have Suno render the video, and save it beside the album's audio.

You never pick a take. The video is made for the track's approved take, and only for that one.


Lyric Video Skill

Suno's video-assemble holds a picture under a song and burns the words in as they are sung, lit word by word. This skill has it do that with the album's cover and the track's keeper.

Measured on songs of 52 to 97 seconds: rendering and waiting spent no credit of any kind, and each video was ready in under a minute. Downloading was free too for the two whose song was already unlocked. Suno's own description says stills and rendering are free. Check it every run all the same: Step 2 reads the balances and Step 7 reads them again.

Background, the answers each tool gives and what was measured: ${CLAUDE_PLUGIN_ROOT}/reference/suno/mcp-api-mapping.md § Visuals.

Step 1: Plan

Expected format: <album-name> <track> [--shape 16:9|1:1|9:16] [--asset <Suno image id>] [--suno-audio] [--replace]

If the album or the track is missing, show:

Usage: /lyric-video <album-name> <track> [--shape 16:9|1:1|9:16]

Example: /lyric-video sample-album 03

Call get_lyric_video_plan(album_slug, track_slug, shape), with asset_id as well when the user passed --asset: an album with no cover is only blocked without one. The shape is 16:9 unless the user names another.

ResultDo
found: false, or an errorReport it and stop
A blocking problemShow each one with its detail and stop. no_keeper: the user approves a take first. instrumental: there are no words to show. no_cover: the album needs a cover, or the user names an image already on Suno with --asset
no_masterSay the video will carry Suno's own audio, and carry on
video_existsAsk whether to replace the earlier video, unless the user passed --replace. No → stop
ffmpeg_missingSay the video will be saved as Suno makes it, and carry on

Step 2: Check the Suno Server

Find video-assemble, visuals-wait, visuals-download, audio-retrieve, audio-download and account-usage on a connected MCP server, and load their definitions. Without --asset, find visuals-upload-create and visuals-upload-complete too.

Not there → say so and stop. Either Suno's server is not connected (the setup command is in the reference doc), or this session started before Suno added the tools and needs a restart.

Call account-usage and keep the three balances: credits_remaining, download_credits_remaining and visuals_credits_remaining.

Step 3: The Song

  1. audio-retrieve(id: <song.clip_id>). Keep metadata.duration.

  2. Find out whether the song is locked, because Suno renders a video for a locked song but will not hand it over. Call audio-download(id: <song.clip_id>, format: "mp3") without confirm. Do not save what it returns, and spend nothing yet.

    AnswerDo
    status: "ok"The song is unlocked. Nothing was spent
    status: "requires_credit"The song is locked: unlocking it costs one download credit. Keep the balance (credits_remaining in the answer) and carry on. The question comes in Step 5, once nothing else can stop the video
    status: "processing"Call audio-download again, three times at most
    rate_limitedWait the retry_after_seconds it names, then call again
    Any other refusal (quota_exhausted, daily_limit_exceeded, no_permission, …)Report it and stop. Do not retry

    A keeper whose WAV was downloaded from Suno for a download credit is already unlocked. One exported through Suno Studio is not.

Step 4: The Picture

With --asset <id>, that image on Suno is the picture: go to Step 5.

Otherwise the picture is made from the album's cover and uploaded:

  1. prepare_lyric_video_still(album_slug, shape). It writes a JPEG of the video's shape with the whole cover in the middle. Keep still.path and still.bytes.

  2. visuals-upload-create(content_type: "image/jpeg", bytes: <still.bytes>).

    • 403 with reason upload_consent_required → Suno asks every account, once, to accept a notice before its first upload: that the user has the rights to what they upload. It is theirs to accept. Never accept it for them, and never look for a way around it. Tell them to start an image upload under Visuals on suno.com, accept the notice there, and run this again. Mention --asset for an image that is already on Suno. Stop.
    • Otherwise the answer holds the upload's asset id, an upload_url, upload_fields and expires_at.
  3. Send the file to upload_url as a multipart form, every upload_fields entry first and the file last as file:

    curl -sS -o /dev/null -w '%{http_code}' --form-string 'key=…' --form-string 'policy=…' … -F 'file=@<still.path>' '<upload_url>'
    

    Each field goes in with --form-string, which sends its value as it is; -F would read a value that starts with @ or < as a file to send. Only the file itself takes -F. The address and the fields are credentials for this one upload: do not repeat them in your reply. A 2xx code is success; anything else → report the code and stop.

  4. visuals-upload-complete(id: <the asset id>), then visuals-wait(ids: <that id>) until it is ready, six times at most. An upload that ends failed says why in error (moderated, invalid_file or processing_failed): report it and stop.

The upload steps follow Suno's tool descriptions. They were not measured: the test account had not accepted the notice.

Step 5: Assemble

  1. If the song is locked (Step 3), ask now. "The video can be made free, but Suno will only hand it over once the song is unlocked, which costs one download credit. You have N." On a yes, audio-download(id: <song.clip_id>, format: "mp3", confirm: true). On a no, stop before rendering anything.
  2. get_lyric_video_plan(album_slug, track_slug, shape, asset_id: <the picture's id>, duration_s: <metadata.duration>). Its request holds the arguments for video-assemble. A blocking request_invalid → show its detail and stop. A request that is null means the picture's id or the song's length did not arrive: stop and say which.
  3. Say what is about to happen in one line: "Suno will render a 16:9 lyric video of [Title] (3:26). It was free when measured and takes about a minute. It leaves a Sequence in your Suno library." No go-ahead is needed for a call that spends nothing.
  4. Call video-assemble with the keys of request and idempotency_key: "{album_slug}/{track_slug}/lyric-video/{UTC timestamp}". Add nothing else. Keep the id and the editor_url it answers with. Make the key once and keep it: every retry in this run uses the same one.
  5. visuals-wait(ids: <that id>). It returns after about 50 seconds whether or not the video is ready: call it again while status is processing, ten times at most, then give the user the id and the editor_url and stop. A job that answers unread was skipped by a rate limit: wait its retry_after_seconds and ask again. A job that ends failed → report it and stop.
What happenedDo
No response or a timeout from video-assembleRetry once with the same idempotency key, which finishes the same video instead of starting another
404 from a Visuals toolThe Suno sign-in does not include Visuals. Say so and stop
400: a clip is still being madeThe picture was not ready. Wait for it with visuals-wait, then call again with the same key

Step 6: Save

  1. visuals-download(id: <the video's asset_id>). It answers with a url; call it again while it answers processing, six times at most.

    A 403 with reason clip_not_unlocked means the song is still locked. The video is made and stays made: do not render it again. Unlock the song as Step 5 item 1 says, asking first, then call visuals-download once more. If it still refuses, give the user the video's suno_url and stop.

  2. save_lyric_video(album_slug, track_slug, link: <that url>, shape). Add master_audio: false when the user passed --suno-audio, and replace: true only when the user said to replace the earlier video.

    It fetches the file, checks that it is a whole video, and saves it under the album's lyric_videos/. When the track has a mastered file as long as the video, the master goes under the picture; the picture itself is copied untouched.

    saved: false → report its error and stop. One exception: when the error says the download stopped early, ask visuals-download for the link again and call save_lyric_video once more.

Step 7: Report

Call account-usage again and compare the three balances with Step 2.

LYRIC VIDEO — [NN] [Title]

  Saved    /path/to/lyric_videos/03-track-name-16x9.mp4  (1920x1080, 3:26, 41 MB)
  Audio    the master
  On Suno  https://suno.com/visual/ast_...
  Editor   https://suno.com/visual/cmp_...
  Spent    nothing — all three balances are unchanged
  • Audio: "the master", or "Suno's own audio" followed by audio_note when there is one.
  • Spent: if a balance moved, say which one and by how much. Never say "nothing" without having compared.
  • Editor is the editor_url from Step 5, where the user can open the cut on suno.com.

Tell the user once: watch it through before publishing. The words and their timing are Suno's reading of the take, not the track file's Lyrics Box. Every sung line was shown on the takes tested, but nothing here checks the picture.

Remember

  1. The keeper only. The video is made for the approved take. You never pick one.
  2. Free when measured, and checked every run. Read the balances before and after, and report any that moved.
  3. Suno's upload notice is the user's to accept. Never accept it for them.
  4. The words are the take's. The video shows what was sung, so a Lyrics Box changed since the take was made does not change it.
  5. An earlier video is kept unless the user says to replace it.
  6. Unlocking a song can cost a download credit. Ask before calling audio-download with confirm: true.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall