Synchronizing with Scripts

A tutorial outlining how to programmatically send scripts to the Handy.


In our third tutorial, we’ll write some code to send a script file to the Handy, and then we’ll have the Handy play the script.

What are scripts?

In the context of the Handy, a script is a file that tells the Handy where it should position its stroker arm at a given point in time. Most often a script is created to map the movement of adult videos so that the motions seen on screen can be recreated by the Handy.

You can read more about the technical details of scripts here.

Invoke the Handy UI

As usual, we’ll invoke the Handy UI on our page using the code from our previous tutorial:

The script file

For our purposes, we’ll use our script for testing Handy synchronization. It can be found at the following URL:

Timing and order of operations

When we send a script to the Handy, we actually perform a file transfer of the script to the memory of the Handy itself. As a consequence, though the script file is small, it takes a bit of time before the Handy reacts to the script.

As such, the best practice for sending a script to the Handy first involves sending the script, then waiting for a response from the Handy to confirm that it is ready, and then telling the Handy to play the script.

That may sound cumbersome, but it works out quite nicely with the use of asynchronous events.

The code

For our purposes, we’ll create a simple function that assigns the URL of the script file to a variable, then calls the setScript() function, and then waits for the setScript function to fulfull its promise asynchronously.

In this way, the script will never try to play until the Handy is ready to play it.

Let’s walk through it step by step:

Step 1

Assign the script URL to a variable:

var scriptURL = "";

Step 2

Next, we call the setScript() function and pass in the script variable:


This by itself is enough to send the script to the Handy — but we still need to tell the Handy to play the script.

This is done with the hsspPlay() function. However, it is not enough to execute setScript() and hsspPlay() sequentially. setScript() actually sends the script data to the Handy and this transfer time takes a moment. So if we tell the Handy to play a script immediately after setting the script, the Handy will still not have a script to play and will throw an error.

Instead, we’ll leverage the fact that setScript() returns a promise, and we’ll only execute hsspPlay() when that promise is fulfilled. That is, hsspPlay() will only run once setScript() has confirmed that it has completed its operation.

This will look like the following:

HANDY.setScript(scriptURL).then((value) => {
  HANDY.hsspPlay(0, HANDY.getEstimatedServerTime);

Step 3

Finally, we’ll assign the code we have created to a Play button, and we’ll add a Stop button as well. For clarity of execution steps, we’ll also change the text of the Play button to represent the state of the script loading.

Putting it all together looks like the following:

function setScriptAndPlay() {
  var scriptURL = "";
  document.getElementById("play-btn").innerText = "Setting script...";
  HANDY.setScript(scriptURL).then((value) => {
    HANDY.hsspPlay(0, HANDY.getEstimatedServerTime);
    document.getElementById("play-btn").innerText = "Playing script";

function stopPlay(){
  document.getElementById("play-btn").innerText = "Set Script and Play";

<button id="play-btn" onClick="setScriptAndPlay()">Set Script and Play</button>
<button onClick='stopPlay()'>Stop</button>

And this is what it will look like:

Feel free to play around to get a feeling for the network delay of sending a script.

Next Steps

Now that we have our Handy playing scripts, we’ll explore how to synchronize those scripts with their corresponding video content.