skywork-music-maker

Skywork Music Maker（Mureka API）

https://api.mureka.ai の Mureka API を使用して、プロ品質の音楽を生成します。このスキルでは、歌詞の作成から楽曲／インストゥルメンタルの生成まで、音楽制作の全ワークフローを扱います。

初回セットアップ

API コマンドを実行する前に、MUREKA_API_KEY が設定されているか確認してください。設定されていない場合は、https://platform.mureka.ai/ で API キーを取得する手順（登録 → API Keys → キーを生成 → export MUREKA_API_KEY="..."）を案内し、その後停止してください。キーが設定されるまでは、API 呼び出しを試みないでください。

---

スマートプロンプト変換（重要なワークフロー）

デフォルトの動作：ユーザーが曲の種類を指定しない場合は、必ず歌詞付きの楽曲を生成してください（mureka.py song を使用）。ユーザーがインストゥルメンタル、BGM、バックグラウンドミュージック、または「ボーカルなし」を明示的に求めた場合に限り、mureka.py instrumental を使用してください。

出力のデフォルト：ユーザーから別の指定がない限り、mp3 形式を使用してください。--output フラグにはディレクトリを指定します。スクリプトはディレクトリを作成し、すべての結果（音声ファイルと、楽曲の場合は lyrics.txt）をその中に保存します。ユーザーが保存場所を指定しない場合は、曲のテーマに基づく説明的なフォルダー名を付けた、ユーザーにとって使いやすいパスを選んでください（例：summer_pop_song/）。

ユーザーが自然言語（どの言語でも可）で音楽の説明を入力した場合は、必ず次のワークフローに従って、Mureka API 用の構造化プロンプトに変換してください。

変換プロセス

ユーザー入力の例：

• 「アップビートなポップソング、女性ボーカル、ギター、夏にぴったり」
• 「失恋をテーマにした悲しいピアノバラード」
• 「ファンタジーゲーム向けの壮大なオーケストラ音楽」
• 「竹笛と古筝を使った、霧がかった雰囲気の中国伝統音楽」

タスク：

1. 以下の抽出ルールに従って、構造化パラメーターを抽出します
2. プロンプトが品質基準を満たしていることを確認します（品質チェックリストを参照）
3. 生成前に、確認のためユーザーに提示します
4. 構造化プロンプトを指定して、生成コマンドを実行します

パラメーターの抽出ルール

ユーザーが自然言語で音楽の説明を入力した場合は、以下のパラメーターを直接抽出して構造化します。

必須パラメーター：

• genres：音楽ジャンル（融合スタイルを含む。例：ポップ、ロック、ジャズ、ポップラップフュージョン、オルタナティブロック、グオフェン）
• moods：感情のトーン（例：幸福感、憂うつ、エネルギッシュ、ノスタルジック、明るい）
• instruments：具体的な楽器（例：ピアノ、ギター、ドラム、二胡、古筝、シンセパッド、笛子）
• rhythms：リズムの特徴（例：4/4、スロー、シンコペーション、力強い推進感、流麗）
• vocals：ボーカルの特徴（例：女性、ハスキー、ささやき声、男性、ソフト、クリア）、または「インストゥルメンタルのみ」
• key：指定がある場合は調性（例：C メジャー、A マイナー、C# メジャー）
• bpm：1 分あたりの拍数（例：120）、またはテンポの表現（例：「スローグルーヴ」、「アップテンポ」）
• description：ムードの変化、メロディー、ハーモニー、音色、テクスチャー、ダイナミクスを捉えた簡潔な要約（50 語未満）

抽出時の指示：

1. 英語以外の用語を翻訳する：文化的・音楽的な意味を保ちながら、英語以外の音楽用語をすべて英語に変換します
2. 具体性を保つ：具体的なスタイル、サブジャンル、文化的背景など、詳細な情報を維持します（例：「Chinese traditional guofeng」とし、単に「Chinese music」としない）
3. ダイナミックな展開を設計する：適切な場合は、ムードの変化を含めます（例：「まばらなイントロ → 高まる緊張感 → カタルシスのあるコーラス」）
4. 適切に推測する：パラメーターが明示されていない場合は、ジャンルの慣習に基づいて妥当な前提を置きます
5. 英語で出力する：最終的なプロンプト文字列は、必ずすべて英語にしてください

構造化プロンプトを生成する： 抽出したすべてのパラメーターを組み合わせ、ユーザーが思い描く音楽の本質を捉えた、包括的で自然な流れの説明にします。

