masterup

前後工程

• 前工程: /automation-run, /suno, /suno-helper
• 後工程: /videoup

Overview

SunoAI 楽曲のクロスフェード結合でマスター音源を自動生成するまでの一連フローを実行します。

ダウンロードの責務分離: 楽曲のダウンロードは /suno-helper が一括ダウンロード機能で自動実行するのが primary path。本スキルの Step 2-3（WebFetch + CDN curl）は /suno-helper でダウンロード済みの場合はスキップされる。本スキルの主責務は マスター音源生成 + workflow-state 更新 である。

完了条件

以下がすべて満たされたとき本スキルは完了とする（各項目の詳細は該当 Step が正）:

1. Step 1.5 / 1.6 / 3〜4.5 の検証ゲートがすべて通過している（FAIL / MISSING / 混入 / 生成漏れが残る間は Step 5 に進まない）
2. 01-master/ にマスター音源（既定 master.mp3）が生成されている
3. workflow-state.json の assets.raw_master と updated_at が更新されている（phase は "prepared" のまま。"mastered" への遷移は /wf-next の責務）

Subagent Contract

subagent として呼ぶ場合、メインエージェントは対象コレクション、fallback path を使う場合は確定済み playlist URL または title list、実行する処理をリポジトリルート相対パスまたは値で入力に含める。選曲、混入許容、over-max 例外採用などの承認が必要なら、メインが承認を得るまで subagent を起動しない。subagent は workflow-state.json を読み書きせず、AskUserQuestion を実行しない。Step 5.6 の雨レイヤー後処理は成果物生成時に workflow-state.json を更新するため subagent の担当外とし、メインエージェントが実行する。完了報告には status: success | failure、生成した 01-master/master.*、01-master/.selection.log の絶対パス一覧、エラーを含める。メインは成果物存在を検証してから state を更新する。直接実行時は既存手順を変更しない。

設定読み込みゲート

前提確認や Step 1 に入る前に、以下を必ず Read（Codex では同等のファイル閲覧）で開く。SKILL.md の説明や記憶から設定値を推測しない。

1. .claude/skills/masterup/config.default.yaml
2. config/skills/masterup.json（存在する場合）
3. config/skills/masterup.yaml（JSON が存在しない場合の fallback）

読み込み後は youtube_automation.utils.skill_config.load_skill_config("masterup") と同じ deep-merge 前提で、チャンネル上書きを優先して扱う。TS CLI uv run yt-generate-master は config/skills/masterup.json を優先し、存在しない場合のみ config/skills/masterup.yaml を fallback として読む。存在しない override は未設定として扱い、勝手に作成しない。

前提

以下を確認し、満たさなければ前工程を案内して停止する:

• チャンネルの音楽エンジンが Suno であること。Lyria チャンネルでは /lyria が 01-master/master.mp3 を直接出力するため本スキルは不要
• 対象コレクションが /suno 完了済みであること（collections/planning/ 配下に workflow-state.json があり assets.music_prompts = true、かつ 20-documentation/suno-prompts.json が存在）。無ければ /wf-new → /suno を案内して停止する
• 02-Individual-music/ にダウンロード済み音源が揃っていること（primary path は /suno-helper の一括ダウンロード）。未ダウンロードの場合は /suno-helper を案内するか、fallback としてプレイリスト URL を引数に受け取り Step 2-3 で DL する。音源が揃っていれば playlist URL は不要（URL 未指定を理由に停止しない。突合は Step 1.6 のローカルファイル名を第一手段にする）
• ffmpeg / ffprobe が利用可能であること（uv run yt-generate-master が使用）。無ければ /setup を案内する

設定

Python の /masterup 経路は skill-config (.claude/skills/masterup/config.default.yaml) とチャンネル上書きを deep-merge して読む。 TS CLI uv run yt-generate-master は audio の実行時既定値を組み込み default として持ち、同梱 config.default.yaml の audio.bitrate / audio.crossfade_duration と同期テストで固定する。チャンネル側で上書きする場合は config/skills/masterup.json を優先する。既存チャンネル互換として config/skills/masterup.yaml もサポートするが、両方ある場合は JSON が優先される。TS CLI が読む audio section は optional で、post_processing / pair_selection だけの override は有効。audio が存在する場合は object でなければならず、未対応 YAML 行や空 scalar は config error として停止する。

マスター音源生成は uv run yt-generate-master CLI がチャンネル側 audio.crossfade_duration override を読み、未指定時の組み込み default は同梱 config.default.yaml と同期テストで固定する。そのため実音声のクロスフェードと metadata_generator のタイムスタンプ計算は同じ既定値・同じチャンネル上書き値を使う。

When to Use

• /suno-helper で楽曲生成・ダウンロードが完了し、マスター音源を生成したいとき
• 02-Individual-music/ に MP3 / M4A / WAV ファイルが揃っている状態でマスター結合を実行したいとき
• /suno-helper のダウンロードが使えない場合のフォールバックとして、プレイリスト URL 経由で DL + マスター生成を一貫実行したいとき

Lyria で音源を生成するチャンネルでは /lyria が 01-master/master.mp3 を直接出力するため本スキルは不要。

Quick Reference

uv run yt-generate-master の値は CLI フラグ > config/skills/masterup.json > config/skills/masterup.yaml > 組み込み default の順で解決される。組み込み default の audio.bitrate / audio.crossfade_duration は同梱 config.default.yaml と同期テストで固定する。--crossfade-duration / audio.crossfade_duration は 0 より大きい数値でなければならない。

Suno 依存の脆弱性と復旧手段

注: suno-helper の一括ダウンロード機能により、以下の WebFetch / CDN 依存は fallback 経路に格下げされた。通常運用では suno-helper が DL を完了するため、本セクションの脆弱性は fallback 使用時にのみ該当する。

