mcpField
I
import-audio

import-audio

github.com/bitwize-music-studio创意与媒体603227 次安装2 周前更新
代码仓库

关于 import-audio

import-audio 是将音频文件导入音乐项目指定专辑目录的技能，供管理曲目音频和分轨文件的创作者使用。它通过 MCP 解析配置路径，并将普通音频文件或 ZIP 分轨归档到相应位置。

主要功能

  1. 01导入 WAV、MP3 等音频格式
  2. 02按曲目整理 ZIP 分轨
  3. 03通过 MCP 解析目标路径
  4. 04导入分轨后更新曲目元数据
  5. 05检测目标文件冲突

适用场景

  1. 01将下载的音频放入专辑目录
  2. 02把 ZIP 分轨解压到指定曲目文件夹
  3. 03将 MP3 或 WAV 导入音乐项目

MCP 相关

技能调用 MCP 的 resolve_path 获取专辑音频目录，并在导入分轨后调用 update_track_field 更新曲目元数据。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bitwize-music-studio/claude-ai-music-skills --skill import-audio

安装后在 Claude Code 中输入/import-audio确认已加载。

详细介绍

你的任务

输入：$ARGUMENTS

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

导入音频技能

将音频文件移至用户音频目录中的正确位置。

第 1 步：解析参数

预期格式：<file-path> <album-name> [track-slug]

track-slug 是可选参数——仅当无法从文件名推断曲目时，导入分轨 ZIP 才需要提供。

示例：

  • ~/Downloads/track.wav sample-album
  • ~/Downloads/03-t-day-beach.wav sample-album
  • ~/Downloads/stems.zip sample-album 01-first-taste

如果缺少参数，请询问：

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

第 2 步：通过 MCP 解析音频路径

  1. 调用 resolve_path("audio", album_slug)——返回完整的音频目录路径
  2. 解析出的路径采用镜像结构：{audio_root}/artists/{artist}/albums/{genre}/{album}/

示例结果：~/bitwize-music/audio/artists/bitwize/albums/hip-hop/sample-album/

重要：始终使用 resolve_path，切勿手动构造路径。

第 3 步：检测文件类型

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

文件类型操作
.wav、.mp3、.flac、.ogg、.m4a移至专辑音频目录（第 4 步）
.zip（分轨）解压到每首曲目对应的分轨子文件夹（第 4b 步）

如何识别分轨 ZIP：用户会提到“分轨”，或者 ZIP 中包含 0 Lead Vocals.wav、1 Backing Vocals.wav 等文件。

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

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

第 4b 步：导入分轨 ZIP

分轨必须放入每首曲目对应的子文件夹，以免文件名冲突（每首曲目都有 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
      ...

工作流：

  1. 确定曲目 slug，方法如下：
    • 如果 ZIP 文件名符合曲目命名模式，则使用文件名（例如，01-first-taste-stems.zip → 01-first-taste）
    • 用户指定曲目（例如，/import-audio stems.zip sample-album 01-first-taste）
    • 如果两者都不满足：询问用户这些分轨属于哪首曲目
  2. 解压到对应曲目的子文件夹： 
    mkdir -p {resolved_path}/stems/{track-slug}
unzip "{source_file}" -d "{resolved_path}/stems/{track-slug}"
  3. 更新曲目元数据：调用 update_track_field(album_slug, track_slug, "stems", "Yes")

分轨参数格式：<zip-path> <album-name> [track-slug]

第 5 步：确认

报告：

Moved: {source_file}
   To: {resolved_path}/{filename}

分轨文件：

Extracted stems: {source_file}
       To: {resolved_path}/stems/{track-slug}/
    Files: {count} stem files extracted
  Updated: {track-slug} stems → Yes

错误处理

源文件不存在：

Error: File not found: {source_file}

配置文件缺失：

Error: Config not found at ~/.bitwize-music/config.yaml
Run /configure to set up.

目标位置已存在同名文件：

Warning: File already exists at destination.
Overwrite? (The original was not moved)

MP3 文件

Suno 支持下载 WAV 和 MP3 格式（WAV 仅限 Pro/Premier 套餐，且只能在网页端下载）。为保证母带制作质量，始终优先选择 WAV。

**自 2026-09-03 起，下载次数受限。**免费账户可获得 7 次终身试用下载（仅限个人使用，不可发布）；Pro 每月 20 次；Premier 每月 60 次。下载次数会在账单日重置，且不会结转。无论格式如何，一首歌只计为一次下载，且下载内容包含分轨——先下载 WAV，之后可免费获取分轨；重新下载同一首歌也免费。Premier 的 Suno Studio 导出次数不限，导出文件为 32 位浮点 / 48 kHz WAV，是一个月内制作整张专辑的实用方式。仅在付费套餐下进行获准的下载，才附带商业使用权。

如果用户提供 MP3 文件：

  1. 接受 MP3，并按常规方式导入（使用相同的路径逻辑）
  2. 警告用户：
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.
  1. 将文件导入与 WAV 文件相同的目标路径

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

示例

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

配置包含：

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

结果：

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/stems.zip sample-album 01-first-taste

结果：

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

常见错误

❌ 不要：手动读取配置并构造路径

错误：

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

正确：

# Use MCP to resolve the correct path
resolve_path("audio", album_slug) → returns full path with artist folder

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

❌ 不要：混淆 content_root 和 audio_root

路径对照：

  • 内容：{content_root}/artists/{artist}/albums/{genre}/{album}/（Markdown、歌词）
  • 音频：{audio_root}/artists/{artist}/albums/{genre}/{album}/（WAV 文件、分轨）
  • 文档：{documents_root}/artists/{artist}/albums/{genre}/{album}/（PDF、研究资料）

使用 resolve_path 并指定适当的 path_type（"content"、"audio"、"documents"），以获取正确的路径。

评论

支持 Markdown