editor-video

クライアント別ビデオエディター

人間の編集者のように素材を理解し、正確にカットし、クライアントのルックを適用し、確認して納品するためのエンジンとフロー。このエンジンに独自のスタイルはありません。すべてのビジュアルは clientes/<CLIENTE>/look.py から取得されます。

SKILL_DIR = このスキルのフォルダ。ツール: engine/reel.py, tools/{takes.py, words.py, media.sh}、テンプレートは templates/、スタータールックは looks/。

必要条件（初回確認; 不足しているものはインストール）

• ffmpeg, python3, node/npx · macOS: HDR→SDR および HEIC 写真には avconvert と sips（システム標準）。
• HyperFrames（レンダリングとSFXライブラリ）: npx hyperframes skills update general-video（media-use もインストール）。
• watch（動画の表示/文字起こし、Instagram/TikTok/YouTube のリンクダウンロード（yt-dlp））: スキル watch（github.com/bradautomates/claude-video より）、ローカルエンジン WhisperX（無料）: setup.py --engine local および --backend whisperx。
• whisper CLI（確認用ウィンドウ）: uv tool install --python 3.12 openai-whisper --with setuptools。
• MFA（単語アライメント ±20 ms）: brew install --cask miniforge, conda create -n mfa -c conda-forge montreal-forced-aligner -y, conda run -n mfa mfa model download acoustic spanish_mfa および … dictionary spanish_mfa（他の言語の場合はそのモデル）。

フォルダ構造（作業ベース、例 ~/Documents/VIDEOS/）

clientes/<CLIENTE>/
├── estilo.md      クライアントガイド（templates/estilo.md）— 編集前には必ず読む
├── look.py        スタイルをエンジンオプションに変換したもの（looks/nativo.py または looks/datos.py より）
├── refs/          参照動画 + フレームシート + 分析
├── marca/         ロゴ、カラー、フォント、自社音楽
└── proyectos/<AAAA-MM-DD_名前>/
    ├── crudo/     ユーザー素材 — 絶対に変更・削除しない
    ├── broll/     補助テイク（オプション）
    ├── guion.md   スクリプトまたはメモ（オプション; このプロジェクトでは estilo.md より優先）
    ├── trabajo/   media/（変換済み）, mfa/, gt/, および各動画の config.py + takes.json フォルダ
    └── final/     納品物のみ: <cliente>_<tema>_v1.mp4 · 修正は v2, v3 とし、前のバージョンは削除しない

ユーザーはフォルダを作成しません。「 の新規プロジェクト、素材は にあります」と言うだけで、ここに proyectos/<日付_名前>/ が作成され、crudo が移動されます（ベース外にある場合、移動したくないか事前に確認）。

フロー

0 · 新規クライアント → 参照動画を分析し estilo.md を作成

1. 参照動画を refs/ にダウンロード/読み込む（リンクは watch 経由、yt-dlp 使用）。理想的には約5本。
2. 各動画について測定: フック（最初の3秒）、カット数/分（ffmpeg -vf "select='gt(scene,0.3)',showinfo" → カウント）、字幕（フォントまたは最も近い無料フォント、サイズ、位置、色、ハイライト、アニメーション）、カラー/ルック、カードとアニメーション、サウンド（音楽、SFX、ナレーション）、フレーミング、構成、CTA。フレームシート: fps=16/dur,scale=270:480,tile=8x2。
3. 2本以上の参照動画で確認できたパターンのみで estilo.md（テンプレート）を作成。測定値と推測値は区別。他社のフレーズやブランドをコピーしない。参照動画が矛盾する場合は、どれを優先するか質問。
4. 最も近いスタータールックから look.py を作成し、ガイドに合わせて調整。編集前にガイドとテスト静止画を表示し、承認を待つ。

1 · 生素材を理解する

• estilo.md と guion.md を読む。各ファイルをテスト（ffprobe: 長さ、回転、color_transfer）。
• 各生素材に対して WATCH_WHISPERX_LANGUAGE=es を設定し --out-dir trabajo/watch を付けて watch を実行: 何が言われているか、どのテイクが使えるか、リテイク、絶対にカットしてはいけない部分。この文字起こしが唯一の完全なもの。MFA に再利用。
• スクリプトと照合: スクリプトのどの部分が録画されていないか、またはアドリブか → ユーザーに通知。
• 音声なしの短いクリップが複数ある場合（イベント）: クリップごとにフレームシートを作成し、テーマごとに分類。編集前にグループ分けを提案（テーマ別動画 + 単発 + 全体的なリキャップ）。

2 · メディアを準備

