bitwize-music-studio/claude-ai-music-skills / skills/import-audio
import-audio
VerifiedMoves audio files to the correct album location with proper path structure, or pulls an approved take's WAV and stems straight from Suno. Use when the user has downloaded WAV files from Suno or other sources that need to be organized, or wants to import the keeper, or its instrumental version, after approving a take.
Your Task
Input: $ARGUMENTS
Import audio to the correct album location based on config — from a local file, or with --from-suno straight from Suno through its MCP server.
Import Audio Skill
You put audio in the correct location in the user's audio directory. Two forms:
- A file on disk —
<file-path> <album-name> [track-slug]: Steps 1–5 below. - Straight from Suno —
--from-suno <album-name> <track> [--stems | --version instrumental] [--browser <app>]: skip to Importing From Suno.
Step 1: Parse Arguments
Expected format: <file-path> <album-name> [track-slug]
The track-slug is optional — only needed for stems zip imports when the track can't be inferred from the filename.
Examples:
~/Downloads/track.wav sample-album~/Downloads/03-t-day-beach.wav sample-album~/Downloads/stems.zip sample-album 01-first-taste
If arguments are missing, ask:
Usage: /import-audio <file-path> <album-name> [track-slug]
Examples:
/import-audio ~/Downloads/track.wav sample-album
/import-audio ~/Downloads/stems.zip sample-album 01-first-taste
Step 2: Resolve Audio Path via MCP
- Call
resolve_path("audio", album_slug)— returns the full audio directory path - The resolved path uses the mirrored structure:
{audio_root}/artists/{artist}/albums/{genre}/{album}/
Example result: ~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/
CRITICAL: Always use resolve_path — never construct paths manually.
Step 3: Detect File Type
Check the file extension and whether it's a stems zip:
| File Type | Action |
|---|---|
.wav, .mp3, .flac, .ogg, .m4a | Move to album audio dir (Step 4) |
.zip (stems) | Extract to per-track stems subfolder (Step 4b) |
How to identify a stems zip: The user will say "stems" or the zip contains files like 0 Lead Vocals.wav, 1 Backing Vocals.wav, etc.
Step 4: Create Directory and Move File
mkdir -p {resolved_path}
mv "{source_file}" "{resolved_path}/{filename}"
Step 4b: Import Stems Zip
Stems must go into per-track subfolders to prevent filename collisions (every track has 0 Lead Vocals.wav, etc.):
{resolved_path}/
01-first-taste.wav
02-sugar-high.wav
stems/
01-first-taste/
0 Lead Vocals.wav
1 Backing Vocals.wav
2 Drums.wav
...
02-sugar-high/
0 Lead Vocals.wav
1 Backing Vocals.wav
...
Workflow:
- Determine the track slug from one of:
- The zip filename if it matches a track pattern (e.g.,
01-first-taste-stems.zip→01-first-taste) - The user specifying which track (e.g.,
/import-audio stems.zip sample-album 01-first-taste) - If neither: Ask the user which track the stems belong to
- The zip filename if it matches a track pattern (e.g.,
- Extract into the per-track subfolder:
mkdir -p {resolved_path}/stems/{track-slug} unzip "{source_file}" -d "{resolved_path}/stems/{track-slug}" - Update track metadata: Call
update_track_field(album_slug, track_slug, "stems", "Yes")
Argument format for stems: <zip-path> <album-name> [track-slug]
Step 5: Confirm
Report:
Moved: {source_file}
To: {resolved_path}/{filename}
For stems:
Extracted stems: {source_file}
To: {resolved_path}/stems/{track-slug}/
Files: {count} stem files extracted
Updated: {track-slug} stems → Yes
Importing From Suno (--from-suno)
Pulls a track's approved take from Suno through the Suno MCP server: the WAV, and with --stems the 12 stems, with no browser and no Downloads folder. Once the account's download credits run out, a Premier account can take the WAV from Suno Studio in the browser instead (step C2).
Costs, limits and the tool notes are in ${CLAUDE_PLUGIN_ROOT}/reference/suno/mcp-api-mapping.md. In short: the first download of a song uses one Suno download credit; every later download of it, in any format, and of its stems, is free. A take that was played in the terminal with /bitwize-music:listen has already used its credit.
A. Find the keeper
Call get_suno_import_plan(album_slug, track_slug).
problems code | Meaning | Do |
|---|---|---|
| (none) | clip_id is the keeper | Continue |
no_keeper | No take is approved yet | Ask the user to pick one first (/bitwize-music:listen), then stop |
keeper_ambiguous | Several takes are marked ✓ and no Suno Link is set | Ask which one, set the Suno Link, then call the plan again |
legacy_link | The Suno Link is a share link from before MCP generation | Explain that it carries no clip id; the file has to be downloaded on suno.com and imported with the file form of this skill. Stop |
If wav.existing is set, a file is already imported for this track. Say which file and ask before replacing it.
--version instrumental imports the track's instrumental version instead of its keeper (/bitwize-music:edit-take <album> <track> instrumental makes one). Call get_suno_import_plan(album_slug, track_slug, version: "instrumental"): clip_id is the version row marked ✓ and wav.path is versions/<track>-instrumental.wav, a folder the mastering tools never read. no_version_takes → none has been made; no_version_keeper → ask the user to mark the one to keep; version_keeper_ambiguous → ask which. Then steps B, C and E; a version has no stems, so skip D. To release an instrumental, give it a track of its own.
B. Check the Suno server
Run § Preflight in the reference doc. If the server is not connected, give the setup command and stop — the file form of this skill still works for a manual download.
Keep two values from account-usage: the plan (suno_account.plan.name) and download_credits_remaining. With no download credits left, go straight to step C2.
C. Download the WAV
-
Call
audio-download(id: <clip_id>, format: "wav")withoutconfirm.Answer Do status: "ok"Free — save it (step 2) status: "requires_credit"Say it uses one download credit and how many are left ( credits_remainingin the answer), and ask. On a Premier plan the answers are yes (spend the credit), studio (download it in Suno Studio instead: step C2, from its step 3) or no. On any other plan, ask only yes or no, and don't mention Studio. On yes, call again withconfirm: truestatus: "processing"Call audio-downloadagainrate_limitedWait retry_after_seconds, then call againquota_exhausted(no download credits left)Step C2 Any other refusal Report what Suno said and stop -
Save the link to
wav.path, exactly as the plan gave it:mkdir -p "$(dirname "{wav.path}")" \ && curl -fsSL --max-time 600 -o "{wav.path}.part" "{url}" \ && mv "{wav.path}.part" "{wav.path}"Quote the URL — it contains
&. Links last an hour. Ifcurlfails, remove the.partfile and report the error. -
Call
get_suno_import_planagain and check thatwav.existingis now the new file.
C2. Suno Studio instead (Premier)
On a Premier plan the WAV can come from Suno Studio, in a real browser, instead of a download credit: when the user answers studio to the credit question in step C, and when no download credits are left. Suno's downloads FAQ says work downloads from Studio "without limitation", and one measured download spent no credit. That is Suno's word and one test, not a guarantee: say so. Spending the credit stays the default answer.
-
Check the plan. Studio comes with Premier only. If the plan isn't a Premier plan, say that Studio needs Premier, when the downloads reset (
renews_onfromaccount-usage), and that more downloads can be bought on suno.com. Stop. -
Offer it when the credits have run out (after studio at the credit question, go straight to step 3): "You're out of Suno downloads. I can open the keeper in Suno Studio in your browser, and you download the WAV there. Suno says Studio downloads aren't limited." Stop unless the answer is yes.
-
Call
audio-retrieve(id: <clip_id>)and keeptitleandmetadata.duration. It is free. -
Call
open_in_studio(album_slug, track_slug, plan: <the plan name>), addingbrowser: <app>when the user gave--browser <app>(an app name or a path to one), andversionas in step A. Pass on itsnote, if any. Ifbrowsercomes back null, give the userurlto open by hand. A refusal names the reason; report it and stop. -
Tell the user
next: in Studio's editor, select the song's whole waveform, then click Download .WAV. -
Call
find_studio_download(since: <opened_at>, title: <title>, expected_seconds: <duration>, wait_seconds: 120).statusDo found,problemsemptyShow name, its length beside the song's, and its format. Ask before importing itfoundwithproblemsSay what's wrong, usually a selection that missed part of the song. Ask them to download it again, then call again severalList the candidatesand ask which onenot_foundName anything still downloading. Ask them to say when the download has finished, then call again withwait_seconds: 30 -
On yes, copy the file to
wav.pathfrom step A. The audio folder may be a network share, so copy, check, then remove:mkdir -p "$(dirname "{wav.path}")" \ && cp "{file}" "{wav.path}.part" \ && mv "{wav.path}.part" "{wav.path}" \ && cmp -s "{file}" "{wav.path}" \ && rm "{file}"If a step fails, leave the download where it is and report the error.
-
Carry on with step C.3. Skip
--stems: a Studio download doesn't count as the song's download, so its stems wait until a download credit is free (one credit then covers the song and every stem). Studio's multitrack export names its files its own way, not as the mix tools expect.
D. Stems (--stems only)
- State the price and ask. A 12-part split costs 50 Suno song credits. Show the balance from
account-usage. Ifstems.existsis true, also say the stems folder already exists and will be overwritten. Stop unless the answer is yes. - Call
audio-stems-create(id: <clip_id>, mode: "twelve", idempotency_key: "{album_slug}/{track_slug}/stems/{UTC timestamp}"). Keep theidin the answer (stemgrp_...). - Call
audio-stems-retrieve(id: <clip_id>, group_id: <that id>)about every 20 seconds untilstatusis no longerpending— usually one to two minutes.partialmeans some stems failed: say which, and carry on with the rest. - The split returns two takes of all 12 parts. Use the stems with
take: 1, and say that take 2 exists. Never mix the two takes — they are separate renderings and do not sum together. - For each take-1 stem, in the order returned, about two seconds apart:
audio-download(id: <the stem's audio_id>, format: "wav"). It answersokonce the song itself has been downloaded (step C did that). Handleprocessingandrate_limitedas in step C. If it answersrequires_credit, ask once — that one credit covers the song and every stem.- Save the link to
stems.files[<the stem's name>], the same way as the WAV. The plan maps Suno's part names (vocals,backing_vocals,drums, ...fx) to the file names the mix tools expect.
- If the plan has a
workspace, file the stems in it so they do not pile up in My Songs:workspaces-update-clips(id: <workspace.id>, add: [every stem's audio_id, both takes])— 24 ids, under that tool's limit of 50. Checkskipped. Filing is free. - Call
update_track_field(album_slug, track_slug, "stems", "Yes").
Import all 12 files, including parts the song does not have: Suno returns those as near-silent stems, and /bitwize-music:mix-engineer skips them on its own.
Without a workspace the split leaves 24 stem songs loose in the user's Suno library. Mention it once.
E. Confirm
Imported from Suno: [NN] [Title]
WAV: {wav.path}
Stems: {stems.dir} (12 files, take 1) — 24 stem songs filed in workspace "{workspace.name}"
Spent: 1 download credit, 50 song credits
Next: /bitwize-music:mix-engineer [album]
Leave out the lines that do not apply. After step C2, the Spent line reads Spent: no download credit (downloaded in Suno Studio).
Error Handling
Source file doesn't exist:
Error: File not found: {source_file}
Config file missing:
Error: Config not found at ~/.bitwize-music/config.yaml
Run /configure to set up.
File already exists at destination:
Warning: File already exists at destination.
Overwrite? (The original was not moved)
MP3 Files
Suno allows downloading in both WAV and MP3 formats (WAV on Pro/Premier, web only). Always prefer WAV for mastering quality.
Downloads are metered since 2026-09-03. Free accounts get 7 lifetime trial downloads (personal use only — never releasable); Pro 20 a month; Premier 60 a month; the count resets on the billing date and does not roll over. One song is one download whatever the format, and its stems are included — download the WAV first, then pull stems later at no extra cost; re-downloading the same song is free. Premier accounts can also download from Suno Studio: Suno's downloads FAQ says Studio work downloads "without limitation", and one measured download spent no credit and arrived as a 16-bit, 48 kHz stereo WAV, the same format as a WAV from audio-download. Step C2 uses it once the credits run out. Commercial rights attach only to a permitted download made on a paid plan.
If the user provides an MP3 file:
- Accept the MP3 and import it normally (same path logic)
- Warn the user:
Note: This is an MP3 file. For best mastering results, download the WAV
version from Suno instead. MP3 compression removes audio data that can't
be recovered during mastering.
If WAV isn't available, this MP3 will work but mastering quality may be limited.
- Import the file to the same destination path as WAV files
Supported formats: WAV (preferred), MP3, FLAC, OGG, M4A
Examples
/import-audio ~/Downloads/03-t-day-beach.wav sample-album
Config has:
paths:
audio_root: ~/bitwize-music/audio
artist:
name: bitwize
Result:
Moved: ~/Downloads/03-t-day-beach.wav
To: ~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/03-t-day-beach.wav
Import from Suno example
/import-audio --from-suno sample-album 03 --stems
Result:
Imported from Suno: 03 T-Day Beach
WAV: ~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/03-t-day-beach.wav
Stems: ~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/stems/03-t-day-beach/ (12 files, take 1)
Spent: 50 song credits
Next: /bitwize-music:mix-engineer sample-album
Stems import example
/import-audio ~/Downloads/stems.zip sample-album 01-first-taste
Result:
Extracted stems: ~/Downloads/stems.zip
To: ~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/stems/01-first-taste/
Files: 5 stem files extracted
Updated: 01-first-taste stems → Yes
Common Mistakes
❌ Don't: Manually read config and construct paths
Wrong:
cat ~/.bitwize-music/config.yaml
mv file.wav ~/music-projects/audio/artists/bitwize/albums/electronic/sample-album/
Right:
# Use MCP to resolve the correct path
resolve_path("audio", album_slug) → returns full path with artist folder
Why it matters: resolve_path reads config, resolves variables, and includes the artist folder automatically. No manual config parsing or path construction needed.
❌ Don't: Mix up content_root and audio_root
Path comparison:
- Content:
{content_root}/artists/{artist}/albums/{genre}/{album}/(markdown, lyrics) - Audio:
{audio_root}/artists/{artist}/albums/{genre}/{album}/(WAV files, stems) - Documents:
{documents_root}/artists/{artist}/albums/{genre}/{album}/(PDFs, research)
Use resolve_path with the appropriate path_type ("content", "audio", "documents") to get the right path.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |