Beat Sync

An optional planning layer that snaps transition boundaries to audio beats and modulates camera intensity by track energy — keeping style pack rules intact while adding rhythmic alignment.

What is beat sync?

Beat-synced editing is a technique from music video and motion graphics production where visual transitions — cuts, crossfades, camera changes — are timed to land on audio beats. When transitions align with rhythm, the result feels intentional and polished. When they don't, even well-composed sequences feel disconnected from their soundtrack.

Animatic's beat sync system is an optional layer that activates during sequence planning. When beat data is provided to plan_sequence, two additional stages run after the standard planning pipeline: beat snapping (adjusting durations so transitions land on beats) and energy matching (mapping audio energy to camera intensity).

The core editing logic remains rule-based and deterministic. Beat sync adjusts timing — it doesn't change shot order, transition types, or style pack rules.

How it works

Beat sync integrates into the sequence planning pipeline as two additional stages:

Without beat data, the planner behaves exactly as before — fully backward-compatible.

Beat analysis

The analyze_beats MCP tool processes audio files and returns beat timing data. It decodes WAV files and runs energy-based onset detection to identify rhythmic boundaries.

The beat analysis module (mcp/lib/beats.js) is pure functions with no I/O — audio decoding happens upstream before the data reaches the analysis functions.

Beat data includes:

• Beat positions — timestamps (in seconds) where rhythmic onsets occur
• Energy levels — relative energy intensity at each beat position
• Tempo — estimated BPM (beats per minute)

Duration snapping

When beats data is passed to plan_sequence, scene durations are adjusted so that transition boundaries align with the nearest beat.

The snapping algorithm:

1. Calculate the ideal transition point (cumulative duration up to each scene boundary)
2. Find the nearest beat to each transition point
3. Stretch or compress the scene duration to land on that beat

Snap tolerances

These tolerances keep adjustments subtle. A scene planned for 2.5s might snap to 2.8s or 2.2s, but never to 1.5s or 3.5s. The result feels rhythmically aligned without dramatically altering the planned pacing.

How it affects different styles

Fast styles (energy, kinetic) have more transition points per second, giving more opportunities for beat alignment. Slow styles (documentary, intimate) have fewer transitions, so each snap is more noticeable.

Energy matching

The second beat-sync stage maps audio energy levels to camera intensity. For each scene's time range, the average audio energy is calculated and blended with the style pack's camera intensity.

Blending formula

effective_intensity = (style_pack_intensity × 0.5) + (audio_energy × 0.5)

The 50/50 blend ensures:

• Style pack rules still dominate the camera behavior (move type, base intensity)
• Audio energy modulates the intensity — louder sections get more camera movement, quieter sections get less
• Camera intensity stays in the valid 0.1–0.8 range

Practical effect

A prestige sequence with push_in at 0.2 intensity:

• During a quiet audio section (energy 0.1): effective intensity = 0.15
• During a loud audio section (energy 0.6): effective intensity = 0.40
• The camera still does push_in (style pack decides the move), but the magnitude follows the music

Styles with force_static camera (energy, minimal, kinetic) are unaffected by energy matching — static is static regardless of intensity.

Constraints and limits

What beat sync does

• Adjusts scene durations within tight tolerances to align transitions with beats
• Modulates camera intensity based on audio energy
• Works with any style pack

What beat sync does not do

• Change shot order — that's the planner's job
• Change transition types — crossfade stays crossfade, hard cut stays hard cut
• Override style pack rules — it adjusts within the style's framework
• Require audio — sequences work fine without beat data

Edge cases

• Very fast music (180+ BPM): Many beats available, most transitions will snap successfully
• Very slow music (60 BPM): Beats are 1s apart, snapping works well for short-hold styles but may not find nearby beats for long-hold styles
• Irregular rhythm: The algorithm finds the nearest beat regardless of regularity. Works with both metronomic electronic music and organic acoustic recordings
• No audio: Omit the beats parameter and the planner runs its standard pipeline

Workflow

A typical beat-synced sequence follows this process:

1. Analyze your audio — use analyze_beats on your WAV soundtrack to get beat timing and energy data
2. Prepare scenes — author or generate scene JSON files
3. Analyze scenes — run analyze_scene on each to generate metadata
4. Plan with beats — pass scenes, style, and beat data to plan_sequence
5. Evaluate — use evaluate_sequence to check quality scores
6. Compile — use compile_motion to produce the final output

The beat data flows through steps 4-6. You can re-plan with different style packs while keeping the same beat data to compare how different editorial styles align with your music.

Try it

Try asking your AI:

Analyze the beats in my audio file at assets/soundtrack.wav and show me the beat positions and tempo.

Plan a sequence from these 8 scenes using the energy style, synced to these beats. Show me which transitions snapped to beats.

I have a 120 BPM track. Which style pack would give me the best beat alignment for a product launch video?

Plan the same sequence twice — once with beat sync and once without. Compare the total durations and transition timing.