本スキルの fallback 経路は Suno の公式 API ではなく、UI でレンダリングされる HTML（WebFetch）と CDN URL パターン（https://cdn1.suno.ai/{song_id}.mp3）への curl アクセスという 非公式・非サポートな経路 に依存している。Suno 側の UI / CDN 仕様は事前告知なく変更されうるため、ある日突然 /masterup の Step 2 / Step 3 が壊れる可能性があることを前提に運用すること。

どこが壊れうるか

壊れた時の判定フロー

1. Step 2 で曲リストが取れない → Suno UI の HTML 構造変更を疑う。WebFetch 結果を生で確認し、プロンプトを更新して回避できるかを試す。回避不可なら下記フォールバックへ。
2. Step 3 で 403 / 404 が連発 → CDN URL パターン変更を疑う。1 曲を手動で Suno UI からダウンロードして MIME / URL を確認し、suno_download.cdn_url_template の更新で吸収できるか判定する。吸収不可なら下記フォールバックへ。
3. いずれの場合も silent な続行は禁止（不完全な master.mp3 を生成しない）。ユーザーへ「Suno 経路が壊れた可能性が高い。fallback 運用に切替推奨」と明示報告し、停止する。

フォールバック運用（手動ダウンロード → uv run yt-generate-master 直叩き）

/masterup の Step 1 / Step 5 / Step 5.5 / Step 6 / 完了時の更新は MP3 が 02-Individual-music/ に揃っていれば成立するため、Step 2 / Step 3 を 手動で代替することで運用継続できる:

1. Suno UI から曲を 1 つずつ MP3 ダウンロード（公式に提供されている UI 経路。サブスク権利範囲内）
2. アクティブコレクションの 02-Individual-music/ に配置し、ファイル名を連番 + タイトルで揃える（例: 01-pattern-a-arrival.mp3）
3. uv run yt-generate-master（または --target-duration / --shuffle などのオプション付き）を 直接実行
4. 必要に応じて uv run yt-finalize-master（雨音レイヤー）→ Step 6 の rsync 同期を 手動で順番に実行
5. uv run yt-raw-master-check <コレクションディレクトリ> --apply で workflow-state.json の assets.raw_master / updated_at を更新する（手動編集は不要。更新し忘れても次回の /masterup / /wf-status 起動時に Step 1.4 の突合チェックが不整合を検知・警告する）

このフォールバックは /masterup が壊れていても master.mp3 を生成できる最小経路であり、Suno 公式 API 公開までの暫定運用として機能する。

Suno 公式 API 公開時の移行プラン（将来案 / 現行手順ではない）

この節は yt-suno-fetch が存在する前提の現行実行手順ではない。Suno が公式 API（プレイリスト一覧 / 楽曲メタデータ / ダウンロード URL）を公開した場合の移行方針:

1. 新規 yt-suno-fetch CLI を追加（scripts/ 配下、yt-* プレフィックス踏襲、pyproject.toml::[project.scripts] 登録）。公式 API クライアントを実装し、認証情報は auth/suno_token.json 等の独立ファイル + utils/secrets.py::_SECRET_REFS 経由で解決する。
2. 本 SKILL.md の Step 2 / Step 3 を書き換え、WebFetch + CDN curl の経路を yt-suno-fetch 呼び出しに置換する。skill-config の suno_download.cdn_url_template は deprecated として config.default.yaml に deprecation note を残し、しばらくは「API 障害時の緊急 fallback」として併存させる。
3. 非公式経路は別 skill /masterup-legacy へ退避するか、もしくは本 SKILL.md 内で mode: "official" | "legacy" を切替可能にする（移行期間中の保険）。
4. 公式 API が安定し下流チャンネル全てが移行完了したら非公式経路を削除し、suno_download.cdn_url_template を skill-config からも除去する（破壊的変更として major version bump）。

移行作業は本 issue とは別 issue で扱う。Suno が公式 API 公開を発表した時点で本セクションのリンクとして issue を起票すること。

Instructions

あなたは SunoAI 楽曲ダウンロード & マスターアップマネージャーです。

引数の解釈

$ARGUMENTS

• 第1引数: SunoAI プレイリストURL（省略可）。02-Individual-music/ に音源が揃っていれば URL なしで完走できる（Step 2-3 はスキップ）。URL 未指定を理由に「raw master 生成には playlist URL が必要です。URL を教えてください」と案内して停止するのは誤り — Step 1.6 でローカルファイル名を突合する

前提条件

• アクティブなコレクションの 02-Individual-music/ ディレクトリが存在
• WebFetch ツールが利用可能であること（Step 2-3 を実行する場合のみ）

Step 1: コレクションの特定

1. collections/planning/ の workflow-state.json を検索
2. assets.music_prompts = true かつ assets.raw_master = null のコレクションを対象
3. 複数ある場合はユーザーに選択を促す

Step 1.4: raw_master 実ファイル突合チェック（不整合検知 / #1668）

対象コレクションを確定したら、生成に進む前に assets.raw_master と 01-master/ の実ファイルを突合する。フォールバック運用（yt-generate-master 直接実行）では 01-master/master.mp3 が生成済みでも assets.raw_master が null のまま残ることがあり、放置すると後続スキルが古い状態を前提に進行する:

uv run yt-raw-master-check <コレクションディレクトリ>

• exit 0（整合）: そのまま Step 1.5 へ進む
• exit 2（不整合検知）: CLI が出力した警告（例:「assets.raw_master が実ファイルと一致しません。更新しますか」）をユーザーに提示し、AskUserQuestion で更新可否を確認する
  • 承認 → uv run yt-raw-master-check <dir> --apply を実行し、assets.raw_master / updated_at が更新されたことを確認してから Step 1.5 へ進む。raw master が既に揃っている場合は Step 2〜5 の再生成は不要（Step 6 / 完了時の更新のみ確認）
  • 非承認 → workflow-state.json は変更しない。警告を無視して silent に続行するのは禁止 — 不整合が残ったままである旨を明示してから、ユーザーの指示（再生成 or 中断）を仰ぐ。次回起動時も同じ警告が再表示される
• exit 1（エラー）: workflow-state.json の破損等。内容を報告して停止する

Step 1.5: DL 完全性チェック（部分ダウンロード検知）

02-Individual-music/ の実ファイル数を期待曲数と突合する。assets.music_downloaded が true でも本チェックはスキップしない（フラグと実ファイル数が食い違う部分ダウンロード — 例: 10 曲中 5 曲失敗 — を見逃さないため）。

期待曲数・実ファイル数は /suno-helper の DL 完了判定・yt-collection-serve の status 判定と同じロジック（既存ユーティリティ）で算出し、算式を二重管理しない:

python3 -c "
from pathlib import Path
from youtube_automation.utils.suno_downloaded_workflow_state import read_pattern_count, expected_download_count
from youtube_automation.utils.suno_downloaded_archive import count_audio_files
from youtube_automation.utils.collection_paths import CollectionPaths

coll_dir = Path('.')  # アクティブなコレクションディレクトリで実行
pattern_count = read_pattern_count(coll_dir)
expected = expected_download_count(pattern_count)
actual = count_audio_files(CollectionPaths(coll_dir).music_dir)
print(f'pattern_count={pattern_count} expected={expected} actual={actual}')
"

• pattern_count: 20-documentation/suno-prompts.json の entry 数
• expected（期待曲数）: pattern_count × 2。Suno は 1 Generate = 2 clip を生成するため、インスト / ボーカルいずれのモードでも共通の算式（ボーカルモードの 1 曲 1 winner 採用は Step 4.5 の後段処理であり、ダウンロード完了判定には影響しない）
• actual（実ファイル数）: 02-Individual-music/ 内の .mp3 / .m4a / .wav ファイル数

判定:

• actual == 0: /suno-helper 未実行として「/suno-helper を実行してダウンロードを完了してください」を案内して停止
• 0 < actual < expected: 部分ダウンロードとして扱う。assets.music_downloaded が true であっても揃っているとはみなさない。不足曲数（expected - actual）を提示し、「/suno-helper を再実行して不足分を DL するか、Suno UI から手動で不足曲をダウンロードして 02-Individual-music/ に配置してください」を案内して停止
• 定期実行の extension state が checkpoint / manual-intervention / running の場合も、実ファイル数・planning.music.suno_playlist_url・assets.music_downloaded が揃うまでは停止する。extension state の completed は補助情報であり、この実ファイル突合を代替しない
• actual >= expected: チェック OK として Step 1.6 へ進む

pattern_count が None（suno-prompts.json が存在しない）の場合は期待曲数が算出不能なため本チェックをスキップし、以降の既存フローに委ねる。

Step 1.6: playlist × suno-prompts.json 突合ゲート（必須・混入検出）

Step 5 前の共通ゲート: この突合は Step 2 fallback 専用ではない。02-Individual-music/ に音源があり Step 2-3 をスキップする primary path でも、Step 5 に進む前に必ず完了させる。

primary path では 02-Individual-music/ のローカルファイル名を第一手段とし、下記 CLI を実行する。--music-dir の相対パスは <collection-path> 基準で解決する。外部の title list 解決や対話確認は行わない。非正準形ファイル（Suno UI 手動 DL 由来の Title.mp3 / Title (1).mp3 / Title_1.mp3 等）は CLI が suno-prompts.json と照合して正準形 NN{a|b}-Title.ext へ自動リネームしてから突合する。照合できないファイルはリネームされず unknown として報告される。playlist URL の記録有無に依らず本ゲートは完走できる — 「Suno playlist URL がないため suno-prompts.json との突合ができません」型の停止は誤り。title list 提示 / 混入込み続行の 2 択分岐は 02-Individual-music/ に音声ファイルが 1 件も無い場合の最終 fallback に限る。

# primary path: 02-Individual-music/ の <2桁以上のentry index>{a|b}-<title>.<ext> を直接突合
uv run yt-suno-verify-playlist <collection-path> --music-dir 02-Individual-music

fallback path（Step 2-3 で DL する場合）は従来どおり Step 2 の WebFetch 結果から title list を作り、--titles または --titles-file で突合する。

判定:

• unknown（どの entry にも一致しない曲）: 別コレクション由来の混入。playlist から除外するまで Step 5 に進まない
• missing（playlist に存在しない entry）: 生成漏れ。/suno-helper で追補生成するまで Step 5 に進まない
• underfilled（clip 数が期待未満の entry）: 生成が途中で止まった疑い。既定は 2 clip/entry（--expected-clips-per-entry で調整、0 で無効化）
• 非 0 終了時はレポートをそのままユーザーへ提示して停止する。ユーザーが混入込みでの続行を明示指示した場合のみ、混入内容と影響（世界観不整合・メタデータずれ）を報告した上で続行できる

背景: playlist には「最新セットの生成が未完のまま、前後コレクションの曲が混入する」事故が繰り返し起きている（実例: 深夜コレクションに昼テーマ 2 ペアが混入 + 深夜 2 entry 未生成のまま master 化）。曲名は /suno-helper が Song Title 欄へ注入する entry.title ?? entry.name で一意なため、機械突合で確実に検出できる。silent な続行は禁止。

Step 2: WebFetch でプレイリスト情報を取得 (DEPRECATED -- fallback only)

suno-helper DL 済みの場合はスキップ: 02-Individual-music/ ディレクトリにオーディオファイル（mp3 / m4a / wav）が既に存在する場合、suno-helper が一括ダウンロード済みと判断し、Step 1.6 の突合ゲート完了後に Step 2-3 をスキップして Step 5 へ進む。この経路が primary path であり、以下の WebFetch + CDN curl は suno-helper のダウンロードが使えない場合のフォールバックとしてのみ使用する。

1. 引数のプレイリストURLを WebFetch で取得
2. prompt で全曲の情報を抽出するよう指示。プレイリスト全体の総曲数（メタ表記）も同時に取得する:
   • プレイリスト総曲数（HTML 内の song_count / songs · NN tracks / NN songs 等のメタ表記。必須）
   • 各曲のタイトル
   • 各曲の Song ID（UUID）
   • 各曲の再生時間
