music

使用するタイミング

• ユーザーがプロンプトや歌詞からオリジナルの AI ミュージックを生成したい場合
• ユーザーが既存の曲を新しい歌詞でリミックス／再作成したい場合
• ユーザーが純粋なインストゥルメンタル、または画像や動画に合わせたサウンドトラックを求めている場合
• ユーザーが曲を延長したり、単一のトラックを分離／生成したりしたい場合
• ユーザーが音声を分析したい場合 — 歌詞の認識、曲の説明、ステムの分割など
• ユーザーが「音乐」、「music」、「生成音乐」、「generate music」、「翻唱」／「混音」／「remix」、「续写」／「extend」、「纯音乐」／「instrumental」、「配乐」／「soundtrack」、「分轨」／「stem」、「识别歌词」、「作曲」、「compose」、「create a song」、または「做一首歌」と言った場合

使用しないタイミング

• ユーザーがテキスト読み上げを求めている場合（/speech を使用）
• ユーザーがポッドキャスト形式のディスカッションを求めている場合（/podcast を使用）
• ユーザーがナレーション付きの解説動画を求めている場合（/explainer を使用）
• ユーザーが話し言葉の音声をテキストに文字起こししたい場合 — 歌詞ではない音声（/asr を使用）

目的

listenhub music CLI を通じて Mureka プロバイダーを利用する、ListenHub の音楽ツールキット一式です。次の機能を提供します。

生成（非同期 — ポーリング用のタスクを返します）：

1. generate — テキストや歌詞から新しい曲を生成します。スタイル、タイトル、インストゥルメンタル、クローンした --vocal-id を指定できます。
2. remix — 既存の曲と新しい歌詞から曲を再作成します。入力には音声ファイル、音声 URL、またはプロバイダーの曲 ID のいずれかを使用します。
3. instrumental — プロンプトから純粋なインストゥルメンタルを生成するか、参照音声に基づいて生成します。
4. soundtrack — 画像や動画に合わせた音楽を生成します。
5. track — 曲から単一の楽器／ボーカルトラックを分離するか、生成します。
6. extend — 曲を長くします。
7. cover (非推奨) — 旧式のカバー作成フローです。remix の使用を推奨します。

分析（同期 — 結果をすぐに返します）：

8. recognize — 行ごとのタイムスタンプ付きで歌詞を認識します。
9. describe — 説明、タグ、ジャンル、楽器を返します。
10. stem — 曲を個別のステムに分割します（ZIP のダウンロード URL）。

タスク管理： list（最近のタスク）と get <taskId>（1 件のタスクのステータス／結果）。

生成コマンドのモデル：auto（デフォルト）、mureka-7.6、mureka-8、mureka-9、mureka-o2。コマンドごとのパラメーターの詳細は references/music-api.md を参照してください。

厳守事項

• 何らかの操作を行う前に、必ず shared/config-pattern.md に従って設定を読み取ってください
• 実行モード、エラー処理、インタラクションパターンについては、shared/cli-patterns.md に従ってください
• 認証チェックについては、必ず shared/cli-authentication.md に従ってください
• ~/Downloads/ や .listenhub/ にはファイルを保存しないでください。アーティファクトは現在の作業ディレクトリに、内容がわかる名前を付けて保存してください（shared/config-pattern.md § Artifact Naming を参照）
• スピーカーは関係ありません — 音楽生成ではスピーカーを選択しません
• ファイルサイズの上限（すべて最大 10 MB）：音声 mp3/m4a（track は wav も受け付けます）；画像 jpg/jpeg/png/webp；動画 mp4/mov/avi/mkv/webm
• すべての時間範囲フラグは秒単位です（--generate-start/--generate-end）
• 非同期の生成コマンドでは、長いタイムアウトを使用してください：run_in_background: true と timeout: 660000（600 秒以上）。同期コマンド（recognize、describe、stem）はすぐに結果を返します
• cover は非推奨です — ユーザーが明示的に cover を求めない限り、remix を案内してください