• media.sh video <crudo> trabajo/media/<名前>.mp4 [vertical|horizontal] — HDR（iPhone/DJI）をSDRに1パスで変換、キーフレーム間隔1秒、30 fps。再圧縮は行わない: パスごとにディテールが失われる。
• 写真: media.sh foto <foto> trabajo/media/<名前>.mp4 2.5。アライメント用音声: media.sh audio。

3 · 単語のアライメント（音声あり動画）

• corpus/a.wav + corpus/a.txt（watch からのプレーンテキスト）→ conda run -n mfa mfa align --clean <corpus ABSOLUTE PATH> spanish_mfa spanish_mfa <output ABSOLUTE PATH>（絶対パス必須; --beam なし）。words.py textgrid … words.json および words.py show words.json。
• ~ の付いた単語（1秒以上）はポーズやリテイクを隠している可能性。テキストのない長いギャップは、watch が文字起こししなかったリテイクかもしれない。隔離ウィンドウで確認: オーディオの3～15秒をカットし、whisper --model small --language es --word_timestamps True、words.py whisper … <offset>。ノイズやリテイクがあった場所では、MFA が数秒ずれることがある。

4 · テイクを選択 → takes.json → takes.py

• 各フレーズについて**最良のテイク（通常は最後のテイク）**を選択。リテイク、失敗テイク、フィラーワード、編集者への指示（「これは別の動画にしたい」）、目的に合わないものは削除。最大再生時間を守る。
• スパンは単語の開始位置で指定: (最初の単語の開始, 最後の単語の開始 + 0.2)。終了が最後の単語の開始より前にある場合、最後の単語が切り取られる。word_fix で MFA が誤って配置した単語を修正（隔離ウィンドウのタイミングを使用）。
• テキスト: phrases / words で ASR が誤認識した単語を修正（名前、ブランド: 「Claude」を「Klaus」ではなく、「IA」を「ella」ではなく）。
• python3 $SKILL_DIR/tools/takes.py trabajo/<video>/takes.json trabajo/<video> → 長さと最終テキストを出力。全文を読む: どのセクションの最後の単語も欠けていないこと、切り取られた単語が残っていないことを確認。

5 · 動画を組み立てる

• trabajo/<video>/: config.py（templates/config.py より）、media → ../media（シンボリックリンク）、media.sh sfx trabajo/<video>、hyperframes.json（最低限 {"paths": {"assets": "assets"}}）。
• edit(e) 内: カード/POV/CTA、Bロール、効果音は単語にアンカー（e.word_t(None, "palabra")）。カードは端に配置。ズームすると顔が横に広がる。可視イベントは3秒以内ごとに1つ（不足するとエンジンがオートパンチを挿入）。
• python3 $SKILL_DIR/engine/reel.py trabajo/<video> → npx hyperframes check trabajo/<video>（エラー0; 「大きなファイル/高密度トラック/ネスト」の警告はこのエンジンでは正常）。

6 · レンダリング前に確認

• npx hyperframes snapshot trabajo/<video> --at <t1,t2,…> --no-end -o <ABSOLUTE PATH> を各カード、フック、CTAで実行。確認: 顔を覆うものがない、テキストが不自然に分割されていない、色が正しい、字幕が読みやすい。
• 静止画をユーザーに表示し、承認を待つ（スタイルが既に承認済みで「レンダリングして」と言われた場合を除く）。

7 · レンダリングと納品

• trabajo/<video> 内で npx hyperframes render --quality delivery -o …/raw.mp4 → media.sh final raw.mp4 final/<cliente>_<tema>_v1.mp4（−14 LUFS）。作成した中間の raw.mp4 のみ削除。
• watch --detail transcript で確認: 全文、繰り返しなし。冒頭が「欠けている」ように見える場合は、最初の3秒を whisper で確認（全体の文字起こしでは冒頭が省略されることがある）。

教訓（繰り返さないこと）

• HDR を変換しないと色褪せて見える。avconvert で1度だけ変換する。
• ズームがある場合は4Kで録画: 1080p を13～22%拡大するとぼやける。クライアントに通知。
• 単語数が増えた修正フレーズに同じ時間を割り当てられない: 長さ0の字幕は固着する。
• 画面上のテキストに絵文字を使用するとレンダリングされない場合がある。避ける。
• snapshot -o で相対パスを使用するとプロジェクトの隣に書き込まれる。絶対パスを使用すること。
• 同じファイルを動画の2つの部分で使用する場合は、takes.json で異なるキー（一意のID）を使用する。
• SFX ライブラリをリポジトリにアップロードしない（media-use の Pixabay ライセンス）。media.sh sfx でプロジェクトごとにコピーされる。
• 単一の動画に対するクライアントの修正（例：「07の効果音を消して」）は、その config.py に記述する（SFX = {"card": None, "broll": None, "cut": None} およびカード内の sfx: None）。index.html を編集しない（再構築時に失われる）。