Scripting
Scripting turns movement in a video, or a movement effect you have designed, into a sequence of timed positions. Start with the script-format reference for timestamps, positions, and file examples.
You can create a script manually, use the community scripting tool, or arrange access to the Handy team's assisted scripting pipeline. Automated analysis provides a starting point; scene changes and camera angles still require careful review.
Use the community scripting tool
The Handy simple scripter provides a browser-based scripting tool. Its community license permits creating free, publicly available scripts. Contact the Handy team if you need a different use or are unsure whether your project fits that license.
Create a script manually
Manual scripting gives you control over each part of the motion, but it takes time. The manual scripting tutorial demonstrates two common methods.
A useful working sequence is:
- Match the script's starting point to the video's timeline.
- Add positions at the times where the intended motion changes.
- Review the sequence against the video, including cuts, pauses, and transitions.
- Export a supported script and check its times and positions before playback.
Keep the file's timestamps in milliseconds and its positions from 0 through 100. The format examples show equivalent funscript and CSV representations.
Arrange assisted scripting
Contact the Handy team before using its assisted scripting pipeline. Agree on access and upload instructions for your account; the pipeline is separate from the public APIs used to store or play scripts.
Follow the scripting-pipeline guide for SSH keys, SFTP setup, video classification, and stable identifiers. Providers can use script tokens to manage access to the resulting scripts.
The workflow combines automated analysis with human review:
- Upload the video using the supplied instructions.
- Verify the upload and provide its identifier, priority, and other requested parameters.
- The video enters the scripting queue. Computer vision and machine learning produce an initial script.
- A scripter reviews the result and manually completes or corrects sections that need attention.
- The script passes quality review before publication. Publication to a script index can be arranged separately.
The amount of manual work depends on the video. Do not assume that an automatically generated script is ready for playback without review.
Review and share your work
Review the complete timeline, including the beginning and end. Check that movement targets follow the intended action and that transitions are deliberate.
Community resources include both free and paid scripts. Contact the Handy team for pointers to script communities. Share videos and scripts only when you have permission to distribute them, and follow the licensing terms of the tools and content you use.
Prepare the script for playback
For a local script file, Hosting API v2 provides a temporary URL. For reusable server-side content, Stream API v0 stores a script and provides a stream reference.
Use Handy REST API v3 to control playback and keep motion aligned with media. File authoring and playback synchronization are separate steps: a well-timed script still needs the playback application's clock and media position to agree.