import-audio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Your Task

你的任务

Input: $ARGUMENTS

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

输入：$ARGUMENTS

根据配置将音频文件（WAV、MP3等）导入到正确的专辑位置。

Import Audio Skill

音频导入Skill

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

你需要将音频文件移动到用户音频目录中的正确位置。

Step 1: Parse Arguments

步骤1：解析参数

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

预期格式：

<文件路径> <专辑名称> [曲目标识]

曲目标识

为可选参数——仅在导入分轨Zip文件且无法从文件名推断曲目时需要。

示例：

```
~/Downloads/track.wav sample-album
```

~/Downloads/03-t-day-beach.wav sample-album

~/Downloads/stems.zip sample-album 01-first-taste

如果参数缺失，提示：

用法：/import-audio <文件路径> <专辑名称> [曲目标识]

示例：
  /import-audio ~/Downloads/track.wav sample-album
  /import-audio ~/Downloads/stems.zip sample-album 01-first-taste

Step 2: Resolve Audio Path via MCP

步骤2：通过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.

调用
```
resolve_path("audio", album_slug)
```
—— 返回完整的音频目录路径

解析后的路径采用镜像结构：

{audio_root}/artists/{artist}/albums/{genre}/{album}/

示例结果：

~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/

关键注意事项：务必使用

resolve_path

—— 绝对不要手动构建路径。

Step 3: Detect File Type

步骤3：检测文件类型

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.

检查文件扩展名以及是否为分轨Zip文件：

文件类型	操作
`.wav` , `.mp3` , `.flac` , `.ogg` , `.m4a`	移动到专辑音频目录（步骤4）
`.zip` (stems)	解压到单轨分轨子文件夹（步骤4b）

如何识别分轨Zip文件：用户会说明是“stems”，或者Zip文件包含

0 Lead Vocals.wav

、

1 Backing Vocals.wav

等文件。

Step 4: Create Directory and Move File

步骤4：创建目录并移动文件

bash

mkdir -p {resolved_path}
mv "{source_file}" "{resolved_path}/{filename}"

bash

mkdir -p {resolved_path}
mv "{source_file}" "{resolved_path}/{filename}"

Step 4b: Import Stems Zip

步骤4b：导入分轨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

Extract into the per-track subfolder:

bash

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]

分轨文件必须放入单轨子文件夹中，以避免文件名冲突（每个曲目都有

0 Lead Vocals.wav

等文件）：

{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
      ...

工作流程：

确定曲目标识，来源包括：
- Zip文件名（如果匹配曲目格式，例如
```
01-first-taste-stems.zip
```
  →
```
01-first-taste
```
  ）
- 用户指定的曲目（例如
```
/import-audio stems.zip sample-album 01-first-taste
```
  ）
- 如果以上都不满足：询问用户该分轨属于哪个曲目

解压到单轨子文件夹：

bash

mkdir -p {resolved_path}/stems/{track-slug}
unzip "{source_file}" -d "{resolved_path}/stems/{track-slug}"

更新曲目元数据：调用

update_track_field(album_slug, track_slug, "stems", "Yes")

分轨文件的参数格式：

<Zip路径> <专辑名称> [曲目标识]

Step 5: Confirm

步骤5：确认结果

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

反馈：

已移动：{source_file}
   至：{resolved_path}/{filename}

对于分轨文件：

已解压分轨：{source_file}
       至：{resolved_path}/stems/{track-slug}/
    文件数：共解压{count}个分轨文件
  更新信息：{track-slug} stems → Yes

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)

源文件不存在：

错误：未找到文件：{source_file}

配置文件缺失：

错误：未在 ~/.bitwize-music/config.yaml 找到配置文件
请运行 /configure 进行设置。

目标位置已存在文件：

警告：目标位置已存在文件。
是否覆盖？（原文件未被移动）

MP3 Files

MP3文件

Suno allows downloading in both WAV and MP3 formats. Always prefer WAV for mastering quality.

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

Suno支持下载WAV和MP3两种格式。为了母带制作质量，优先选择WAV格式。

如果用户提供MP3文件：

接受MP3文件并正常导入（路径逻辑相同）
向用户发出警告：

注意：这是MP3文件。为获得最佳母带制作效果，请从Suno下载WAV版本。MP3压缩会移除母带制作过程中无法恢复的音频数据。

如果无法获取WAV版本，该MP3文件可以使用，但母带制作质量可能会受限。

将文件导入与WAV文件相同的目标路径

支持的格式：WAV（优先）、MP3、FLAC、OGG、M4A

Examples

示例

/import-audio ~/Downloads/03-t-day-beach.wav sample-album

Config has:

yaml

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-audio ~/Downloads/03-t-day-beach.wav sample-album

配置文件内容：

yaml

paths:
  audio_root: ~/bitwize-music/audio
artist:
  name: bitwize

结果：

已移动：~/Downloads/03-t-day-beach.wav
   至：~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/03-t-day-beach.wav

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

/import-audio ~/Downloads/stems.zip sample-album 01-first-taste

结果：

已解压分轨：~/Downloads/stems.zip
       至：~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/stems/01-first-taste/
    文件数：共解压5个分轨文件
  更新信息：01-first-taste stems → Yes

Common Mistakes

常见错误

❌ Don't: Manually read config and construct paths

❌ 禁止：手动读取配置并构建路径

Wrong:

bash

cat ~/.bitwize-music/config.yaml
mv file.wav ~/music-projects/audio/artists/bitwize/albums/electronic/sample-album/

Right:

undefined

错误做法：

bash

cat ~/.bitwize-music/config.yaml
mv file.wav ~/music-projects/audio/artists/bitwize/albums/electronic/sample-album/

正确做法：

undefined

Use MCP to resolve the correct path

使用MCP解析正确路径

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.

resolve_path("audio", album_slug) → 返回包含艺术家文件夹的完整路径


**原因**：`resolve_path`会读取配置、解析变量并自动包含艺术家文件夹。无需手动解析配置或构建路径。

❌ Don't: Mix up content_root and audio_root

❌ 禁止：混淆content_root和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.

路径对比：

内容：

{content_root}/artists/{artist}/albums/{genre}/{album}/

（Markdown、歌词）

音频：

{audio_root}/artists/{artist}/albums/{genre}/{album}/

（WAV文件、分轨）

文档：

{documents_root}/artists/{artist}/albums/{genre}/{album}/

（PDF、研究资料）

使用带有对应

path_type

（"content"、"audio"、"documents"）的

resolve_path

来获取正确路径。",