品質チェックリスト（生成前に確認）

生成コマンドを実行する前に、プロンプトが次の条件を満たしていることを確認してください。

必須項目：

• 具体的なジャンル（「ポップソング」ではなく「2020年代のシンセポップ」など）
• BPM またはテンポの説明（例：「120 BPM」や「スローなグルーヴ」）
• 楽器を3〜5種類、具体的に明記
• ムードや感情を表す語句（2〜3語）
• ボーカルのスタイル（または「インストゥルメンタルのみ」）
• 歌詞に構成タグ：[Verse]、[Chorus]、[Bridge]、[Outro]

注意点：

• 曖昧な表現：「素敵」「良い」「美しい」→具体的な表現に置き換える
• 矛盾する表現：「スロー」＋「エネルギッシュ」、「悲しい」＋「高揚感がある」→方向性を1つに絞る
• 短すぎる：50文字未満 → 詳細を追加する
• 歌詞の行が長すぎる：1行あたり10語超 → 短い行に分ける
• 展開がない：ムードの変化（例：「シンプル → 盛り上がる → フル編成」）を加える

避ける項目：

• 命令形の動詞：「曲を作成する」→「アップビートなポップソング」など、描写表現を使う
• 有名アーティスト名：「Taylor Swiftのようなサウンド」→代わりに特徴を描写する
• 非現実的な組み合わせ：melody_id は他の制御オプションと組み合わせられない

検証後、次に進む前に、生成するプロンプトをユーザーに提示して確認を求めてください。

---

基本ワークフロー：制作パイプライン

1. Conceptualize → User describes in natural language → YOU convert to structured prompt
2. Validate → Check prompt quality against Quality Checklist (see above)
3. Write Lyrics → Use lyrics/generate or write manually
4. Upload References → Optional: reference track, vocal sample, melody
5. Generate → Submit song/instrumental task (async) with validated prompt
6. Evaluate → Listen to all N choices, pick best
7. Iterate → Refine prompt based on what you heard

重要な手順：

• ユーザーが自然言語で入力した場合（特に英語以外の場合）、ステップ1は必須です
• ステップ2の検証により、よくある生成失敗の80％を防げます
• ステップ3：プロンプト作成の例、歌詞の構成ルール（行の長さ、音節数、韻のパターン、フックの書き方）、反復改善のベストプラクティスについて、references/prompt_guide.md を読んでください
• 概念化を省略しないでください — 明確なコンセプトなしにいきなり生成すると、ありきたりな結果になる最大の原因になります

AI アシスタントとしての役割：

1. ユーザーの自然言語を構造化された Mureka プロンプトに変換する（スマートプロンプト変換を使用）
2. プロンプトの品質を検証する → 問題を指摘する → 修正案を提示する
3. 適切な構成で歌詞を書く、または生成する
4. 確認のためにプロンプトをユーザーに提示する
5. 検証済みのプロンプトで生成コマンドを実行する
6. 生成結果に基づいて、反復改善と調整を支援する

---

CLI ツール

すべての操作は、単一のスクリプト scripts/mureka.py を通じて行います。

mureka.py song           Generate a song with lyrics and vocals
mureka.py instrumental   Generate an instrumental track
mureka.py lyrics         Generate or extend lyrics
mureka.py upload         Upload reference audio, vocals, melodies

使用方法の詳細は python scripts/mureka.py --help を実行して確認してください。注：複数の候補を生成する場合は、--n ではなく -n 2（ハイフン1つ）を使用してください。

---

よくあるシナリオ

「動画のBGMが欲しいだけです」

python scripts/mureka.py instrumental \
  --prompt "ambient electronic, calm, 80 BPM, soft pads, no percussion, background music for tech product video" \
  --output ./bg_music

「曲は欲しいのですが、歌詞がありません」

# Step 1: Generate lyrics with proper structure
python scripts/mureka.py lyrics generate "a nostalgic summer love song, bittersweet, looking back at memories"

# Step 2: Copy/refine the output, then generate the song
python scripts/mureka.py song \
  --lyrics "[Verse]\n(paste lyrics here)\n[Chorus]\n(paste chorus here)" \
  --prompt "indie pop, warm, 110 BPM, acoustic guitar, soft drums, male vocal" \
  --output ./summer_song

---

高度な機能

参照音源を使った生成

