visant-video-editor

Visant Video Editor

必要条件

必要な用途	内容	確認方法
すべて	bash 3.2 以上を備えた Windows（Git Bash）、macOS または Linux	bash --version
すべて	PATH 上に ffmpeg と ffprobe（libx264、aac、コンタクトシート用の drawtext）	ffmpeg -version
plan.py、transcribe.sh	Python 3（PYTHON= でインタープリターを指定）	python --version
transcribe.sh	faster-whisper（pip install faster-whisper）	python -c "import faster_whisper"
テイク内の無音部分（任意）	auto-editor（pip install auto-editor）	auto-editor --version
実際の撮影日（任意）	exiftool	exiftool -ver

Node も GUI アプリも不要です。それ以外はすべて POSIX シェルと awk です。 ツールを追加する前にreferences/tools.mdを確認してください。

できること

素材フォルダーから vlog を組み立てます。素材はスマートフォンで撮影された映像で、ファイル数は数十から数百、テイクの長さは 1～120 秒、向きは混在し、クリップごとに音量が 20 LU 変動します。

互いに置き換えることのない 2 つの要素があります。

1. ゲート（scripts/self-test.sh、決定論的）：パイプラインは動画全体を出力するか、何も出力しません。合否判定です。
2. 判断（内訳を読むあなた）：どのテイクを、どの順番で、どの長さ使うか。これをうまく決めるスクリプトはありません。

最初のルール：エンコード前にカットリストの承認を得てください。 クラウドドライブ上の素材 25 分をエンコードするには 1 時間かかります。カットリストをテキストで提案するだけなら数秒です。ユーザーが「そのままやって」と明示していない限り、ユーザーがカットリストを確認する前にマスターをレンダリングしないでください。

ゲートが合格しても、動画を視聴したことにはなりません。 ゲートで確認できるのは、カットが失われておらず、音声が目標に達していることです。冒頭が良いか、適切なテイクが選ばれているかは確認できません。完成したと伝える前に、必ずコンタクトシートを開いてください。

作業を始める前に

bash scripts/self-test.sh

約 2 分で、生成したフィクスチャを使って独立したサンドボックス内で実行できます。ゲートが閉じている間はクライアントの動画を編集しないでください：ここで扱う失敗はすべて、誤った動画でも終了コード 0 を返す、気づきにくいものです。パイプラインのスクリプトを変更した場合は、もう一度実行してください。

手順

1. self-test          gate. Without it, do not start.
2. ingest.sh          reads metadata of everything -> _build/manifest.tsv (sorted by capture)
3. cutlist.sh         proposes the cut under a ceiling -> _build/edl.txt
4. breakdown.sh       cut sheet + chapters + contact sheet
5. >>> APPROVAL <<<   show the breakdown and the total; wait for the ok
6. build.sh           normalizes each cut and concatenates -> _out/vlog.mp4
7. verify             loudness, duration, contact sheet. Only then say ready.

ユーザーがすでにプロファイルを承認している場合は、まとめて実行します。

SRC=/path/media PROJ=/path/project PROFILE=youtube bash scripts/all.sh

PROJ は _build/ と _out/ が作成される場所です。SRC はメディアフォルダーで、書き込みは一切行いません。ゲートでもそのことを確認します。以前のポルトガル語の名前（tudo.sh、roteiro.sh、TETO_MIN、PERFIL、_build/transcricao/ など）も引き続き使えます。スクリプトのヘッダーに一覧があります。

プロファイル

PROFILE	形式	音声テイク	用途
youtube（デフォルト）	16:9 1920x1080	全体	イベント vlog、長時間の記録
reels	9:16 1080x1920	最大 8 秒	SNS 向けカット、上限 1 分
archive	16:9	全体、トリミングなし	整理された素材アーカイブ

重要な判断事項

判断	デフォルト	理由
画面の埋め方	FILL=auto	横向きのクリップは画面いっぱいに表示します（クロップ）。縦向きのクリップは、ぼかした背景の上に配置します。縦向き映像を 16:9 にクロップすると、構図が台無しになります。判断にはピクセル幅ではなく表示マトリックスを使います
ラウドネス	LOUD=2（2 パス）	1 パスではダイナミクスが圧縮されます。数値はaudio.mdを参照してください
トランジション	ハードカット	良い vlog に必要なのはカットです。B ロールにワイプやクロスフェードを使うと、テンプレートのように見えます
カットの長さ	テイクに比例	一律の上限を設けると、同じ 5.0 秒のカットが 41 個でき、ベルトコンベアのようなリズムになります
順序	creation_time による時系列	自然に物語が組み立てられます（準備 → 到着 → イベント）。動画には有効ですが、写真には当てはまりません
キャッシュ	コンテンツキー	ファイル＋in＋out＋fill＋format＋audio の md5。位置は使いません

