go-veo-orchestrator

README

🎬 Go Veo Orchestrator

🚀 概要 (About) - 楽曲構成から、文脈の続く動画カット列へ

Go Veo Orchestrator は、Music Recipe（音楽レシピ / 楽曲構成書） から動画カット列を構造化し、Google の動画生成 AI Veo (Vertex AI / Gemini API) へ渡すためのバックエンドオーケストレーターです。

genai-kit の imagegen でカットごとのキーフレームを生成し、VideoRunner adapter を通じて Veo に Prompt / Keyframe / Audio / PreviousVideoURI / Seed を渡します。

video_id を次カットの PreviousVideoURI として引き継ぐことで、Video-to-Video の文脈を保った連続カット生成を行います。

---

✨ 提供機能 (Features)

• 🧬 Consistency Control キャラクター固有 Seed、キーフレーム画像、動きのプロンプト、前カットの VideoID を 1 つの video.GenerationRequest にまとめ、カット間の見た目と文脈を維持します。

• ⏳ Audio-Driven Timeline Logic（音楽主導のタイムライン管理） music_recipe.sections または cuts から duration_sec、start_sec、end_sec を補完し、audio_cue を Veo 用プロンプトへ注入します。

• 🔁 Resumable Video Chain 各 cut は status、video_id、video_url を保持します。生成済みカットは再生成せず、保持済み video_id を次カットの PreviousVideoURI として使用します。 キーフレームも同じ考え方で、keyframe_reference を持つカットは焼き直しません（CutKeyframe.GenerateAndSave）。1 枚生成するたびに保存するため、途中で落ちても失うのは最大 1 枚で、続きから再開できます。焼き直したいカットは keyframe_reference を空にしてから渡します（Cut.ResetGeneration(false)）。

• 🧩 Adapter-Oriented Architecture Veo への実通信は ports.VideoRunner に閉じ込め、オーケストレーション、キーフレーム生成、メタデータ保存を分離しています。Veo API の具体実装はこのリポジトリに含まれません（実装ガイド）。

---

🎬 4つの動画生成ワークフロー (Workflows)

ワークフロー	担当インターフェース	内容
1. Scripting	ScriptRunner	Music Recipe JSON を読み込み、歌詞・section・楽曲展開から、カット割り・カメラワーク・推定秒数を含む Video Recipe を生成。
2. Cut Keyframe Gen	CutKeyframeRunner	各カットのキーフレーム画像を、キャラクター Seed と参照画像を使って生成・保存（GenerateAndSave）。既存キーフレームの局所編集にも対応（EditAndSave）。
3. Video Gen	VideoTimelineRunner + VideoRunner	VideoRequestBuilder が video.GenerationRequest を組み立て、Veo adapter に順次投入。
4. Metadata Publish	VideoPublishRunner	video_id / video_url / status 更新済みの video_music_meta.json を保存。

---

🚦 使い方 (Usage)

workflow.New に依存を渡して *ports.Workflows を組み立て、各 Runner を呼びます。

workflows, err := workflow.New(workflow.ManagerArgs{
	// 5 項目とも必須です。キットはモデル名も画作りの既定値も持ちません。
	Config: ports.Config{
		GeminiModel:            "gemini-3.6-flash",
		ImageModel:             "gemini-3.1-flash-image",
		KeyframeAspectRatio:    "16:9",
		KeyframeImageSize:      "2K",
		KeyframeNegativePrompt: "speech bubble, text, watermark", // 任意
	},
	Reader:      reader, // 台本ソースの取得に使います（画像には使いません）
	Writer:      writer, // 並列保存するため、同時アクセス安全な実装が必要です
	AIClient:    geminiClient,
	VideoRunner: &VeoRunner{}, // 自前の Veo アダプタ
	PromptDeps:  promptDeps,
})
if err != nil {
	return err
}

// キーフレームを生成・保存してから動画を生成します。Video はキーフレームを
// 作りません（保存済みの keyframe_reference を読むだけです）。
if _, err := workflows.CutKeyframe.GenerateAndSave(ctx, recipe, "gs://bucket/jobs/<jobID>/"); err != nil {
	return err
}

videos, err := workflows.Video.Run(ctx, recipe)
if err != nil {
	return err
}

// メタデータの保存は Publish が担当します。動画生成と保存を分けているのは、
// 呼び出し側が生成と保存の間に処理（チェーンの結合など）を挟めるようにするためです。
if _, err := workflows.Publish.Run(ctx, recipe, "gs://bucket/jobs/<jobID>/"); err != nil {
	return err
}

---

📚 ドキュメント

ドキュメント	内容
Music Recipe JSON	入力フォーマット、cuts の自動生成、section_index、video.Cut の構造
設定と差し替え (Config / DI)	ports.Config / ManagerArgs / PromptDeps、キーフレーム生成オプション
Adapter Boundary	ports.VideoRunner の実装ガイドと video.GenerationRequest の契約
Veo 生成モードとカット尺	veo.ClassifyRequest による分類、モード別の対応尺、尺プランナー
レシピ・カットの操作	再開・再生成のヘルパー、部分結果、単一カットのキーフレーム編集
Sentinel Errors	errors.Is で分岐するためのエラー一覧
アーキテクチャ	パッケージ構成、生成と保存の責務分担、シーケンス図

---

🤝 依存関係 (Dependencies)

• shouni/genai-kit - Vertex AI クライアント（gemini）、キーフレーム生成（imagegen）、呼び出しガード（callguard）、楽曲レシピの型（music）。参照画像は gs:// URI のまま Vertex AI へ渡します
• shouni/go-character-kit - キャラクター資産（characters.json）管理
• shouni/go-remote-io - GCS / ローカル対応の読み書き抽象化

📜 ライセンス (License)

このプロジェクトは MIT License の下で公開されています。