複数選択の各ステップでは AskUserQuestion ツールを使用してください。選択肢をプレーンテキストで表示してはいけません。質問は一度に 1 つずつ行ってください。次のステップに進む前に、ユーザーの回答を待ってください。すべてのパラメーターを収集したら、選択内容を要約してユーザーに確認してください。ユーザーが明示的に確認するまで、CLI コマンドを実行してはいけません。

Step -1: CLI 認証チェック

shared/cli-authentication.md に従ってください。CLI がインストールされていない場合、またはユーザーがログインしていない場合は、自動でインストールしてログインしてください — ユーザーにコマンドを手動で実行するよう求めてはいけません。

Step 0: 設定のセットアップ

shared/config-pattern.md の Step 0（Zero-Question Boot）に従ってください。

ファイルが存在しない場合 — デフォルト設定でサイレントに作成し、続行してください：

mkdir -p ".listenhub/music"
echo '{"outputMode":"download","language":null}' > ".listenhub/music/config.json"
CONFIG_PATH=".listenhub/music/config.json"
CONFIG=$(cat "$CONFIG_PATH")

セットアップについて質問してはいけません。 そのまま Interaction Flow に進んでください。

ファイルが存在する場合 — 設定をサイレントに読み取り、続行してください：

CONFIG_PATH=".listenhub/music/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/music/config.json"
CONFIG=$(cat "$CONFIG_PATH")

セットアップフロー（ユーザーが明示的に再設定を求めた場合のみ）

ユーザーが明示的に再設定を求めた場合にのみ実行します。現在の設定を表示します。

当前配置 (music)：
  输出方式：{inline / download / both}
  语言偏好：{zh / en / 未设置}

次に、以下を尋ねます。

1. outputMode：shared/output-mode.md § セットアップフローの質問に従います。

2. 言語（任意）：「默认语言？」

   • 「中文 (zh)」
   • 「English (en)」
   • 「每次手动选择」 → null のままにします

回答を収集したら、すぐに保存します。

NEW_CONFIG=$(echo "$CONFIG" | jq --arg m "$OUTPUT_MODE" '. + {"outputMode": $m}')
if [ "$LANGUAGE" != "null" ]; then
  NEW_CONFIG=$(echo "$NEW_CONFIG" | jq --arg lang "$LANGUAGE" '. + {"language": $lang}')
fi
echo "$NEW_CONFIG" > "$CONFIG_PATH"
CONFIG=$(cat "$CONFIG_PATH")

インタラクションフロー

ステップ 1：機能

機能を選択します。ユーザーの意図がすでに明確な場合は質問を省略します（例：「翻唱」／「混音」／「remix」→ remix、「作曲」／「compose」／「做一首歌」→ generate、「纯音乐」／「instrumental」→ instrumental、「续写」／「extend」→ extend、「分轨」／「stem」→ stem、「识别歌词」→ recognize）。

Question: "想做什么？"
Options:
  - "原创 (Generate)" — 用文字 / 歌词生成全新歌曲
  - "混音 (Remix)" — 基于已有歌曲 + 新歌词重新创作
  - "纯音乐 (Instrumental)" — 生成无人声的器乐
  - "配乐 (Soundtrack)" — 为图片或视频配乐
  - "其他" — 续写 / 单轨 / 识别歌词 / 描述 / 分轨

ユーザーが「その他」を選んだ場合は、續写（Extend）、単一トラック（Track）、歌詞の認識（Recognize）、説明（Describe）、ステム分離（Stem）を一覧にした 2 つ目の AskUserQuestion で続けて質問します。

get <taskId> と list はインタラクティブなフローではありません。タスクのステータスについてユーザーから尋ねられた場合は、直接実行します。

ステップ 2：入力を収集する（機能ごと）