カットリスト（_build/edl.txt）

カットごとに 1 行で、TAB 区切りです。ここで実際の編集を行います。

file.MOV	0	12.5      # in at 0s, out at 12.5s
other.MOV	4	9         # only 4s to 9s
photo.jpg	0	3         # photo = 3s with a slow zoom (Ken Burns)
# a line with # is ignored    <- "deletes" a take without deleting the file

行の順序を変えると、動画の順序も変わります。不要なテイクはコメントアウトして削除します。

cutlist.sh はテイクの長さで分類し、物語の流れを損ないません。上限を超えた場合、まず上限値を引き下げ、それでも足りないときだけ、均等サンプリングで B ロールを間引きます。長いテイク（>25 秒）はスピーチとみなし、必ず含めます。

MAX_MIN=5 bash scripts/cutlist.sh     # 5 min target
MAX_MIN=0 bash scripts/cutlist.sh     # no ceiling
MAX_LONG=0 bash scripts/cutlist.sh    # whole speech take
PHOTOS_PER_DAY=0 bash scripts/cutlist.sh

編集成果物の内訳

breakdown.sh は、ユーザーが実際に使う次の3つを生成します。

• BREAKDOWN.md：カットごとに1行で、タイムライン上の位置、ファイル、日、素材の使用量、 種類（音声／中間素材／Bロール）、フレーミングを記載します
• CHAPTERS.txt：日ごとのチャプターを記載します。YouTube の説明欄にそのまま使えます（最初のチャプターは 00:00:00 にしなければなりません。そうしないと YouTube に拒否されます）
• _build/contact/sheet-*.jpg：番号付きサムネイルのグリッドです。準備完了と宣言する前に、少なくとも1つ開いてください。 動画をすべて見ずに内容を確認する唯一の方法です

準備完了と言う前に

ffprobe -v error -show_entries format=duration,size -of default=nw=1 _out/vlog.mp4
ffmpeg -hide_banner -nostats -i _out/vlog.mp4 -af ebur128 -f null - 2>&1 | tail -12

確認項目：尺が EDL の合計と一致していること、I: が目標値の ±1 以内であること、LRA: が 5～12 の範囲内であること（3 未満は圧縮しすぎです）。次にコンタクトシートを開いて、冒頭を確認します。Vlog は印象的なクリップから始まっていますか、それともぼやけた縦向き動画から始まっていますか。

ナレーション付き編集（記録映像ではなくエッセイ）

素材に内容のあるセリフがある場合、順序は日付ではなく、論旨によって決まります。次の手順を実行します（プロジェクトフォルダーから実行するか、PROJ を設定してください）。

bash scripts/transcribe.sh       # sentences with timecode
bash scripts/frames.sh           # entry point of each clip
# cut the speech blocks into _build/speech_audio (audio) and _build/speech_video (video+audio)
python scripts/plan.py           # builds the EDL by argument
bash scripts/build.sh

ナレーション EDL：5列で、映像は1つのファイルから、音声は別のファイルから取得します。

broll.MOV   in   out   narration.m4a   voice_in

顔が映る場面：speech_video/ 内の、映像と音声を一緒にカットしたセリフのクリップ自体を参照する3列です。同期が保証され、ナレーションが途切れません。

現場で検証されたルール（詳細はpitfalls.mdを参照）：

• 環境音のブレスは、異なるソースからのブロック間にのみ入れます
• 重複のないグローバルプールを使います（そうしないと、動画で同じ6つのクリップが繰り返されます）
• 長く連続するセリフのブロックは、40～56秒間中断しないのが自然に聞こえます

動画レッスン／コース（スクリーンキャスト、話し続ける形式）

Vlog とは異なる構成です。通常は1つのファイル（または、同じ録画セッションで撮影した数個のファイル）を使い、映像と音声は常に同じソースから取得します（ナレーション用の別個のBロールはありません）。問題は適切なテイクを見つけることではありません。録画には、良いセリフの合間に何分もの無音（画面を見ているだけで、誰も話していない時間）があり、場合によっては好ましくない音声イベント（背景の叫び声、マイクへの衝撃音）が含まれています。

