# Setup Environment

> Sets up a video processing project by checking the environment, installing dependencies, configuring API keys, and verifying the setup.

- Skill: `mocchalera/setup-environment` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add mocchalera/setup-environment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mocchalera/setup-environment/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra, Integrations & APIs, Deployment & Release
- Tags: Ffmpeg, Ffprobe, Gemini Api, Groq Api, Nodejs, Npm, Pyannote, Python
- Author: mocchalera (https://skillmd.com/u/mocchalera)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/mocchalera/setup-environment

---

# 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: 環境チェックを自動実行する

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

```bash
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 ごとの基本コマンド:

```bash
# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

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

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

```bash
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 が出ているときだけ実行する

```bash
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` が無い場合は次のテンプレートを作る

```dotenv
# 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 を入れる

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

```bash
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 容量をまとめて確認する

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

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

```bash
npm run demo
```

- demo が通ったら test を流す

```bash
npm test
```

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

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

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

```bash
mkdir -p projects/my-project
```

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

```bash
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 しない**
- `node_modules/`
- `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` に引き継ぐ