スタイルの参考にする音源をアップロードします（長さは正確に30秒、形式はmp3/m4a）：

python scripts/mureka.py upload my_reference.mp3 --purpose reference
# → File ID: 542321
python scripts/mureka.py song --lyrics "[Verse]\n..." --reference-id 542321 --output ./song

ボーカルのクローン

特定の声を使うためのボーカルサンプルをアップロードします（15〜30秒、mp3/m4a）：

python scripts/mureka.py upload my_voice.mp3 --purpose vocal
# → File ID: 789012
python scripts/mureka.py song --lyrics "[Verse]\n..." --vocal-id 789012 --prompt "R&B, smooth, 90 BPM" --output ./song

---

制御オプションとルール

楽曲生成の制御オプションの組み合わせ

楽曲の生成時には、次の制御オプションを組み合わせて使用できます。

組み合わせ	prompt	reference_id	vocal_id	melody_id
スタイルのみ	✅
参照音源のみ		✅
声のみ			✅
メロディのみ				✅
スタイル＋声	✅		✅
参照音源＋声		✅	✅

重要：

• melody_id は他のオプションと組み合わせられません — 単独で使用してください
• prompt と reference_id は同時に指定できません — どちらか一方を使用してください

インストゥルメンタル生成のルール

インストゥルメンタルでは、prompt と instrumental_id を同時に指定できません — どちらか一方を使用してください。

ファイルアップロードの要件

用途	形式	長さ	備考
reference	mp3/m4a	正確に30秒	超過分はトリミングされます
vocal	mp3/m4a	15〜30秒	超過分はトリミングされます
melody	mp3/m4a/mid	5〜60秒	MIDIを推奨します
instrumental	mp3/m4a	正確に30秒	インストゥルメンタルの参照用

モデルの選択

常に mureka-8 を使用してください。最新かつ最高品質のモデルです。

---

エラー処理

スクリプトは失敗時に RuntimeError または requests.HTTPError を発生させます。よくあるエラーには、次のように対処してください。

エラー	原因	対処
401 Unauthorized	API キーが無効、または期限切れです	MUREKA_API_KEY を確認するようユーザーに依頼します
429 Too Many Requests	レート制限を超過しました	30～60 秒待ってから再試行します
402 / Insufficient balance	アカウント残高が不足しています	チャージするため、ユーザーに https://platform.mureka.ai を案内します
Task ended with status: failed	生成に失敗しました（不適切なプロンプト、サーバーエラー）	品質チェックリストに照らしてプロンプトを確認し、再試行します
Task ended with status: timeouted	生成に時間がかかりすぎました	再試行します。繰り返し発生する場合は、プロンプトを簡潔にするか、別のモデルを試します
ConnectionError / Timeout	ネットワークの問題です	数秒待ってから再試行します

一般的な対処方針：エラーメッセージを注意深く読みます。クライアントエラー（4xx）の場合は入力を修正します。サーバーエラー（5xx）またはタイムアウトの場合は、ユーザーに報告する前に一度再試行します。

---

よくある問題のトラブルシューティング

問題	解決策
タスクが失敗する、またはタイムアウトする	• プロンプトが品質チェックリストを満たしているか確認します • 歌詞に構成タグがあるか確認します • 生成を再試行します
ボーカルが急いで聞こえる	• 歌詞の行を短くします（10 語以下） • 1 行あたりの音節数を減らします
指定した楽器が聞こえない	• プロンプトで各楽器を明示的に指定しているか確認します • より具体的な説明（例：「アコースティックギターのストローク」）を追加します
プロンプトと出力が一致しない	• 具体性を高めます（正確なジャンル、BPM、楽器） • ムードの変化（「まばら → 豊か」）を追加します • 選択肢を n=3 で生成します
melody_id エラー	• melody_id は単独で使用する必要があります • --prompt、--reference-id、--vocal-id を削除します
無効な file_id	• ファイル ID はアップロードしたアカウントでのみ有効です • 別のセッションでアップロードしたファイルの場合は、再アップロードします

パラメーターに関するヘルプ：

python scripts/mureka.py --help
python scripts/mureka.py song --help

---

環境

• API キー：環境変数 MUREKA_API_KEY（必須）
• ベース URL：https://api.mureka.ai
• 依存関係：Python 3、requests ライブラリ
• 請求：curl -H "Authorization: Bearer $MUREKA_API_KEY" https://api.mureka.ai/v1/account/billing で残高を確認します