./kaisetsu-app/README.md

# kaisetsu-app

動画から字幕・解説を自動生成するツールです。Claude Code を使って開発・運用します。

---

## これは何？

- ブラウザで動画をアップロードして、文字起こし + 解説ナレーションを作るアプリ
- 使っている AI: **Gemini**（文字起こし解析・ナレーション生成）/ **Whisper**（音声→テキスト、OpenAI API）/ **ElevenLabs**（テキスト→音声）
- 本番は Google Cloud Run にデプロイされていますが、**ローカル開発にはクラウド不要**（ファイルは自分の Mac に保存されます）
- Whisper も **OpenAI API 経由**なので Python / mlx のローカルインストール不要

中身のコードを触らなくても、Claude Code に「こうして」と頼めば開発できます。

---

## 最初の1回だけやること

### 1. 必要なツールをインストール

Mac のターミナルで、以下を貼り付けて実行。

```bash
brew install node                    # アプリを動かすエンジン
brew install --cask 1password-cli    # パスワードを安全に取り出すツール
brew install ffmpeg                  # 動画から音声を抽出するツール
```

すでに入ってたら「already installed」と出るだけなので気にしなくてOK。

### 2. 1Password にサインイン

```bash
op signin
```

自分の Quintia アカウント（`xxx@quintia.co.jp`）を選んで Master Password を入力。まだアカウントが無い / `quintia.1password.com` が一覧に出てこない場合は先に 1Password のデスクトップアプリから Quintia チームにサインインしておく。

### 3. このプロジェクトを開発できる状態にする

プロジェクトのフォルダに移動してから：

```bash
bash scripts/setup-dotenv-key.sh
source ~/.zshrc
```

これだけで：

- ✅ 1Password から復号キーを取得
- ✅ Mac の設定ファイル（`~/.zshrc`）に書き込み
- ✅ git の pre-commit フック（秘密情報をうっかりコミットしない仕組み）を有効化

> **何をしてる？** API キーは暗号化されて `.env.local` に入っています。解読するには復号キーが必要。そのキーを 1Password に保管してあり、スクリプトがそれを取り出して `~/.zshrc` に書きます。

### 4. アプリの依存ライブラリをインストール

```bash
cd kaisetsu-app
npm ci
```

1〜2分かかります。

### 5. 起動！

```bash
npm run dev
```

ブラウザで http://localhost:3000 を開くとアプリが見えます。

---

## 開発するとき

### Claude Code への頼み方（例）

- 「トップページのボタンの色を青にして」
- 「動画アップロードの進捗バーを追加して」
- 「/api/tts でエラーが出たときのログをもっと詳しく出して」
- 「voices.csv に新しい声を追加するボタンを作って」

Claude はこの README やコードを読んで、必要な変更をやってくれます。変更後は `npm run dev` で動作確認 → OK ならコミットをお願いしましょう。

### 動画ファイルはどこに保存される？

ローカル開発時は `kaisetsu-app/.data/` に保存されます（クラウドに上げない）。
容量が気になったら `rm -rf kaisetsu-app/.data/` で全削除してOK。

---

## 用語集

| 用語 | 意味 |
|---|---|
| `.env.local` | アプリの設定値（API キーなど）。**秘密情報は暗号化済み**なのでコミットしてOK |
| `.env.keys` | 復号キー本体。**絶対にコミット禁止**。1Password が本拠地でローカルには置かない |
| `QUINTIA_DOTENV_PRIVATE_KEY` | その復号キーが入る環境変数の名前（`~/.zshrc` に書かれるやつ） |
| `.data/` | ローカル開発時の動画＆ジョブファイル置き場。gitignore 済み |
| 1Password CLI (`op`) | 1Password の中身をコマンドで取り出すツール |
| Cloud Run | Google Cloud でアプリを動かすサービス（本番のみ） |

---

## よくあるトラブル

### `npm run dev` で `MISSING_PRIVATE_KEY` や `could not decrypt` と出る

復号キーがセットされてません。ターミナルで：

```bash
source ~/.zshrc
```

それでもダメなら setup をやり直し：

```bash
bash scripts/setup-dotenv-key.sh
source ~/.zshrc
```

### `op: command not found`

1Password CLI が未インストール。`brew install --cask 1password-cli`。

### 1Password でログインが切れた

```bash
op signin
```

### コミット時に「contains a plaintext secret」で止まる

秘密情報（API キーなど）が暗号化されずにステージされています。意図的でなければ：

```bash
cd kaisetsu-app
npx dotenvx encrypt -f .env.local
git add .env.local
git commit
```

### 新しい秘密情報（API キーなど）を追加したい

Claude に「ELEVENLABS_API_KEY を値 xxx で追加して暗号化して」のように頼めばやってくれます。手動でやるなら：

```bash
cd kaisetsu-app
echo "NEW_KEY=値" >> .env.local
npx dotenvx encrypt -f .env.local
```

---

## 裏側の仕組み（興味があれば）

- **Storage backend**: `.env.local` の `STORAGE_BACKEND` で切替
  - `local` → `.data/` ディレクトリに保存（デフォルト）
  - `gcs` → Google Cloud Storage
- **Whisper backend**: `WHISPER_BACKEND` で切替
  - `openai` → OpenAI Whisper API（デフォルト、インストール不要）
  - `mlx` → `mlx_whisper` CLI（Apple Silicon、要 `pipx install mlx-whisper`）
  - `cpu` → `whisper` CLI（要 `pipx install openai-whisper`）
- **Gemini**: `GEMINI_API_KEY` があれば AI Studio API、無ければ Vertex AI（本番）

## 本番デプロイ

現時点でデプロイ設定はリポジトリにありません（ローカル開発専用）。必要になったら別途ホスティングを用意してください。コードは `STORAGE_BACKEND=gcs` に切り替えれば Cloud Storage + Vertex AI 経由で動くようにはなっています。

---

## 困ったら

- インフラ・環境周り: Claude Code に README を見せて相談
- ビジネスロジック: `src/` 以下のコードを Claude に読んでもらって相談
- それでもダメなら開発チームに Slack で連絡