framerate-audit

name: framerate-audit description: This skill should be used when the user asks "check frame rate", "is this CFR or VFR", "video has duplicate frames", "video stutters", "frame rate issues", "why does video judder", or wants to analyze frame rate characteristics and detect timing problems.

Frame Rate Audit

Analyze video frame rate characteristics, detect CFR vs VFR, find duplicate frames, and diagnose timing issues.

Key Concepts

CFR vs VFR

CFR (Constant Frame Rate):

• Every frame has identical duration
• Required by most video editors
• Preferred for distribution

VFR (Variable Frame Rate):

• Frame durations vary
• Common in screen recordings, phone videos
• Causes editor sync issues

Common Frame Rates

23.976 vs 24: Nearly identical visually. The fractional rate exists for NTSC broadcast compatibility from analog TV era.

Audit Workflow

Step 1: Check MediaInfo

mediainfo video.mkv

Look for:

Frame rate mode    : Constant or Variable
Frame rate         : 23.976 (24000/1001) FPS

Frame rate mode tells you CFR vs VFR.

Step 2: Detailed Frame Analysis

For deeper analysis:

# Check frame rate mode specifically
mediainfo --Inform="Video;%FrameRate_Mode%" video.mkv

# Get frame count
ffprobe -v error -count_packets -select_streams v:0 \
  -show_entries stream=nb_read_packets -of csv=p=0 video.mkv

Step 3: Detect Duplicate Frames

Using ffmpeg:

# Detect duplicate frames (mpdecimate filter)
ffmpeg -i video.mkv -vf "mpdecimate,setpts=N/FRAME_RATE/TB" \
  -f null - 2>&1 | grep "drop"

Manual inspection with mpv:

• Open video in mpv
• Step frame-by-frame with . and ,
• Compare adjacent frames visually
• Look for identical frames in sequence

Step 4: Check for Judder

Judder causes:

• Frame rate mismatch with display
• Incorrect pulldown handling
• Duplicate frames creating uneven motion

Visual test:

• Watch panning shots
• Motion should be smooth
• Stuttering indicates timing issues

Common Issues

VFR Causing Editor Problems

Symptoms:

• Audio/video desync in editors
• Random stuttering
• Export timing issues

Solution: Convert to CFR before editing:

ffmpeg -i vfr_video.mkv -vsync cfr -r 30 cfr_video.mkv

Duplicate Frames

Symptoms:

• Motion appears to stutter
• Some frames are identical to previous
• Uneven playback

Causes:

• Bad frame rate conversion
• Screen recording with drops
• Encoding errors

Detection: Step through video frame-by-frame. If two adjacent frames are identical, you have duplicates.

Wrong Frame Rate Tag

Symptoms:

• Video plays too fast or slow
• Audio sync issues
• Duration doesn't match expected

Solution: Retag without reencoding:

# Change frame rate metadata only
ffmpeg -i video.mkv -c copy -video_track_timescale 24000 output.mkv

Interpolation Damage

Symptoms:

• "Soap opera effect" smoothness
• Morphing/warping on motion
• Ghosting around moving objects

Cause: Frame interpolation (RIFE, SVP, TV motion smoothing) generating fake frames.

Why it's bad:

• Invented frames don't match source
• Artistic intent is 24fps, not 60fps
• Creates unnatural motion

Editor Compatibility

Premiere Pro / DaVinci / Vegas

Requirements:

• CFR strongly preferred
• Fractional rates (23.976) can cause issues
• Some editors handle VFR poorly

Before importing:

1. Check if source is CFR
2. If VFR, convert to CFR first
3. Use MkvToMp4 or ffmpeg for conversion

MKV to MP4 for Editors

Standard remux may preserve VFR timestamps:

# May not fix VFR
ffmpeg -i input.mkv -c copy output.mp4

Force true CFR:

# Step 1: Set timescale
ffmpeg -i input.mkv -c copy -video_track_timescale 24000 temp.mp4

# Step 2: Round timestamps (for 23.976 fps)
ffmpeg -i temp.mp4 -c copy \
  -bsf:v "setts=dts=1001*round(DTS/1001):pts=1001*round(PTS/1001)" output.mp4

Quick Reference

Tools

• MediaInfo: Frame rate mode detection
• ffprobe: Detailed timing analysis
• mpv: Frame stepping (. and , keys)
• MkvToMp4: VFR to CFR conversion for editors

Additional Resources

• ${CLAUDE_PLUGIN_ROOT}/references/encoding-commands.md - Frame rate conversion commands
• ${CLAUDE_PLUGIN_ROOT}/references/tools.md - Tool recommendations