Script formats
A movement script describes where a device should be at particular times. Like subtitles, its entries follow a timeline. For slider motion, each entry pairs a time in milliseconds with a position from 0 through 100.
Use this reference for the file encoding. The scripting guide explains how to create and review a script; the API guides explain how to store or play it.
For ready-made test content, choose a demo video and matching funscript.
Times and positions
Use nonnegative integer timestamps measured in milliseconds from the beginning of the script. Positions are integers from 0 through 100, inclusive. Write entries in chronological order.
| Format | Time | Position |
|---|---|---|
| Funscript JSON | at |
pos |
| Handy CSV | First column | Second column |
For example, time 250 and position 82 describe a target position of 82% at 250 milliseconds. The values describe the intended timeline; playback and synchronization are handled by the selected device protocol.
Point density and device limits
Use the fewest points needed to describe the intended movement. For most simple stroke patterns, the peaks and valleys—plus the start, end and any holds—are enough. The device moves between points, so a continuous, densely sampled wave often adds little benefit.
Add intermediate points when they meaningfully shape acceleration, deceleration or smoothness. Extra points along an already straight transition add no movement information, but consume buffer space and increase the data sent.
Keep the device’s physical capabilities in mind. Maximum speed, acceleration and how quickly it can reverse direction vary by model. The device tries to reach each specified position at its timestamp. If it cannot complete the movement in time, it may reverse before reaching the target, shortening the stroke, or skip points to keep up with the timeline. Adding more points cannot overcome these limits.
Some of this behavior can be adjusted through firmware settings. The resulting movement therefore depends on the pattern’s points and timing, the device model and its firmware configuration.
Funscript JSON
A funscript contains an actions array. Each action has an integer at timestamp and an integer pos position:
{
"actions": [
{"at": 0, "pos": 0},
{"at": 250, "pos": 82},
{"at": 500, "pos": 51},
{"at": 750, "pos": 9}
]
}
These actions describe four targets: position 0 at the beginning, 82 at 250 ms, 51 at 500 ms, and 9 at 750 ms.
Save the JSON as a funscript file. Hosting API v2 also accepts standard funscript JSON with a .json extension. When an API accepts an actions array directly, follow that endpoint's request structure rather than sending the entire file object.
Handy CSV
Write one timestamp and position pair per line, separated by a comma. The same movement sequence is:
0,0
250,82
500,51
750,9
The first column is time in milliseconds; the second is position from 0 through 100. Save the text as a .csv file, or pass it as a string where an API accepts inline CSV.
Content access and script tokens
Some script content has server-side access and expiry information. This is separate from the Application ID or client token used to authenticate an API request.
Providers can supply a funscript-shaped script-token file for use in a supported player. It takes the place of the script the user selects alongside a video, while the service resolves access to the actual movement data. Treat the issued carrier as opaque and keep it unchanged through the supported upload/playback flow.
The script-token guide explains this drop-in file-selection experience, online resolution, open and closed distribution, and separate download/access lifetimes.
Hosting API v2 uses its ordinary script-upload workflow for standard script data. Script-token state is handled server-side. Inspect the upload response for either a usable url or an error, including terminal TOKEN_EXPIRED outcomes. See Hosting error handling.
Store or play a script
- Hosting API v2 gives a local file a temporary download URL. Equivalent CSV and funscript data normalizes to the same content identifier.
- Stream API v0 stores script content for reuse. It accepts URL, CSV, or actions input and returns a stream reference for playback.
- Handy REST API v3 controls device playback. HSSP accepts a server-accessible script URL; STREAM uses a stream reference.
Each receiving API defines its own size limits, validation, and error handling. For example, Stream processes points in input order, discards invalid points, and requires each accepted timestamp to be strictly greater than the previous one.