anibon-stream-synthesis-ffmpeg

Advanced FFmpeg Video Editing & Narrative Flow

Overview

This skill provides a structured approach for advanced video editing using FFmpeg. It focuses on achieving frame-accurate cuts, perfect audio-video synchronization, and maintaining a seamless narrative flow. The goal is to produce edits that feel natural, avoiding jarring jump cuts and ensuring the viewer never feels confused.

Core Principles

1. The "But / Therefore" Narrative

Always edit using the "But / Therefore" storytelling method.

• Avoid "And Then" jump cuts (e.g., cutting from one random farming/grinding segment to another).
• Ensure each scene naturally leads to the next: "This happened, therefore this happened," or "This happened, but then this unexpected event occurred."
• This maintains viewer engagement and provides a cohesive narrative arc.

2. Audio-Waveform Driven Cutting

Do not cut blindly based on visuals alone. Always pay close attention to the audio waveform.

• Cut at the End of Sentences: Ensure cuts occur naturally at the exact end of a spoken sentence or breath.
• Avoid cutting mid-word or mid-breath, which causes jarring jump cuts.
• Look deep into the exact picture and waveform details to find the exact frame where the audio trails off into silence before the next action begins.

3. Deep Close Detail (Frame-Accurate Precision)

Look closely at the detailed picture and exact frames.

• Ensure the cut makes visual sense. The transition should feel smooth, not disorienting.
• The viewer should not feel confused by a sudden, inexplicable change in scene, posture, or context. Every cut must feel intentional.

FFmpeg Technical Implementation

This skill inherently integrates and extends the technical foundation from anibon-stream-synthesis/edit-cut-video-ffmpeg. To guarantee perfect synchronization and prevent frame freezes, you must re-encode specific segments using FFmpeg's filter_complex at the raw frame level.

Fixing Audio-Video Sync & Frame Freezes

Never use -c copy when cutting streams or merging clips, as this causes keyframe issues (black screens/freezes) and container-level packet alignment problems (AV desync).

Instead, force frame-level alignment in memory:

ffmpeg \
  -i input1.mp4 \
  -i input2.mp4 \
  -filter_complex "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[outv][outa]" \
  -map "[outv]" -map "[outa]" \
  -c:v libx264 -pix_fmt yuv420p \
  -c:a aac \
  -movflags +faststart \
  output_seamless.mp4

Why this is critical:

• -c:v libx264: Forces a keyframe at the start, eliminating black screen freezes.
• -pix_fmt yuv420p: Ensures compatibility across all players, including macOS/QuickTime.
• concat=n=2:v=1:a=1: The filter_complex aligns video and audio packets perfectly at the raw frame level, completely resolving progressive desync issues.

Workflow Execution (TDD RED-GREEN-REFACTOR)

Apply the TDD philosophy to your video editing workflow:

1. RED (Identify the Problem): Watch the raw footage. Identify disjointed "And Then" moments, audio trailing, or sync issues. Find the exact frames where the viewer would get confused.
2. GREEN (Make the Cut): Use FFmpeg to make precise cuts based on the audio waveform at the end of sentences. Re-encode using filter_complex to ensure perfect AV sync and visual continuity.
3. REFACTOR (Polish the Narrative): Review the concatenated output. Does it follow the "But / Therefore" structure? Are the cuts invisible to the viewer's cognitive load? If not, adjust the cut points and re-process.

Red Flags - STOP and Start Over

• The edit feels like an "And Then" sequence without narrative causality.
• You cut while a speaker was still inhaling or mid-sentence.
• You used -c copy to save time, resulting in a black screen for the first few seconds of the clip.
• The audio and video slowly drift out of sync over a 5-minute clip.