ワークフロー（ナレーションとBロールを分離する cutlist.sh／frames.sh／plan.py は使用しません。ここでは映像と音声を分離しません）。

1. transcribe.sh              sentences with timecode for each raw file
2. read the transcript        decide which sentences GO IN, in order
3. write the EDL by hand      file\tin\tout, one per sentence (not per take)
4. audio anomaly scan         see references/course-lessons.md: peak and drop
5. build.sh                   same trim+concat+loudnorm engine as the vlog
6. check the cut              listen to the splices, especially where an event was removed

絶対に守るルール：単語の途中や、進行中の論理展開の途中では絶対にカットしないでください。 無音部分はほぼゼロまで詰めますが、文／節の実際の切れ目だけで行ってください。推測せずに whisper のタイムスタンプから切れ目を見つける方法については、references/course-lessons.mdを参照してください。

この方法が最も破綻しやすいのはレッスンの終わりです。 最後のカットが「要約すると……」で終わり、論理展開を締めくくる評価（「7分かかり、エラーは1つで、評価は8」）が抜けてしまいます。ほとんどの場合、その直前に中断した試み（「およそ450秒で」＋無音）があるためです。その試みを削除し、再開した部分は残してください。評価まで一緒に削除してはいけません。編集内容を確定する前に、素材内で次の単語がカットから3秒以内に始まる各レッスンについて、残した部分とその次に続く部分を確認し、ポーズにも印を付けてください。判断するのは編集者です。音声は論理展開の終わりを把握できず、whisper は句点をほとんど使いません。採用した終わり位置は、締めくくりとなる文と一緒に記録してください。次に続くのがすでに次のレッスンである場合、録画中に「カット」と言っている場合、または話題が変わる場合（「では、次のテストは……」など）は、考えの途中でのカットではありません。

好ましくない音声イベント（叫び声、衝撃音、ピーク）：デフォルトではその部分をそのままカットし、音量を下げないでください。ここでのダッキングは不安定です。後処理でコンプレッサーと loudnorm を適用すると、音量を下げた部分が再び大きくなり、よく聴かない限り「うまくいっている」ように聞こえる結果になりがちです。時間部分をカットすると、残す必要のある文が壊れてしまう場合に限り、ダッキングを検討してください。その場合でも、例外であることを明記してください。計測に基づく理由を含む詳細は、references/course-lessons.mdを参照してください。

音声の割合が高い素材の場合

cutlist.sh はテイクを選びますが、テイクの途中を編集するものではありません。テイク内の無音部分をカットするには auto-editor を使います。取り込み前に、別のフォルダーに出力して実行してください。tools.md を参照してください。

クラウドドライブ上のメディア

Google Drive for desktop のマウント上では、ファイルは読み込まれるまで仮想ファイルであり、読み込むたびにダウンロードが発生します。約 170 個のファイルの取り込みには数分かかり、2.5 GB のエンコードには 1 時間かかります。

バックグラウンドで実行し、まずユーザーに所要時間を伝えてください。実行後に伝えてはいけません。速いと思い込んで、all.sh をフォアグラウンドで実行するのは避けてください。

必要に応じて読む

• references/pitfalls.md：このパイプラインで発生する、根本原因を伴う目立たない失敗について説明しています。スクリプトを編集する前に必ず読み、症状の類似性からバグを診断する前にも読んでください。ここに記載されたケースのひとつでは、誤った診断によって再構築に 1 時間かかりました。
• references/audio.md：ラウドネスの目標値、1 パスと 2 パスの違い、クリックノイズの除去、音楽のバックグラウンド、デスクマイクについて説明しています。音声を扱うときや、「音がおかしい」と感じたときに読んでください。
• references/tools.md：すでにあるツール（auto-editor、faster-whisper、ffmpeg-normalize、exiftool）と、追加すべきでないツールについて説明しています。新しいものを書く前に読んでください。
• references/course-lessons.md：スクリーンキャストやレッスンを文単位で分解し、whisper のタイムスタンプを使った安全なカット位置、話し方の強調と混同せずに音声の問題箇所を見つける方法、ダッキングより直接カットが優れている理由を説明しています。
• references/cases.md：これらのルールが生まれた作業事例です。