What is a funscript file?

A funscript (.funscript) is a small text file in JSON format that lists timed positions: at this many milliseconds into the video, move to this position. A player reads it alongside the video it was made for and drives an interactive device in sync. It's the format the interactive-script community has standardised on — if you've downloaded a script for a video, you've downloaded a funscript.

• Open it: any text editor shows the JSON; OpenFunscripter shows it as an editable timeline.
• Play it: a funscript player, with the script next to the video under the same name.
• Make one: by hand in OpenFunscripter, by motion tracking, or from a song's beats for music-timed video.

This page covers each of those, and one thing that's newly possible: cutting a video to a script you already have, instead of scripting a video you already have.

What's inside a funscript file

It's plain JSON. A typical file looks like this:

{
  "version": "1.0",
  "inverted": false,
  "range": 100,
  "actions": [
    { "at": 0,    "pos": 0   },
    { "at": 480,  "pos": 90  },
    { "at": 960,  "pos": 10  }
  ]
}

• actions is the script itself: at is milliseconds from the start of the video, pos a position from 0 to 100.
• inverted flips every position, for devices or setups that run the other way.
• range limits how far the device travels, from 0 to 100.
• Many scripts also carry a metadata block (title, creator, tags) that players ignore.

Two consequences worth understanding, because they explain a lot:

• A script is tied to one specific video file. The timestamps only mean anything against the exact cut they were written for. A different release of the same scene will drift.
• Intensity lives in the speed, not the position. A script sitting at pos: 90 isn't "intense" — it's parked. Fast alternation between positions is intense. This is why heatmaps colour by speed, and it matters later on this page.

How to open a funscript file

• To read it: any text editor — Notepad, VS Code — opens a .funscript and shows the JSON above. Nothing is encrypted or compiled.
• To edit it: OpenFunscripter (OFS) loads the script with its video and shows every point on a timeline you can drag, add to and delete.
• To use it: load it in a player together with the video it belongs to (next section).

How to play a funscript

You need a player that reads the script and drives a device:

• Desktop players such as MultiFunPlayer and ScriptPlayer load a video plus its matching .funscript.
• Intiface Central is the usual bridge between a player and the device itself; many players connect through it.
• Device-specific apps from the hardware makers, and browser players on sites that host scripted content.

The near-universal convention: keep video.mp4 and video.funscript side by side, same name. Most players find the script automatically that way.

How scripts get made

Three approaches, roughly in order of effort:

1. By hand, in an editor. OpenFunscripter is what most scripters use — you scrub the video and place points. Slow, accurate, and the way good scripts still get made.
2. Motion tracking. Tools that follow movement in the video and generate points from it. Decent starting point, usually needs cleanup.
3. From a beat grid. For anything music-timed — PMVs, cock hero, HMVs — the timing is the music, not the on-screen motion. If you can detect the beats, you have the script skeleton.

That third one is worth expanding, because it's the case most people on this site are in.

Making a script from a song's beats

For music-timed video, hand-tapping beats is the tedious part — hundreds of placements before you make a single creative decision. Beat detection solves that in one pass.

Onset Engine exports any track's detected beat grid as a funscript, along with an Audacity label track and a CSV:

1. In the AUDIO tab, click ⇩ BEATS next to the track.
2. Tick Funscript, Audacity labels and CSV and click Export.
3. The files appear next to the song, as song_beats.funscript and friends.

You get a metronome-pattern script — a stroke on every detected beat, with downbeats identifiable — that you load into OFS as a timing skeleton and then shape. It's free in the demo and not paywalled. There's more detail on that, and on the community around it, in the Eroscripts guide.

The other direction: cutting a video to a script

Here's the part almost nobody does, because until recently there wasn't a tool for it.

Normally you have a video and you write a script for it. Flip that around: you have a script you like — maybe one you wrote, maybe one you downloaded for a scene you own — and you want a new edit built around its rhythm. The script becomes the blueprint instead of the output.

Onset Engine can take a funscript as the energy curve for an edit. On the ADVANCED tab of the Editor's settings, under ENERGY CURVE, click … next to Energy curve and pick your .funscript, then generate and render as normal.

What that actually does: it reads the script's stroke speed over time — remember, speed is the intensity signal, not position — and uses that as the edit's intensity envelope. Where the script goes fast, the edit cuts fast and reaches for your highest-energy clips. Where it eases off, the edit breathes.

The cuts still land on the music's beat grid, so the result is still beat-synced and still looks deliberate. What the script controls is pacing and clip intensity, not raw cut placement. The Curve weight slider blends it with the music's own energy: 100% follows the script alone, 50% averages the two.

It also takes a plain CSV of time_s,intensity rows instead — a hand-drawn build, a curve exported from something else, whatever you can express as intensity over time. On Core you can skip the file and draw the curve over the song with Shape it….

Why you'd actually want this

• You have a script you love. Build a fresh edit that follows its shape, rather than re-scripting from scratch for new footage.
• Cock hero rounds. The escalation pattern is an intensity curve. Draw it once, get an edit that follows it.
• Script and video from one source. Export the beat grid, shape it into a script with real variation, then drive the edit from that script — the video and the script follow the same timing.

Honest limits

• This doesn't write motion for you. Onset reads a script's intensity; it doesn't watch a video and generate stroke points. Motion-tracking tools do that, and this isn't one.
• Beat export is a skeleton, not a finished script. It gives you accurate timing. The feel is still your job.
• An unshaped beat export makes a flat curve. Its strokes are all the same speed, so loading it straight back as an energy curve gives an edit with no variation. Onset warns you when a curve is flat.
• Scripts are cut-specific. Driving an edit from a script produces a new video with its own timing — the original script won't line up with the result. They're related in shape, not frame-for-frame.

Funscript questions

What is a funscript file?

A .funscript is a small text file in JSON format that lists timed positions: at this many milliseconds into the video, move to this position from 0 to 100. A player reads it alongside a video and drives an interactive device in sync. It holds no video or audio of its own.

How do I open a funscript file?

It's plain text, so any text editor (Notepad, VS Code) opens it and shows the JSON. To see it as a timeline you can edit, open it in OpenFunscripter. To use it, load it in a funscript player together with the video it was made for.

How do I play a funscript?

Use a player such as MultiFunPlayer or ScriptPlayer, usually with Intiface Central connecting your device. Keep the script next to the video with the same name (video.mp4 and video.funscript) and most players load it automatically.

How do I make a funscript?

By hand in OpenFunscripter, by motion tracking and then cleaning up the result, or, for music-timed video, from the song's beats: export the beat grid as a funscript and use it as the timing skeleton.

Does a funscript work with any video?

Only with the exact video it was written for. The timestamps are tied to that cut, so a different edit or release of the same scene drifts out of sync.