機能ごとの以下のフィールドを使用します。必須の入力を尋ね、任意の入力も提示します。音声／画像／動画ファイルについては、確認前に検証します。

• ローカルパス：ファイルが存在し、拡張子がそのコマンドで許可されているリストと一致することを確認します（Hard Constraints／references/music-api.md を参照）。
• URL：そのまま受け付けます（CLI が検証します）。
• サイズ：10 MB を超えるローカルファイルは拒否します。

FILE_SIZE=$(stat -f%z "{path}" 2>/dev/null || stat -c%s "{path}" 2>/dev/null)
if [ "$FILE_SIZE" -gt 10485760 ]; then echo "File exceeds 10 MB limit"; fi

generate — --prompt および／または --lyrics（少なくとも 1 つは必須）。--style、--title、--model、--instrumental、--vocal-id は任意です。

remix — 入力ソースは 1 つのみ：--audio（ファイル）／--audio-url／--provider-song-id。加えて --lyrics と --prompt（両方必須）。--style、--title、--model は任意です。

instrumental — --prompt／--reference-audio のいずれか 1 つのみ。--title、--model は任意です。

soundtrack — --image／--video のいずれか 1 つのみ。--prompt、--title、--model は任意です。

track — 入力ソースは 1 つのみ：--audio／--provider-song-id。--generate-type（Vocals|Instrumental|Drums|Bass|Guitar|Keyboard|Percussion|Strings|Synth|FX|Brass|Woodwinds のいずれか）。--prompt は任意です。--lyrics はタイプが Vocals の場合のみ指定します。--vocal-gender male|female。--generate-start／--generate-end（秒）。--model。

extend — 入力ソースは 1 つ：--audio／--provider-song-id。--prompt、--model は任意です。

recognize／describe／stem — --audio のみ。stem では --model audio-separation-1|audio-separation-2 も指定します。

複数選択式のフィールド（model、generate-type、vocal-gender、instrumental の yes/no）には AskUserQuestion ツールを使用します。自由入力のフィールド（prompt、lyrics、style、title）にはプレーンテキストを使用します。

ステップ 3：確認

機能と収集したすべてのパラメーターを要約してから、ユーザーに確認を求めます。例：

generate:

准备生成音乐：
  能力：原创 (Generate)
  描述：{prompt / 无}
  歌词：{lyrics / 无}
  风格：{style / 自动}
  标题：{title / 自动}
  模型：{model / auto}
  人声：{带人声 / 纯音乐}
  Vocal ID：{vocal-id / 无}
  确认？

remix:

准备混音：
  能力：混音 (Remix)
  原曲：{audio / audio-url / provider-song-id}
  新歌词：{lyrics}
  描述：{prompt}
  风格：{style / 自动}
  标题：{title / 自动}
  模型：{model / auto}
  确认？

分析機能（recognize／describe／stem）の要約は、機能と入力音声のみです（stem の場合は分離モデルも含めます）。これらは同期的に実行されるため、確認は簡潔にできます。

CLI コマンドを実行する前に、明示的な確認を待ちます。

ワークフロー

非同期生成コマンド

generate、remix、instrumental、soundtrack、track、extend、cover。

