import-audio

タスク

入力：$ARGUMENTS

設定に基づいて、オーディオファイルを正しいアルバムの場所にインポートします。

---

オーディオインポートスキル

オーディオファイルを、ユーザーのオーディオディレクトリ内の正しい場所に移動します。

ステップ 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. 次のいずれかからトラックのスラッグを特定します：
   • トラックのパターンに一致する場合は 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 回です。カウントは請求日にリセットされ、翌月への繰り越しはありません。形式にかかわらず 1 曲につき 1 回のダウンロードで、ステムも含まれます。まず WAV をダウンロードし、後から追加料金なしでステムを取得してください。同じ曲の再ダウンロードは無料です。Premier の Suno Studio からの書き出しには上限がなく、32 ビット浮動小数点／48 kHz の WAV で出力されます。1 か月でアルバム全体を用意するには、これが実用的な方法です。商用利用権が付与されるのは、有料プランで許可されたダウンロードを行った場合に限られます。

ユーザーが 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.

3. 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}/（マークダウン、歌詞）
• オーディオ：{audio_root}/artists/{artist}/albums/{genre}/{album}/（WAV ファイル、ステム）
• ドキュメント：{documents_root}/artists/{artist}/albums/{genre}/{album}/（PDF、調査資料）

適切な path_type（"content"、"audio"、"documents"）を指定して resolve_path を使用し、正しいパスを取得してください。