3. 件数突合チェック（必須・silent な取りこぼし禁止）:
   • WebFetch 結果から len(songs) を数え、ステップ 2 で取得した「プレイリスト総曲数」と突合する
   • 不一致なら処理を中断し、ユーザーへ次のメッセージで報告する:

     ⚠️ プレイリスト総曲数 (N) と取得件数 (M) が一致しません。WebFetch は suno.com のサーバー描画分（50 曲まで）しか見えないため、51 曲目以降は遅延読み込みで取りこぼされます。 対処: (a) プレイリストを 50 曲以下に分割して再実行 / (b) 全件を手動で 02-Individual-music/ に揃えてから uv run yt-generate-master を直接実行

   • 総曲数のメタ表記が WebFetch から取得できなかった場合も同様に中断し、ユーザーへ「件数突合不能のため処理を停止」と報告する（silent な続行を禁止）
   • 総曲数 ≤ 50 で件数が一致した場合のみ Step 3 へ進む
4. WebFetch の結果から曲リストをパースして Step 3 に渡す
5. Step 1.6 の突合ゲートが未実行なら、この曲リストで yt-suno-verify-playlist を実行してから Step 3 に進む

取得手段のフォールバック方針: WebFetch は suno.com のサーバー描画分（上限 50 件）しか拾えないため、本 skill は「50 曲以下のプレイリスト」を前提運用とする。50 曲超のプレイリストは現状 50 曲単位に分割して個別実行するか、手動で 02-Individual-music/ に MP3 を揃えてから uv run yt-generate-master を直接実行するワークフローへ切り替える（内部 API / 公式 API への移行は別 issue）。

Step 3: MP3 ダウンロード（CDN curl）(DEPRECATED -- fallback only)

suno-helper DL 済みの場合はスキップ: Step 2 と同様、02-Individual-music/ にファイルが存在すれば本ステップはスキップ。

各曲について:

1. Song ID または Suno ショート URL（https://suno.com/s/<slug>）を UUID に正規化
2. UUID から CDN URL を生成: https://cdn1.suno.ai/{song_id}.mp3
3. curl でダウンロードし 02-Individual-music/ に保存
4. ファイル名: 連番 + タイトルから生成（例: 01-pattern-a-arrival.mp3）

Suno ショート URL の UUID 解決:

song_id 欄に https://suno.com/s/<slug> が入っている場合は、リダイレクト先 URL から UUID を抽出してから CDN URL を組み立てる。解決できない場合は当該曲をスキップせず、原因を表示して処理を停止する（silent な欠落禁止）。

resolve_suno_song_id() {
  local input="$1"
  local uuid_re='[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'

  if echo "$input" | rg -qi "^${uuid_re}
quot;; then
    echo "$input"
    return 0
  fi

  if echo "$input" | rg -qi '^https://suno\.com/s/[^[:space:]]+
#x27;; then
    local final_url
    final_url="$(curl -sI -L -o /dev/null -w '%{url_effective}' "$input")"
    if echo "$final_url" | rg -qio "$uuid_re"; then
      echo "$final_url" | rg -o "$uuid_re" | tail -1
      return 0
    fi
    echo "ERROR: Suno ショート URL から UUID を解決できません: $input (final_url=$final_url)" >&2
    return 1
  fi

  echo "ERROR: Song ID は UUID または https://suno.com/s/<slug> で指定してください: $input" >&2
  return 1
}

入力値のサニタイズ（必須）:

• Song ID: UUID v4 形式（xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx、hex + hyphen のみ）であることを検証する。正規表現: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$（case-insensitive）。不一致なら当該曲をスキップし警告を出す（シェルインジェクション防止）
• ファイル名 slug: タイトルから生成するファイル名は英数字・ハイフン・アンダースコアのみ許可し、それ以外の文字は - に置換する（tr -cs 'a-zA-Z0-9_-' '-'）。先頭・末尾の - は除去する

# song_id の UUID 正規化・検証（各曲ループ内で実行）
song_id="$(resolve_suno_song_id "$song_id")" || exit 1

if ! echo "$song_id" | rg -qi '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
#x27;; then
  echo "SKIP: invalid song_id format: $song_id"
  continue
fi

curl -fSL \
  --retry "${RETRY_COUNT:-3}" --retry-delay "${RETRY_DELAY:-2}" \
  -w '\n[DL] %{filename_effective}: HTTP %{http_code}, type=%{content_type}, %{size_download} bytes, %{speed_download} B/s\n' \
  -o "02-Individual-music/{filename}.mp3" \
  "https://cdn1.suno.ai/{song_id}.mp3"

RETRY_COUNT / RETRY_DELAY は skill-config の suno_download.retry_count / suno_download.retry_delay_seconds から読み込む（既定 3 / 2）。

各フラグの意味:

• -f (--fail): HTTP 4xx/5xx でゼロバイトファイルを残さず即座に失敗扱いにする
• -S: -f と組み合わせてエラー詳細を stderr に出力
• --retry N --retry-delay N: 一時的な CDN エラー時にリトライ（skill-config で調整可能）
• -w: ダウンロード結果（HTTP status, Content-Type, サイズ, 速度）をログ出力

Content-Type 検証: -w 出力の %{content_type} が audio/mpeg でない場合（例: text/html — CDN がエラーページを返した）、そのファイルは破損扱いとして検証失敗リストに追加する。

ダウンロード後の検証（全曲完了後に一括実行）:

