go-veo-orchestrator

README

🎬 Go Veo Orchestrator

🚀 概要 (About)

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

Gemini Image Kit を使ってカットごとのキーフレームを生成し、VideoRunner adapter を通じて Veo に Prompt / Keyframe / Audio / PreviousVideoURI / Seed を渡します。Veo API の具体実装はこのリポジトリに含まれず、ports.VideoRunner として差し替える設計です。

video_id を次カットの PreviousVideoURI として引き継ぐことで、Video-to-Video の文脈を保った連続カット生成を行います。生成済みカットは status=generated と video_id / video_url を使ってスキップできるため、途中失敗後の再開にも対応しやすい構造です。

---

✨ コア・コンセプト (Core Concepts)

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

• ⏳ 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 を持つカットは焼き直しません（CutKeyframeRunner.Run / RunAndSave の両方）。焼き直したいカットは keyframe_reference を空にしてから渡します（Cut.ResetGeneration(false)）。

• 🧩 Adapter-Oriented Architecture Veo への実通信は ports.VideoRunner に閉じ込め、オーケストレーション、キーフレーム生成、メタデータ保存を分離しています。

---

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

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

---

⚡ クイックスタート

workflow.New に依存を渡して *ports.Workflows を組み立て、各 Runner を呼びます。VideoRunner が Veo API アダプタの差し込み口です（実装ガイド）。

workflows, err := workflow.New(workflow.ManagerArgs{
	Config: ports.Config{
		GeminiModel: "gemini-3.6-flash",        // 必須
		ImageModel:  "gemini-3.1-flash-image",  // 必須
	},
	HTTPClient:  httpClient,
	Reader:      reader,
	Writer:      writer,
	AIClient:    geminiModel,
	VideoRunner: &VeoRunner{}, // 自前の Veo アダプタ
	PromptDeps:  promptDeps,
})
if err != nil {
	return err
}
defer workflows.Close() // 画像キャッシュの goroutine を止める

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、ports.Cut の構造
設定と差し替え (Config / DI)	ports.Config / ManagerArgs / PromptDeps、キーフレーム生成オプション
Adapter Boundary	ports.VideoRunner の実装ガイドと VideoGenerationRequest の契約
Veo 生成モードとカット尺	ClassifyVeoRequest による分類、モード別の対応尺、尺プランナー
レシピ・カットの操作	再開・再生成のヘルパー、部分結果、単一カットのキーフレーム編集
Sentinel Errors	errors.Is で分岐するためのエラー一覧
アーキテクチャ	パッケージ構成、生成と保存の責務分担、シーケンス図

---

🤝 依存関係 (Dependencies)

• shouni/gemini-image-kit - 静止画・キーフレーム生成コア基盤（参照画像の解決もここが担います）
• shouni/go-gemini-client - Gemini API / Vertex AI クライアント（台本生成の構造化出力に使用）
• shouni/go-character-kit - キャラクター資産（characters.json）管理
• shouni/go-remote-io - GCS / ローカル / HTTP 対応の読み書き抽象化
• shouni/go-http-kit - HTTP クライアント抽象化
• shouni/go-utils - 共通ユーティリティ

📜 ライセンス (License)

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