1. 送信（バックグラウンド）：run_in_background: true と timeout: 660000 を指定します。必ず --json を渡してください。ユーザーが指定したフラグのみを含め、それ以外は省略します。

   generate:

   listenhub music generate \
     --prompt "{prompt}" \
     --lyrics "{lyrics}" \
     --model "{model}" \
     --style "{style}" \
     --title "{title}" \
     --instrumental \
     --vocal-id "{vocal-id}" \
     --json
   

   remix:

   listenhub music remix \
     --audio "{path}" \
     --lyrics "{lyrics}" \
     --prompt "{prompt}" \
     --style "{style}" \
     --title "{title}" \
     --json
   

   （--audio、--audio-url、--provider-song-id のいずれか1つのみを使用します）

   instrumental:

   listenhub music instrumental \
     --prompt "{prompt}" \
     --model "{model}" \
     --json
   

   （または、--prompt の代わりに --reference-audio "{path}" を使用します）

   soundtrack:

   listenhub music soundtrack \
     --image "{path}" \
     --prompt "{prompt}" \
     --json
   

   （または、--image の代わりに --video "{path}" を使用します）

   track:

   listenhub music track \
     --audio "{path}" \
     --generate-type "Vocals" \
     --lyrics "{lyrics}" \
     --vocal-gender "female" \
     --generate-start 0 --generate-end 30 \
     --json
   

   （または --provider-song-id を使用します。--lyrics は --generate-type Vocals の場合にのみ使用します）

   extend:

   listenhub music extend \
     --audio "{path}" \
     --prompt "{how to continue}" \
     --json
   

   CLI が内部でポーリングを処理します。生成には最大約10分かかる場合があります。

2. タスクが送信されたことと、完了時に通知されることをユーザーに伝えます。taskId しかない場合は、listenhub music get <taskId> --json または listenhub music list --json で確認できます。

3. 完了通知を受け取ったら、結果を提示します。CLI の JSON はタスクオブジェクトです。曲は tracks[0]、クレジットは creditCost、duration の単位は秒です。主要なフィールドを解析します。

   AUDIO_URL=$(echo "$RESULT" | jq -r '.tracks[0].audioUrl // empty')
   TITLE=$(echo "$RESULT" | jq -r '[.tracks[0].title, .params.title, "Untitled"] | map(select(. != null and . != "")) | .[0]')
   # duration is seconds (older pre-rollout Mureka tasks may still be ms → a value ≥ 3600 means ms)
   DURATION=$(echo "$RESULT" | jq -r '.tracks[0].duration // 0' \
     | awk '{d=$1; if (d>=3600) d/=1000; printf "%d:%02d", int(d/60), int(d%60)}')
   CREDITS=$(echo "$RESULT" | jq -r '.creditCost // empty')
   

   設定から OUTPUT_MODE を読み取ります。動作については shared/output-mode.md に従ってください。

   inline または both：音声 URL をクリック可能なリンクとして表示します。

   音乐已生成！
   
   标题：{title}
   在线收听：{audioUrl}
   时长：{duration}
   消耗积分：{credits}
   

   download または both：ファイルもダウンロードします。shared/config-pattern.md の「§ Artifact Naming」に従って、タイトルからスラッグを生成します。

   SLUG="{slug}"  # e.g. "summer-breeze"
   NAME="${SLUG}.mp3"
   # Dedup: if file exists, append -2, -3, etc.
   BASE="${NAME%.*}"; EXT="${NAME##*.}"; i=2
   while [ -e "$NAME" ]; do NAME="${BASE}-${i}.${EXT}"; i=$((i+1)); done
   curl -sS -o "$NAME" "{audioUrl}"
   

   已保存到当前目录：
     {NAME}
   

同期分析コマンド

recognize、describe、stem は同じ呼び出しで結果を返すため、フォアグラウンドで実行し（バックグラウンド実行や長いタイムアウトは指定せず）、すぐに結果を提示します。

recognize（歌詞＋タイムスタンプ）：

listenhub music recognize --audio "{path}" --json

describe（説明、タグ、ジャンル、楽器）：

listenhub music describe --audio "{path}" --json

stem（分離されたステム → ZIP ダウンロード URL）：

listenhub music stem --audio "{path}" --model "audio-separation-2" --json

download／both モードでは、ZIP URL を速やかに cwd にダウンロードします。

タスク管理

listenhub music list --json            # recent tasks
listenhub music get "{taskId}" --json   # one task's status / result

生成が成功した後

ユーザーが言語を明示的に指定した場合は、このセッションで使用した言語で設定を更新します。

