import-audio

Files (1)

• SKILL.md

SKILL.md (first lines)

## Your Task

**Input**: the user's input

Import an audio file (WAV, MP3, etc.) to the correct album location based on config.

---

# Import Audio Skill

You move audio files to the correct location in the user's audio directory.

## 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

1. Call `resolve_path("audio", album_slug)` — returns the full audio directory path
2. 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

```bash
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:**

1. **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
2. **Extract** into the per-track subfolder:
   ```bash
   mkdir -p {resolved_path}/stems/{track-slug}
   unzip "{source_file}" -d "{resolved_path}/stems/{track-slug}"
   ```
3. **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
```

## Error Handling

**Source file doesn't exist:**
```
Error: File not found: {source_file}
```

**Config file missing:**
```

From apavanello/claude-ai-music-skills, CC0-1.0.

More from apavanello/claude-ai-music-skills