External Energy Curves

Overview

By default, Onset Engine derives an edit’s intensity from the music: loud, dense passages raise the driver tier and quicken the cutting; quiet passages relax it.

External energy curves let you supply that intensity from a file instead. The cuts still land on the music’s beat grid — what changes is which clips are chosen and how fast the edit moves through them.

Two formats are supported:

• .funscript — a motion script
• .csv — plain time_s,intensity rows

A beat grid is not an energy curve

The beat grid export and energy curves look like two directions of the same feature. They are not.

Export gives you timing — where the beats are, written as a metronome that alternates position on every beat. Import wants dynamics — how intense the moment is, which for a funscript is read from stroke speed.

A metronome’s stroke speed never changes, so re-importing a beat grid you exported produces a completely flat curve and an edit with no energy variation at all. Supply a script with real varying action, or a CSV you wrote yourself. Onset warns you if the curve you pick turns out to be flat.

Using a curve

In the Action Block, under Narrative and Pacing:

1. Click the … button next to Energy curve and pick your .funscript or .csv.
2. Set Curve weight — 100% uses the curve alone, 50% averages it with the music’s own energy, and the slider stays disabled until you have chosen a file.
3. Generate and render as normal.

The curve is checked as soon as you pick it: an unreadable file is rejected there and then, and a flat one warns rather than quietly producing a lifeless edit. The ✕ button clears it. Your choice is saved with the project, so it survives closing and reopening.

It applies to Generate Timeline as well as the final render — clip selection is what the curve changes, so the draft shows you the real result.

How a curve is interpreted

CSV

Two columns, header optional. Intensity can be in any numeric range — it gets normalised:

time_s,intensity
0,10
30,45
60,90

Values between your points are interpolated, so a handful of points is enough to describe a shape. If the curve is shorter than the track, its final value holds to the end.

Funscript

Intensity is derived from stroke speed — the rate of positional change — not from raw position.

This matters and is worth being explicit about: a script parked at a high position is not intense, it is stationary. Fast alternation is intense. This is the same convention the scripting community’s heatmaps use, so a script that looks intense on a heatmap produces an intense edit.

Processing

Whichever format you supply, the curve is:

1. Resampled onto the editor’s energy timeline, so any curve length can drive any track length
2. Smoothed, because raw stroke speed is spiky and the editor wants an envelope
3. Normalised to 0–1, then blended with the music’s energy according to --energy-curve-weight

A completely flat curve resolves to neutral mid-energy rather than an error.

When to use it

• Building an edit around an existing script. The script becomes the blueprint rather than the output.
• Prescribing a shape. A hand-written CSV gives you an exact build — a slow burn to a single peak, or repeating escalation rounds — regardless of what the track does.
• Non-musical intensity sources. Anything you can express as intensity over time works: a sensor trace, telemetry, an annotation pass.

Failure behaviour

Curve loading is non-fatal. If the file is missing, malformed, or in an unsupported format, the render logs a warning and falls back to the music’s own energy rather than aborting:

[ENERGY WARN] Could not use energy curve (...). Using audio energy.

A successful load reports the mix:

[ENERGY] Driving edit from curve.funscript (curve only)

Notes

• The beat grid is unaffected. Cuts stay musically aligned; only tier selection and pacing follow the curve.
• Malformed rows or actions are skipped rather than failing the whole file.
• To generate a curve from a track, see Beat Grid Export.