if [ -n "$LANGUAGE" ]; then
  NEW_CONFIG=$(echo "$CONFIG" | jq --arg lang "$LANGUAGE" '. + {"language": $lang}')
  echo "$NEW_CONFIG" > "$CONFIG_PATH"
fi

推定所要時間：

• 音楽の生成：5～10分

リソース

• コマンドごとのパラメーターリファレンス：references/music-api.md
• CLI 認証：shared/cli-authentication.md
• CLI パターン：shared/cli-patterns.md
• 設定パターン：shared/config-pattern.md
• 出力モード：shared/output-mode.md

組み合わせ

• 呼び出すもの：なし
• 呼び出し元：content-planner（フェーズ3）

例

オリジナル曲を生成：

「夏の海辺をテーマにした曲を作って」

1. 検出：生成モード（「曲を作って」）
2. 設定を読み込みます（初回実行時：outputMode: "download" を含むデフォルト設定を作成します）
3. 推定：モード = 生成、プロンプト = 「夏の海辺をテーマにした曲」
4. 質問：スタイルは？タイトルは？インストゥルメンタルですか？
5. 概要を確認 → ユーザーが確認

listenhub music generate \
  --prompt "关于夏天海边的歌" \
  --json

CLI の結果が返るまで待ってから、{slug}.mp3 をカレントディレクトリにダウンロードします。

既存の曲をリミックス：

「demo.mp3 の歌詞を新しくしてリミックスし、シティポップ風にして」

1. 検出：リミックス機能（「リミックス」）
2. 検証：demo.mp3 が存在し、mp3/m4a 形式で、10 MB 未満であること
3. 質問：新しい歌詞（--lyrics、必須）、プロンプト／方向性（--prompt、必須）、スタイル、タイトル
4. 概要を確認 → ユーザーが確認

listenhub music remix \
  --audio "demo.mp3" \
  --lyrics "{new lyrics}" \
  --prompt "rework as upbeat city pop" \
  --style "city pop" \
  --json

CLI の結果が返るまで待ってから、{slug}.mp3 をカレントディレクトリにダウンロードします。

インストゥルメンタルを生成：

「ゲームのイントロ用に、エレクトロニックなインストゥルメンタル曲を作って」

1. 検出：インストゥルメンタル機能（「instrumental」）
2. 推定：プロンプト = 「ゲームのイントロ用のエレクトロニックな曲」
3. 概要を確認 → ユーザーが確認

listenhub music instrumental \
  --prompt "electronic track for a game intro" \
  --json

CLI の結果が返るまで待ってから、{slug}.mp3 をカレントディレクトリにダウンロードします。

動画用のサウンドトラック：

「この clip.mp4 に緊張感のあるBGMを付けて」

1. 検出：サウンドトラック機能（「BGMを付けて」）、入力は動画
2. 検証：clip.mp4 が存在し（mp4/mov/avi/mkv/webm）、10 MB 未満であること
3. 推定：プロンプト = 「緊張感のあるBGM」
4. 概要を確認 → ユーザーが確認

listenhub music soundtrack \
  --video "clip.mp4" \
  --prompt "tense, suspenseful background score" \
  --json

歌詞を認識（同期処理）：

「song.mp3 の歌詞を認識して」

1. 検出：認識機能（「歌詞を認識」）
2. 検証：song.mp3 が存在し、10 MB 未満であること
3. フォアグラウンドで実行し、タイムスタンプ付きの歌詞を表示します

listenhub music recognize --audio "song.mp3" --json

ステムを分離（同期処理）：

「track.mp3 をトラックごとに分離して」

1. 検出：ステム機能（「トラックごとに分離」）
2. 質問：分離モデル（audio-separation-1 / audio-separation-2）
3. フォアグラウンドで実行します。ダウンロードモードでは、ZIP URL からカレントディレクトリに取得します

listenhub music stem --audio "track.mp3" --model "audio-separation-2" --json