failed=()
for f in 02-Individual-music/*.mp3; do
  size=$(stat -f%z "$f" 2>/dev/null || echo 0)
  if [ "$size" -lt 10000 ]; then
    echo "⚠️  $f: サイズが異常に小さい (${size} bytes) — 部分ダウンロードの可能性"
    failed+=("$f")
    continue
  fi
  duration=$(afinfo "$f" 2>/dev/null | grep "estimated duration" | awk '{print $3}')
  if [ -z "$duration" ] || [ "$(echo "$duration < 5" | bc)" -eq 1 ]; then
    echo "⚠️  $f: 再生時間が異常 (${duration:-N/A} 秒) — ファイル破損の可能性"
    failed+=("$f")
  fi
done
if [ ${#failed[@]} -gt 0 ]; then
  echo "❌ ${#failed[@]} ファイルの検証に失敗:"
  printf '  - %s\n' "${failed[@]}"
  echo "→ 手動で Suno UI から再ダウンロードするか、Song ID を確認して curl を再実行してください"
else
  echo "✅ 全ファイル検証 OK"
fi

期待ファイルとの突合チェック（必須）:

ダウンロード・検証ループの後、Step 2 で取得した曲リスト（期待トラック一覧）と 02-Individual-music/ の実ファイルを突合する:

# expected_files: Step 2 の曲リストから生成したファイル名配列
# actual_files: 02-Individual-music/*.mp3 の basename 配列
missing=()
for expected in "${expected_files[@]}"; do
  if [[ ! -f "02-Individual-music/$expected" ]]; then
    missing+=("$expected")
  fi
done
if [ ${#missing[@]} -gt 0 ]; then
  echo "MISSING ${#missing[@]} files (expected from playlist but not on disk):"
  printf '  - %s\n' "${missing[@]}"
fi

期待ファイルが 1 件でも欠けている場合は検証失敗として扱い、Step 5 へ進まない。

検証が失敗した場合: 該当ファイルを削除し、curl を再実行する。3 回リトライしても失敗する場合は CDN 障害の可能性が高いため、手動で Suno UI からダウンロードして 02-Individual-music/ に配置するフォールバックに切り替える。

注意: CDN URL は public だが永続性は不明。生成後なるべく早めにダウンロードすること。1ファイル約2-3MB。

Step 4: 結果レポート

以下の表形式で全トラックの状態を一覧表示する:

| # | Filename                      | Size (MB) | Duration (s) | Status |
|---|-------------------------------|-----------|--------------|--------|
| 1 | 01-pattern-a-arrival.mp3      |      2.8  |       120.3  | OK     |
| 2 | 02-pattern-a-departure.mp3    |      3.1  |       135.7  | OK     |
| 3 | 03-pattern-b-drift.mp3        |      0.0  |          -   | FAIL: size < 10KB |

表の後にサマリー行を出す:

• Total: N files, XX.X MB
• OK: N / FAIL: N / MISSING: N
• 検証失敗または欠落がある場合は明示的に Step 5 をブロック中 — 上記の FAIL / MISSING を解消してください と表示

Step 4.5: Suno clip 採用整理（歌詞-aware + 尺フィルタ）

uv run yt-generate-master の直前に uv run yt-suno-select-tracks を実行し、02-Individual-music/ を master 入力として安全な状態に整理する。

本実行でファイル移動・削除が発生する前に、必ず dry-run で pair_selection.min_song_sec 未満の候補を確認する:

uv run yt-suno-select-tracks --dry-run <collection-path>

dry-run stdout の [dropped_under_min] セクションに 1 件以上ある場合は、各行の source=<filename> / duration=<sec>s / min_song_sec=<sec>s をユーザーへ提示し、続行可否を確認する。Claude Code では AskUserQuestion で「続行する」「続行しない」の 2 択を出す。AskUserQuestion 非対応環境（Codex 等）では、同じ情報をテキストで提示し、ユーザーの明示的な承認発言を待つ。

• 続行する: 下記の本実行へ進み、既存の pair_selection.out_of_range_action に従って除外する。その後 Step 5 へ進む
• 続行しない: 本実行を行わず、/suno-helper での追補生成または該当曲の手動確認を案内して停止する。Step 5 へ進まない
• [dropped_under_min] に候補が無い場合: 確認プロンプトを出さず、下記の本実行へ進む。pair_selection.max_song_sec 超過だけの候補では、この確認プロンプトを出さない

uv run yt-suno-select-tracks <collection-path>

この CLI は 20-documentation/suno-prompts.json と 02-Individual-music/ の音源を読み、pair_selection.* / stock.* 設定に従って以下を実行する:

1. 尺フィルタを先に適用:
   • pair_selection.min_song_sec 未満の極端に短い曲を除外
   • pair_selection.max_song_sec 超過の極端に長い曲を除外
   • 既定は 45 <= duration <= 300 秒
   • max_song_sec: 300 は 5 分超の崩れた Suno 生成を混ぜないための既定値。チャンネル側の config/skills/masterup.json 優先、既存 masterup.yaml fallback で pair_selection.max_song_sec を明示的に上書きできる
   • 除外曲は pair_selection.out_of_range_action に従い、既定では assets/stock/music/b-side/ へ退避する
   • 除外後にある prompt の採用候補が 0 件になった場合は fail-loud。基本は /suno-helper で追補生成してから再実行する
2. 歌詞あり（vocal / lyrics あり）:
   • suno-prompts.json の lyrics に実歌詞がある entry は、同じ prompt から生成された clip 群のうち 1 曲だけを winner として採用
   • winner は 02-Individual-music/<NN>-<title>.<ext> に rename
   • loser は assets/stock/music/b-side/ へ退避
   • winner 選定は pair_selection.strategy: random。seed は pair_selection.random_seed、未指定なら自動生成して 01-master/.selection.log に記録する
3. 歌詞なし（instrumental / lyrics なし）:
   • 同じ prompt から生成された 2 clip は両方採用する
   • 尺フィルタで落ちた clip だけ除外し、残った clip は 01a-... / 01b-... のまま uv run yt-generate-master に渡す

lyrics が [Instrumental] / [Extended Outro] などタグだけの場合は歌詞なしとして扱う。選別ログは pair_selection.selection_log_path（既定 01-master/.selection.log）に残す。

max_song_sec 超過だけで全落ちした場合の復旧:

この復旧は例外採用の承認を必要とし、非 dry-run の CLI が workflow-state.json::music_pair_selection と updated_at を更新する。subagent へは委譲せず、対象 prompt・候補・duration を提示して承認を得た後、メインエージェントが次のコマンドを実行する。

uv run yt-suno-select-tracks <collection-path> --allow-best-effort-over-max

このフラグは、ある prompt の全候補が pair_selection.max_song_sec 超過だけで落ちた場合に限り、最短の候補を 1 曲だけ警告付きで例外採用する。短すぎる音源（min_song_sec 未満）や probe 失敗は壊れた生成として引き続き fail-loud。例外採用した候補は 01-master/.selection.log の [exceptions_over_limit] と workflow-state.json::music_pair_selection.exceptions_over_limit に、対象ファイル・duration・理由付きで記録される。

安全契約:

• pair_selection.selection_log_path は collection dir 配下の相対パスのみ許可する。絶対パスや .. は fail-loud
• stock.dir はチャンネルルートの assets/stock/ 配下の相対パスのみ許可する。既定は assets/stock/music/b-side/
• stock.filename_template の placeholder は collection_slug / song_id / title_slug / ext のみ。生成ファイル名は basename のみ許可する
• stock.on_duplicate は skip / overwrite / fail のみ。fail と不正設定はファイル移動・削除・rename・log 書き込み前に停止する
• 対応音声拡張子（.mp3 / .m4a / .wav）で命名規則に合わないファイルが 02-Individual-music/ にある場合は、後段 uv run yt-generate-master への混入防止のため fail-loud
• 全検証が通るまでファイル移動・削除・rename・log 書き込みは行わない。非 0 終了時は入力音源を再実行可能な状態に残す

dry-run:

uv run yt-suno-select-tracks <collection-path> --dry-run

ファイル移動なしで winner / loser / 尺外除外の plan を stdout に出す。[dropped_under_min] には pair_selection.min_song_sec 未満で除外される候補だけが、ファイル名・duration・設定中の min_song_sec 付きで表示される。

Step 5: マスター音源生成（CLI）

前提条件（検証ゲート）: Step 3〜4.5 の検証が 全件 OK である場合にのみ本ステップを実行する。以下のいずれかに該当する場合は Step 5 を実行してはならない（不完全な master.mp3 の生成を防止）:

• Step 3 の検証で failed 配列が空でない（サイズ異常・再生時間異常・Content-Type 不正）
• 期待ファイル突合チェックで missing 配列が空でない
• Step 2 の件数突合で不一致が検出されている
• Step 1.6 の uv run yt-suno-verify-playlist が未実行、検証不能、または非 0 終了している（混入 / 生成漏れ / clip 不足。ユーザーが混入込み続行を明示指示した場合を除く）
• Step 4.5 の uv run yt-suno-select-tracks が非 0 終了している（尺フィルタ後の採用候補 0 件、stock 移動失敗など）

検証失敗時は Step 4 / 4.5 のレポートを提示し、ユーザーに手動修正（再ダウンロード / Suno UI からの手動取得 / /suno-helper 追補生成）を促してから再実行する。

Step 5.0: Suno 個別音源の音質補正（任意 / config opt-in）

post_processing.suno_audio_cleanup.enabled: true のチャンネルでは、マスター結合前に 02-Individual-music/ の各 Suno 音源へ ffmpeg 後処理を適用する:

uv run yt-suno-audio-cleanup plan <collection-path>   # まず対象と ffmpeg filter を確認
uv run yt-suno-audio-cleanup apply <collection-path>  # 元ファイルを originals-pre-cleanup/ に退避して同名置換

適用内容:

• 冒頭無音カット (silenceremove)
• 350Hz 付近のもやつき / 8kHz 付近のシャリつきを軽く抑える EQ
• 曲中の音量ムラを dynaudnorm で緩和
• alimiter による瞬間ピーク抑制
• 既定 -14 LUFS の loudnorm
• 後半崩れの被害を抑える末尾 fade-out guard

enabled: false（既定）の場合は何もしない。ユーザーが単発で試したい場合は --force を付けて plan/apply できる。既に backup があるファイルは二重処理を避けるため skip される（再処理する場合も --force）。

Step 5 本体: マスター結合の実行

ダウンロード完了後、uv run yt-generate-master CLI でマスター音源を自動生成:

uv run yt-generate-master                          # CWD がコレクションディレクトリのとき
uv run yt-generate-master <collection-path>        # 明示指定
uv run yt-generate-master --loop 3                 # 全トラックを 3 回繰り返して結合
uv run yt-generate-master --target-duration 150    # 150 分以上になる最小ループ回数を自動算出
uv run yt-generate-master --bitrate 256k           # skill-config の audio.bitrate より優先
uv run yt-generate-master --crossfade-duration 1.5 # skill-config の audio.crossfade_duration より優先
uv run yt-generate-master --shuffle                # ループ展開前にトラック順をランダム化
uv run yt-generate-master --shuffle-seed 42        # 再現性 seed 指定（--shuffle を暗黙有効化）
uv run yt-generate-master --pin-first 00-hook.mp3 --shuffle           # 指定 1 曲を先頭固定 + 残りシャッフル
uv run yt-generate-master --pin-first-count 1 --shuffle               # ソート済み先頭 1 件を固定 + 残りシャッフル

02-Individual-music/ のオーディオファイル（MP3 / M4A / WAV）を自動検出し、skill-config の audio.crossfade_duration / audio.bitrate でクロスフェード結合します。CLI の --crossfade-duration / --bitrate は skill-config より優先し、--crossfade-duration が 0 以下なら validation error で停止します。metadata_generator のタイムスタンプ計算と同じ設定値を参照するため、実音声と description のタイムスタンプが常に一致します。suno-helper の DL フォーマット設定（sunoDownloadFormat）により入力形式が MP3 以外になる場合があるため、拡張子で判別する。 この処理は常にダウンロード後（または suno-helper DL 済み確認後）に自動実行する。

ループ時の注意: --loop / --target-duration は Suno/Lyria のトラック数が少ないコレクションで raw master の尺を target に届かせるためのオプション。--loop / --target-duration / --no-loop は同時指定不可。実行前にトラック総尺・目標尺・ループ回数・見込み尺の preview が表示される。--no-loop は config/skills/masterup.json::audio.target_duration_min（既存 masterup.yaml fallback）が設定されていても 1 パス生成を明示するためのフラグ。全ループ分の YouTube チャプターが必要な場合は、preview の loop count と同じ N を metadata_generator.generate_timestamps(loops=N) / format_timestamps_text(loops=N) に渡して展開する。1 ループ分のみ載せる従来運用は loops=1 のままで変更なし。

シャッフル時の注意: --shuffle はループ展開の前に 1 回だけ実行され、シャッフルされた順序がループごとに同じ並びで N 回繰り返される（ループごとに独立してシャッフルし直すわけではない）。再現性が必要な場合は --shuffle-seed N を指定するか、--shuffle 単独実行時に stdout に出る [Shuffle] seed=<N> の値を控えておけば後で同じ並びを再現できる。再現性ログは --quiet 指定時も常に出力される。

先頭固定時の注意: --pin-first <files...> は引数順を保持して先頭に固定する。--pin-first-count N は 02-Individual-music/ のソート済み先頭 N 件を固定する。両者は mutually exclusive（同時指定で argparse エラー）。--shuffle 併用時は pin された曲は順序固定のまま、残りのみシャッフルされる（要件: retention に強いフック曲を冒頭に置きつつ後半の類似イントロクラスタ化を回避）。--target-duration / --loop 併用時もループ展開の前段で先頭固定処理が適用される。--pin-first 指定ファイルが 02-Individual-music/ に存在しない場合は fail-loud で停止する。スキル設定 audio.pin_first_count を 1 以上にしておけば、CLI フラグなしでもチャンネル単位のデフォルトとして自動適用される。

Step 5.5: ambient レイヤー整音（オプション）

branding/<dirname>/<glob> 配下に該当ファイルを持つチャンネルでは、マスター生成後に環境音 (雨音など) をレイヤーする:

uv run yt-finalize-master                       # CWD がコレクションディレクトリ
uv run yt-finalize-master <collection-path>     # 明示指定

既定では branding/rain_layers/rain_*.wav を探索（既存 v5.5.0 互換）。branding/rain_layers/ ディレクトリが無い／rain_*.wav が 0 件のチャンネルでは何もせず exit 0（pass-through）。master.mp3 は master.tmp.mp3 経由 atomic rename で in-place 上書きされる（pass2 失敗時は元 master が保護される）。

skill-config 設定マトリクス (audio.finalize.*)

uv run yt-finalize-master の音響パイプラインは全項目を skill-config から注入できる（#512）。 すべて任意キーで、未指定時は組み込みデフォルトが既存 v5.5.0 と同じ挙動を再現する。

Fail-loud ルール:

• loudnorm.mode: dynamic → NotImplementedError（two-pass linear 専用設計の明示）
• loudnorm.mode がその他不正値 / mix.duration 不正値 / mix.normalize 範囲外 / layers が dict 以外 → ConfigError
• layer_overrides 長と layer 数の不一致（内部契約） → ValidationError

per-file 上書き設定例

audio:
  finalize:
    ambient_layers:
      volume_db: -19            # 全 layer 共通
      fadein_s: 0.5
      layers:
        rain_001.wav:
          volume_db: -22         # この 1 ファイルだけ -22dB で被せる
        rain_002.wav:
          fadein_s: 1.5          # フェードインだけ長くしたい
          fadein_curve: "exp"    # 指数カーブで自然に立ち上げる
    loudnorm:
      enabled: true
      I: -14
      LRA: 11
      TP: -1.5
    mix:
      duration: "first"          # master の長さで切る (環境音は aloop 展開済み)
      normalize: 0               # amix の自動 0.5x スケーリングを無効化

loudnorm.enabled: false（1-pass モード）

整音不要・amix 結果をそのまま出したい場合は loudnorm.enabled: false で ffmpeg の呼び出し回数を 1 回（amix → encode 直行）に短縮できる。pass1 の measure を行わないため処理時間も半分以下になる。

audio:
  finalize:
    loudnorm:
      enabled: false             # pass1/pass2 を skip

旧 rain_layer namespace（DEPRECATED, #512）

旧 v5.5.0 までの rain_layer: namespace は後方互換 alias として読み続けるが、利用するとプロセス起動時に DeprecationWarning が出る。新 audio.finalize.* namespace へ移行すること。新旧両方を同時に書いた場合は新が勝ち、旧は無視される（warning も出ない）。

Step 5.6: 雨レイヤー後処理（config 駆動 / opt-in）

uv run yt-finalize-master が master.mp3 を loudnorm 二段で in-place 上書きするのに対し、uv run yt-apply-rain-layers は raw master と branding/rain_layers/*.wav を amix のみで合成し別ファイル（既定 01-master/master-rain.wav）に書き出す軽い後処理 CLI。後段で外部 DAW のミキシング+マスタリングを挟む運用（raw master を保持したまま雨レイヤー付きバージョンを並行管理したい場合）向け。

この CLI は出力成功時に workflow-state.json::assets.raw_master を更新し、成果物生成だけを行うオプションを持たない。subagent 実行時はこの Step を実行せず、subagent の成果物をメインエージェントが検証して state を更新した後、メインエージェントが次のコマンドを実行する。

uv run yt-apply-rain-layers                       # CWD がコレクションディレクトリ
uv run yt-apply-rain-layers <collection-path>     # 明示指定
uv run yt-apply-rain-layers --dry-run             # ffmpeg コマンドを表示するだけで実行しない

挙動:

• post_processing.rain_layers.enabled: false（既定）→ 何もせず exit 0
• enabled: true だが branding/rain_layers/*.wav が 0 件 → fail-loud（rc=1。レイヤー WAV を配置するか enabled: false にする）
• enabled: true + WAV が在る → ffmpeg で各レイヤーを -stream_loop -1 で master 尺までループ → volume={volume_db}dB で減衰 → amix=duration=first:normalize=0 で master と合成 → pcm_s16le / 44100Hz / stereo の WAV を出力
• 出力成功時に workflow-state.json::assets.raw_master を output_name で上書き（後段の /wf-next などが新出力を参照するため）

uv run yt-finalize-master（rain_layer: namespace）と uv run yt-apply-rain-layers（post_processing.rain_layers: namespace）は独立した opt-in。両方有効化すると master.mp3 への loudnorm 上書きと master-rain.wav の別ファイル出力が両方走るので、片方だけ使う運用を推奨する。

Step 6: ワークツリー実行時のメインへのコピー

git worktree 内で実行している場合、生成したコレクション成果物をメインリポジトリにも同期する。 個別ディレクトリだけコピーする方式は将来ファイル種別が増えるたび漏れが発生するため、コレクションディレクトリ全体を rsync -a で同期する（01-master/・02-Individual-music/・03-Individual-movie/・10-assets/・20-documentation/・workflow-state.json などすべて含む）。

1. ワークツリー検出: git rev-parse --git-common-dir を使う。値が .git または <toplevel>/.git ならメインリポジトリ実行なのでスキップ。
2. メインリポジトリのルートを算出: git_common_dir を起点に git rev-parse --show-toplevel を再実行。
3. ワークツリールートからのカレントコレクション相対パスを使ってメイン側の目的地パスを構築。
4. mkdir -p で目的地を作成し、rsync -a でコレクションディレクトリ全体をコピー。

WORKTREE_COLLECTION="$(pwd)"   # コレクションディレクトリで実行している前提
GIT_COMMON_DIR="$(git rev-parse --git-common-dir 2>/dev/null)"
WORKTREE_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"

if [[ "$GIT_COMMON_DIR" == ".git" || "$GIT_COMMON_DIR" == "$WORKTREE_ROOT/.git" ]]; then
    echo "メインリポジトリで実行中。コピーは不要です。"
else
    MAIN_REPO="$(cd "$GIT_COMMON_DIR" && git rev-parse --show-toplevel)"
    REL_PATH="${WORKTREE_COLLECTION#"$WORKTREE_ROOT"/}"
    MAIN_COLLECTION="$MAIN_REPO/$REL_PATH"
    mkdir -p "$MAIN_COLLECTION"
    rsync -a "$WORKTREE_COLLECTION/" "$MAIN_COLLECTION/"
fi

--delete を付けない理由: メイン側で /thumbnail や /loop-video 等によって先行生成された素材（例: 10-assets/main.png, 10-assets/loop.mp4）が worktree 側に存在しないことがあり、--delete を付けるとそれらが消えてしまう。worktree 側で新規追加されたファイルだけメインに上書き反映する片方向追加同期で十分。

この処理は常にマスター生成後に自動実行する（ワークツリー実行時のみ）。

完了時の更新

• workflow-state.json の assets.raw_master に生成したマスターファイル名（例: "master.mp3"）を記録
• updated_at を現在時刻に更新

phase は "prepared" のまま変更しない。raw_master → master_audio 確定後の "mastered" フェーズ遷移は /wf-next の責務（本スキルはユーザーのミキシング+マスタリング前の raw master 生成までを担う）。

CDN URL パターン (DEPRECATED -- fallback only)

suno-helper の一括ダウンロード機能が primary path。CDN curl は suno-helper が使えない場合のフォールバックとしてのみ利用する。

長時間処理の取り扱い

uv run yt-generate-master（ffmpeg クロスフェード結合）は 30 秒〜2 分 程度かかる。必ず Bash ツールを run_in_background=true で起動する。これによりユーザーは処理中も同じセッションで質問できる（Claude Code は完了時に自動でメッセージ通知するため、sleep ループや until での自前ポーリングは禁止）。Codex など run_in_background 非対応の実行環境では、同コマンドを nohup ... > <log> 2>&1 & で background 起動し、完了はログ末尾で確認する読み替えとする。

spawn 例:

uv run yt-generate-master > /tmp/masterup-$(date +%s).log 2>&1

これを Bash run_in_background=true で投げ、spawn 直後に次のメッセージを返す:

⏳ マスター音源生成を background 実行中（推定 1〜2 分）。完了まで他の質問にもお答えできます。 ログ: /tmp/masterup-*.log

cmux 環境下（$CMUX_WORKSPACE_ID あり）であれば補助で cmux set-status "masterup" "running" --icon "hourglass" --color "#f59e0b"、完了で cmux clear-status "masterup" + cmux notify --title "masterup 完了" を呼ぶ（非 cmux 環境では skip）。

curl での MP3 一括ダウンロード（Step 3）も曲数が多いと数十秒〜分単位かかるため、同じ background パターンで起動してよい。完了通知が届いたらログ末尾から結果サマリー（master.mp3 のパス、ダウンロード成功曲数）をユーザーへ返す。

オーディオビジュアライザー / オーバーレイ

/masterup は音源（mp3 / wav）を作る工程で、映像オーバーレイ（ビジュアライザー・波形・購読ボタンポップアップ等）は扱わない。 ユーザーから「ビジュアライザー付きで」「波形を出して」等の指示があっても、/masterup 段階では何も合成できない。

ビジュアライザー周りの現行仕様は videoup SKILL.md の「オーディオビジュアライザー / オーバーレイについて」節を参照。必要な場合は /videoup 実行前に config/channel/youtube.json::overlays.enabled: true と overlay 詳細設定を用意する。 誤指示の事故防止のため、masterup 着手前に動画にオーバーレイが必要かをユーザーへ確認すること（#646 feedback）。

Next Step

• /videoup で動画生成を実行