The funscript format, field by field

The structure

A funscript is one JSON object saved as UTF-8 text with the extension .funscript. A complete small file, in the shape AutoScript Sync saves:

{
  "version": "1.0",
  "inverted": false,
  "range": 100,
  "metadata": {
    "creator": "AutoScript Sync",
    "format": "funscript"
  },
  "actions": [
    {"at": 0,    "pos": 50},
    {"at": 350,  "pos": 95},
    {"at": 720,  "pos": 5},
    {"at": 1080, "pos": 95},
    {"at": 1500, "pos": 5},
    {"at": 5500, "pos": 5}
  ]
}

The last two points hold the same position for four seconds: a rest is written as two points at the same pos, not as a gap. Key order does not matter in JSON, and whitespace is free.

The fields

actions

An array of points, each an object with at and pos. This is the only field a player needs. A file without it is not a usable script.

at

The point's time in milliseconds from the start of the video, as an integer. 1500 is one and a half seconds in.

pos

The position to be at, at that time, as an integer from 0 to 100. What 0 and 100 mean physically is up to the device and its settings; the file only says "this far along the range".

version

The format version as a string, usually "1.0".

inverted

true or false. When true, positions are meant to be read upside down, as 100 − pos.

range

A number, usually 100, describing the span of pos. Most files leave it at 100.

metadata

An object for anything about the script: the program that made it, a title, notes, tags. Players do not need it to play the file.

Files from editors often carry extra top-level keys, such as chapters or bookmarks. They are allowed; a reader that does not understand them should ignore them and, ideally, keep them.

Conventions a well-formed file follows

• at is a whole number of milliseconds, counted from the start of the video, never negative.
• pos is a whole number from 0 to 100.
• Actions are sorted by at, earliest first.
• No two actions share the same at.
• Numbers are JSON numbers, not strings: "at": 400, not "at": "400".

Programs differ in how forgiving they are when a file breaks these rules. The desktop app repairs what it can, as described below. Our own browser tool, Report Studio, does not: it assumes the actions are already sorted, takes the duration from the last action, ignores inverted and range, and rejects a file whose at values are strings. A file that follows all five conventions avoids those differences.

How AutoScript Sync reads a file

When you open a script with Load Funscript…, drop it on the window, or open a video with a same-named script beside it, the app repairs the actions instead of refusing the file:

• sorts the actions by time;
• merges actions that share a time, keeping the last one;
• clamps pos to 0–100 and negative times to 0;
• skips entries it cannot read, without saying how many;
• reads range but never uses it to rescale, so a file with a range other than 100 is still treated as 0–100;
• keeps version as found ("1.0" if missing).

The next update (2.121.2, built but not yet released) makes the reader accept more files and keep more of what is in them:

• files saved with a byte-order mark, or as UTF-16, load instead of being refused;
• inverted: true is applied once when loading (100 − pos), with a note to you, and the file is saved back with inverted: false, so every other player sees the same motion. The released app ignores the flag, so an inverted file plays upside down;
• fractional at and pos values are rounded to the nearest whole number, and NaN or infinite values are skipped;
• unknown top-level keys such as chapters or bookmarks are kept and written back when you save; the released app drops them on save;
• a file that is not text, not JSON, not an object or has no actions list gets a plain-language message, and a script with no usable actions is not attached to the video.

How AutoScript Sync writes a file

Every script the app saves, generated or edited, follows the conventions above whatever happened in the editor:

• Actions are written in ascending time order, with unique times, at as a non-negative whole number of milliseconds and pos as a whole number from 0 to 100. If two points round to the same millisecond, the later one wins.
• Header: version, inverted and range are written as held; a generated script gets "1.0", false and 100.
• Metadata: creator is always set to "AutoScript Sync" and format to "funscript". Saving over another tool's script replaces its creator.
• Analysis details in generated scripts: generator, recognition summary, timing, tracking path and an ai block with each two-second window's scene-type label, the tracked region, how much was filled in rather than measured, and the anchor election scores.
• Safe saving: the JSON is written, indented, to a temporary file and then swapped in, so a crash mid-save cannot corrupt the existing script.
• Backup: when Generate saves beside the video, any existing script is first copied to <name>.funscript.bak. Only one backup is kept; the next Generate overwrites it.

The file on disk is never fitted to a device. When the app sends a script to the Autoblow AI Ultra it fits a copy to the device's limits and strips the analysis metadata, keeping only the motion and a few header fields (generator, creator, format, version, range, stroke_expansion and an id if present).

Questions

Read next

• Check a file with the validatorFinds the mistakes on this page in your browser, and offers a repaired copy.
• A plain-language introductionWhat a funscript is and how a device uses it, without the field detail.
• Making a script, by hand or generatedThe workflow from video to a saved, checked file.
• The learn hubAll four reference pages.