Skip to main content

skipFlash

What happens when you add an Incident​

Every time you call addIncident, MotorCortex performs a flash — it replays the entire Clip's state from millisecond 0 up to the current playhead position. This ensures that all Incidents, old and new, are in perfect sync.

For most use cases this is exactly what you want. But in scenarios where you're adding many Incidents in quick succession — particularly during live playback — the repeated 0-to-current replays can become expensive.

The skipFlash option​

addIncident accepts an optional third argument: an options object with a skipFlash flag.

clip.addIncident(myIncident, 5000, { skipFlash: true });

When skipFlash is set to true, MotorCortex skips the full replay after adding the Incident. The Incident is still registered on the timeline and will execute naturally when the playhead reaches it.

When to use it​

skipFlash is safe only when the Incident is placed ahead of the current playhead. In this case there's no state to catch up on — the timeline will discover and execute the Incident on its own during forward playback.

Safe:

playhead at 3000ms
├── existing incidents ... ──────┤
                                  └── new incident at 5000ms ← skipFlash: true ✓

Not safe:

playhead at 5000ms
├── existing incidents ... ──────────────┤
        └── new incident at 2000ms ← skipFlash: true ✗ (state will be wrong)

If the Incident is placed behind the playhead and you skip the flash, its effect won't be applied until the next time the Clip replays that region (e.g. on seek or loop). The state will be inconsistent.

Typical use case​

The primary use case is real-time Incident injection during playback — for example, a tool or UI that adds effects on the fly while the Clip is playing. Without skipFlash, each addition would cause a brief stutter as the entire timeline replays. With skipFlash, additions ahead of the playhead are instant and stutter-free.

// During live playback, add incidents ahead of the playhead
const currentMs = clip.runTimeInfo.currentMillisecond;
const futureMs = currentMs + 2000;

clip.addIncident(
  new CSSEffect(
    { animatedAttrs: { opacity: 1 } },
    { selector: ".element", duration: 1000 }
  ),
  futureMs,
  { skipFlash: true }
);

Default behaviour​

By default, skipFlash is false. The flash replay always runs unless you explicitly opt out. If you're unsure whether to use it, don't — the default behaviour is always correct.