setup-environment — 初期セットアップ

いつ使うか（必ず発火する条件）

• ユーザーがこの repo を新しい環境で初めて使うとき
• ユーザーが「セットアップして」「環境構築したい」「install したい」と言ったとき
• npm install 未実行、node_modules/ 欠落、Cannot find module 系 error が出たとき
• ffmpeg / ffprobe が見つからないとき
• GEMINI_API_KEY、GROQ_API_KEY、OPENAI_API_KEY、HF_TOKEN の設定方法を聞かれたとき
• npm run demo や npx tsx scripts/analyze.ts ... が環境要因で失敗したとき

前提条件

• 作業ディレクトリは repo root であること
• 秘密情報は絶対に表示しない。.env.local の値を読み上げたり、返答内に貼り付けたりしない
• .env.local は 絶対に commit しない。作成前に .gitignore に .env.local が含まれているか確認する
• この repo では scripts/analyze.ts が .env.local を先に読み、次に .env を読む
• 詳細な API キー取得手順は references/api-key-guide.md、典型エラーは references/troubleshoot-setup.md を必要時だけ読む

やること（ステップ）

Step 1: 環境チェックを自動実行する

• まず以下を実行し、環境の現在値を取る

node -v
npm -v
ffmpeg -version
ffprobe -version
ffmpeg -hide_banner -filters
which python3
test -f .env.local && echo yes || echo no
test -d node_modules && echo yes || echo no

• 結果は必ず表形式で返す。最低でも 項目 | 現在値 | 期待値 | 状態 を含める
• 確認対象は以下:
  • Node.js バージョン: 22.x 必須（.nvmrc / .node-version と CI に合わせる）
  • npm バージョン: 10.x
  • ffmpeg が実際に起動できること
  • ffprobe が実際に起動できること
  • ffmpeg の subtitles / ass filter が利用できること
  • python3 の存在
  • .env.local の存在
  • node_modules/ の存在
• 次アクションを案内するのは不足項目だけ にする
• Node.js が 22.x 以外なら他の手順に進む前に揃える。目安は nvm install 22 && nvm use 22
• which ffmpeg / which ffprobe だけでは合格にしない。共有 library 欠落などで binary が起動不能な状態を見逃すため、上記の version command の exit code を確認する

Step 2: ffmpeg / ffprobe を入れる

• ffmpeg または ffprobe が無いときだけ実行する
• OS ごとの基本コマンド:

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows (winget または Chocolatey)
winget install ffmpeg
choco install ffmpeg

• インストール後は必ず確認する

ffmpeg -version
ffprobe -version
ffmpeg -hide_banner -filters | grep -E ' (subtitles|ass) '

• binary が存在しても Library not loaded などで起動しない場合は、インストール済み扱いにせず依存 library / ffmpeg package を修復する
• subtitles / ass のどちらかが無い build は burn-in 字幕の render に使わない
• ここで詰まったら references/troubleshoot-setup.md の ffmpeg: command not found を読む

Step 3: npm install を実行する

• node_modules/ が無い、または Cannot find module 系 error が出ているときだけ実行する

npm install

• install が失敗したら、エラーメッセージをそのまま確認したうえで references/troubleshoot-setup.md を読む
• npm install 済みなのに module error が続く場合は、node_modules/ の破損や Node.js version mismatch を疑う

Step 4: API キーと .env.local を整える

• .env.local が無い、または必要なキーが空なら references/api-key-guide.md を読む
• 先に .gitignore を確認し、.env.local が無ければ追加する
• .env.local が無い場合は次のテンプレートを作る

# Required for VLM video understanding (contact sheets, filmstrips, peak detection)
GEMINI_API_KEY=

# Required for Speech-to-Text (Whisper Large v3 Turbo)
GROQ_API_KEY=

# Optional: Alternative STT with built-in diarization
OPENAI_API_KEY=

# Optional: Speaker diarization (pyannote)
HF_TOKEN=

• .env.local が既にある場合は、既存値を消さずに不足行だけ補う
• 必須度はこう扱う
  • GEMINI_API_KEY: 推奨。VLM 映像理解と peak 検出に使う
  • GROQ_API_KEY: 推奨。Groq Whisper STT に使う
  • OPENAI_API_KEY: 任意。OpenAI STT を使う場合だけ必要
  • HF_TOKEN: 任意。pyannote 話者分離を使う場合だけ必要
• キーが足りないときの fallback も必ず伝える
  • GEMINI_API_KEY が無い: scripts/analyze.ts は warning を出して VLM を skip する。明示的に local/degraded path を取りたいなら --skip-vlm
  • GROQ_API_KEY が無く、OPENAI_API_KEY がある: --stt-provider openai
  • GROQ_API_KEY も OPENAI_API_KEY も無い: --skip-stt
  • HF_TOKEN が無い: --skip-diarize
• .env.local の値は返答内に出さない。commit もさせない

Step 5: Python + pyannote を入れる

• これは 話者分離が必要な場合だけ 行う
• 基本コマンド:

python3 -m pip install pyannote.audio torch torchaudio

• HF_TOKEN を .env.local に入れる
• この repo の pyannote bridge は既定で pyannote/speaker-diarization-community-1 を使う。Hugging Face 側で model access の確認が出たら許可する
• Groq STT + 話者分離を使わないなら、この step は飛ばしてよい
• 不要な場合は完全に --skip-diarize で回避できる

Step 6: 動作確認をする

• 素材を書き込む前に、共通 preflight で Node、ffmpeg/ffprobe、字幕 filter、source、作業 disk 容量をまとめて確認する

npx tsx scripts/preflight.ts <素材フォルダパス>

• preflight に fail があれば ingest / render へ進まない
• まず API キー不要の demo を確認する

npm run demo

• demo が通ったら test を流す

npm test

• npm run demo が失敗したら install / Node.js / repo root を見直す
• npm test が失敗したら、環境差分か repo 側不整合かを切り分ける。セットアップ起因の典型例は references/troubleshoot-setup.md を読む
• demo と test が両方通れば「セットアップ完了」と判断してよい

Step 7: 初回 project の作り方を案内する

• セットアップが終わったら、最小の project を作る

mkdir -p projects/my-project

• 素材は ./footage/ など任意の場所に置き、まず analyze を走らせる

npx tsx scripts/analyze.ts ./footage/*.mp4 \
  --project projects/my-project \
  --content-hint "内容の説明"

• キー不足で degraded path を取るなら、必要に応じて --skip-vlm、--skip-stt、--skip-diarize、--stt-provider openai を追加する
• setup 後の skill 連携も案内する
  • 素材理解だけ欲しいなら analyze-footage
  • analysis 後に 01_intent/creative_brief.yaml が無ければ次は design-intent
  • 「素材から rough cut までまとめて進めたい」なら full-pipeline

出力 artifact

• .env.local ただし local-only。絶対に commit しない
• projects/demo/05_timeline/timeline.json ただし npm run demo 実行時
• projects/<project>/03_analysis/* ただし初回 analyze 実行時

注意事項

• .env.local の中身を version control に入れない
• npm run demo は repo root 実行が前提で、API キーは不要
• scripts/analyze.ts の degraded path は品質と引き換え。--skip-vlm では summary / tags / peak_analysis の品質が落ちる
• pyannote は optional。python3 や HF_TOKEN が無くても、--skip-diarize で repo 全体の利用は続けられる
• setup で解決しない failure は troubleshoot-error に引き継ぐ