# FrameSync Sim — NumPy + SimPy Beat-Timing Simulator for Voiceover-Synced Video

## PURPOSE
A simulation prototype that turns a word-level SRT transcript into an animation timeline. Given a voiceover's per-word timings and a set of scene "beats" (each beat is a visual moment such as an object drawing in), it computes which frame each beat lands on at a target FPS and simulates how the scene builds over time. This models the video's central trick: the user pastes a word-level SRT, and the code-drawn video times itself "perfectly to the words."

## WHY THIS MATTERS
The transcript explains that sync "works best with the word-by-word timings" and warns that asking for a plain SRT gives line-level timing instead. Turning that advice into a computation makes the trade-off concrete: word-level cues give fine-grained anchors, so beats can be placed at exactly the frame a spoken word starts. A simulator lets a student test beat placement against an audio track without rendering anything.

## HOW TO BUILD
Two layers. NumPy holds the numeric timeline — a frame grid and an interpolation of word start times:

```python
import numpy as np

def word_windows(cues):                    # cues: [(start, end, "word"), ...]
    starts = np.array([c[0] for c in cues])
    ends   = np.array([c[1] for c in cues])
    return starts, ends

def beat_frames(beats, word_starts, fps=60):
    idx = np.searchsorted(word_starts, beats)   # which word each beat lands on
    return (word_starts[idx] * fps).astype(int)
```

SimPy models the render loop as discrete events: a `beat` process waits `wait`-until the next timestamp, triggers a `draw`, and perturbs timing to show how small SRT drift accumulates.

## WHEN TO USE IN PRODUCTION
Use it as a pre-render planner: verify beat placement, spot drift where a word file is too coarse, and tune FPS before burning a full generation. Not for actual rendering (Claude writes the JS frames), and not for long videos where word-level SRTs become gigantic — switch to line-level and coarser beats there.

## HOW IT HELPS STUDENTS
Teaches NumPy array/vectorised timing math, `searchsorted` indexing, and discrete-event simulation with SimPy — a real scheduling and media-timing mindset.

## STARTER CODE
`starter/main.py` seeds a deterministic word-level SRT and beat list, builds the NumPy timeline, and runs a SimPy render-loop simulation with TODO markers.
