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

Usage

# Replace the music's energy entirely
OnsetEngine.exe render job.json --final --energy-curve curve.funscript

# Blend it 50/50 with the music's own energy
OnsetEngine.exe render job.json --final --energy-curve curve.funscript --energy-curve-weight 0.5

Both flags work on draft and render.

--energy-curve-weight runs from 0.0 (music only) to 1.0 (curve only, the default).

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.