# 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](https://links.handyfeeling.com/docs-guide-scripting) 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](https://links.handyfeeling.com/docs-guide-demo-content). ## 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: ```json { "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: ```csv 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](https://links.handyfeeling.com/docs-guide-script-tokens#use-a-token-file-like-a-funscript) 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](https://links.handyfeeling.com/docs-hosting-api-v2#handle-errors). ## Store or play a script - [Hosting API v2](https://links.handyfeeling.com/docs-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](https://links.handyfeeling.com/docs-stream-api-v0#store-an-existing-script) stores script content for reuse. It accepts URL, CSV, or actions input and returns a stream reference for playback. - [Handy REST API v3](https://links.handyfeeling.com/docs-handy-rest-api-v3-hssp) 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.