byted-music-generate

Music Generate Skill

Volcengine Music Generation API を使用して音楽を生成します。ボーカル曲、インストゥルメンタル BGM、AI による歌詞生成に対応しています。

トリガー条件

1. ユーザーが曲の生成を希望している（歌詞またはテキストプロンプトあり）
2. ユーザーがバックグラウンドミュージック、インストゥルメンタルトラック、またはサウンドトラックを必要としている
3. ユーザーが AI による歌詞生成を希望している
4. 「曲を書く」「音楽生成」「BGM」「バックグラウンドミュージック」「歌詞」といった言葉に言及している

環境変数

2 つの認証方法に対応しています（ゲートウェイが優先されます）。

オプション 1：API Gateway（推奨）

• ARK_SKILL_API_BASE — API ゲートウェイのベース URL
• ARK_SKILL_API_KEY — API ゲートウェイの認証キー

オプション 2：直接 AK/SK を使用

• VOLCENGINE_ACCESS_KEY — AccessKey ID
• VOLCENGINE_SECRET_KEY — AccessKey Secret
• 取得方法：Volcengine Console → Account → Key Management → Create Key

使用方法

1. ユーザーの意図を判断し、モード（song／bgm／lyrics）を選択します。
2. スキルディレクトリ skills/byted-music-generate に cd します。
3. スクリプトを実行します。スクリプトは内部で API をポーリングするため、完了までに数分かかることがあります（通常、song／bgm は 1〜5 分）。
4. 実行状況を監視します：実行環境によってコマンドがバックグラウンドに移された場合、スクリプトが終了したか確認するため、定期的に（10 秒ごとに）ターミナル出力を読み取る必要があります。スクリプトはポーリングの進捗を stderr に出力し、完了時に stdout へ 1 行の JSON を出力します。
5. 完了したら、JSON 出力から audio_url または lyrics をユーザーに返します。

3 つのモード

1. song — ボーカル曲

ユーザーが歌詞（Lyrics）またはテキストプロンプト（Prompt）を指定して、ボーカル曲を生成します。

# With text prompt
python scripts/music_generate.py song --prompt "A song about summer at the beach" --genre Pop --gender Female

# With lyrics
python scripts/music_generate.py song --lyrics "[verse]\nMoonlight on the windowsill\nMemories flowing like water\n[chorus]\nYou are my moonlight" --genre Folk --mood "Sentimental/Melancholic/Lonely"

注：--lyrics と --prompt は同時に指定できません。歌詞が優先されます。ユーザーが歌詞を指定していない場合は、まず lyrics モードで歌詞を生成し、その結果を song モードに渡すことができます。

2. bgm — インストゥルメンタル BGM

希望する音楽を自然言語で説明します。v5.0 モデルでは Genre／Mood パラメーターは不要です。--text フィールドにすべてを記述してください。

python scripts/music_generate.py bgm --text "Relaxed coffee shop ambiance music with piano and guitar" --duration 60

# With song structure segments
python scripts/music_generate.py bgm --text "Epic game soundtrack" --segments '[{"Name":"intro","Duration":10},{"Name":"chorus","Duration":30}]'

3. lyrics — 歌詞生成

同期的に返されるため、ポーリングは不要です。単独で使用することも、song モードの前処理として使用することもできます。

python scripts/music_generate.py lyrics --prompt "A song about graduation farewell" --genre Folk --mood "Sentimental/Melancholic/Lonely" --gender Female

手動タスク照会（タイムアウト時のフォールバック）

python scripts/music_generate.py query --task-id "202601397834584670076931"

モード判定ロジック

User Request
    ↓
Contains "instrumental/BGM/background music/soundtrack"?
    ├─ Yes → bgm mode
    └─ No → Contains "lyrics/write lyrics" and does NOT request audio?
        ├─ Yes → lyrics mode
        └─ No → song mode
            ├─ User provided lyrics → --lyrics
            └─ User only described a theme → --prompt (or lyrics first, then song)

スクリプトのパラメーター

曲モード

パラメーター	必須	説明
--lyrics	いずれか	構成タグ付きの歌詞
--prompt	いずれか	テキストプロンプト（中国語、5～700文字）
--model-version	いいえ	v4.0 または v4.3（デフォルト：v4.3）
--genre	いいえ	音楽ジャンル
--mood	いいえ	音楽のムード
--gender	いいえ	Female / Male
--timbre	いいえ	ボーカルの音色
--duration	いいえ	長さ（秒）[30-240]
--key	いいえ	音楽のキー（v4.3 のみ）
--kmode	いいえ	Major / Minor（v4.3 のみ）
--tempo	いいえ	テンポ（v4.3 のみ）
--instrument	いいえ	楽器、カンマ区切り（v4.3 のみ）
--genre-extra	いいえ	サブジャンル、カンマ区切り、最大 2 つ（v4.3 のみ）
--scene	いいえ	シーンタグ、カンマ区切り（v4.3 のみ）
--lang	いいえ	言語（v4.3 のみ）
--vod-format	いいえ	wav / mp3（v4.3 のみ）
--billing	いいえ	prepaid / postpaid（デフォルト：postpaid）
--timeout	いいえ	最大待機秒数（デフォルト：300）

BGM モード

パラメーター	必須	説明
--text	はい	自然言語による説明
--duration	いいえ	長さ（秒）[30-120]
--segments	いいえ	曲の構成セグメントを含む JSON 配列
--version	いいえ	モデルバージョン（デフォルト：v5.0）
--enable-input-rewrite	いいえ	プロンプトの書き換えを有効にする
--billing	いいえ	prepaid / postpaid（デフォルト：postpaid）
--timeout	いいえ	最大待機秒数（デフォルト：300）

歌詞モード

パラメーター	必須	説明
--prompt	はい	歌詞のプロンプト（中国語のみ、500文字未満）
--genre	いいえ	音楽ジャンル
--mood	いいえ	音楽のムード
--gender	いいえ	Female / Male

スクリプトの戻り値情報

スクリプトは次のフィールドを含む JSON を出力します。

{
    "status": "success | timeout | error",
    "mode": "song | bgm | lyrics | query",
    "task_id": "...",
    "audio_url": "https://...",
    "duration": 46.0,
    "lyrics": "...",
    "error": null
}

ダウンロードまたは再生できるよう、audio_url をユーザーに返してください。URL の有効期間は約 1 年ですが、ユーザーには速やかにファイルを保存するよう伝えてください。

エラー処理

• スクリプトで PermissionError: Authentication not configured ... が発生した場合は、API ゲートウェイ（ARK_SKILL_API_BASE + ARK_SKILL_API_KEY）または直接 AK/SK（VOLCENGINE_ACCESS_KEY + VOLCENGINE_SECRET_KEY）の環境変数を設定するようユーザーに案内してください。これらをワークスペースの環境変数ファイルに書き込み、再試行してください。
• status が "timeout" の場合、タスクは引き続き生成中です。ユーザーに task_id と、出力に含まれる手動での照会コマンドを伝えてください。
• 著作権チェックに失敗した場合（コード 50000001）、説明を充実させるか音声の長さを延ばしてから再試行するようユーザーに提案してください。

参考資料

• 利用可能なパラメーター値（ジャンル／ムード／音色／楽器など）：references/parameters.md
• Volcengine 音楽生成ドキュメント
• API 署名ガイド