Skip to content
Handyverse documentation

Show interactive endpoint panels inside human guides. This preference is saved for future visits.

Choose an API
Shared guides · Developer resourcesView Markdown

Scripting pipeline

The Handy scripting pipeline turns uploaded videos into reviewed movement scripts. Arrange access with the Handy team before uploading. You will receive an upload host, username, and instructions for associating your videos with their scripts.

This guide covers video delivery and naming. See Scripting for the automated analysis, manual review, and quality checks that follow an upload.

Create an SSH key

Generate a key pair locally with OpenSSH, or use PuTTYgen if that is your preferred SSH tool. For example:

mkdir -p "$HOME/.ssh"
ssh-keygen -t ed25519 -f "$HOME/.ssh/handy-scripting" -C 'Handy scripting upload'

Choose a passphrase when prompted. The example creates a private key named handy-scripting and a public key named handy-scripting.pub.

Send the Handy team the public key only so it can be registered for your upload account:

cat "$HOME/.ssh/handy-scripting.pub"

Keep the private key on your computer. Your transfer client uses it to authenticate; it is not an API Authentication Key or client token.

Configure an SFTP client

FileZilla is available for Windows, macOS, and Linux. Another client that supports SFTP with SSH-key authentication can also be used.

In FileZilla, open File → Site Manager → New Site and enter:

Setting Value
Host Upload host supplied during onboarding
Port 22
Protocol SFTP
Logon type Key file
User Assigned upload username
Key file Your private key, such as .ssh/handy-scripting

Connect using the registered account. Confirm the server's SSH host-key fingerprint with the Handy team when connecting for the first time.

Identify VR and flat videos

The upload area uses these paths:

/upload
/upload/_vr_
/upload/_flat_

Use a folder or filename to identify the video format:

  • Upload VR videos to /upload/_vr_ and flat videos to /upload/_flat_.
  • Alternatively, include _vr_ or _flat_ in the filename, such as video-123_vr_.mp4 or video-123_flat_.mp4.
  • If your site already uses a different naming convention, agree on the detection rules with the Handy team before uploading.

Preserve the video identifier

Give each video a stable, unique identifier that your integration can reference later. An identifier from your site's video URL is suitable, provided it uniquely identifies that video.

For example:

Item Example
Video URL https://example.com/videos/video-123
Video identifier video-123
Upload path /upload/_flat_/video-123.mp4

Agree on how the identifier is extracted from your filenames. Keep its spelling consistent between uploads and later provider requests; changing punctuation can change the identifier.

This association also matters when a provider authorizes playback using script tokens: the video identifier must resolve to the intended script.

Complete and verify the upload

Upload the video and check that the transfer completed successfully. Verify the upload in the account interface provided by the Handy team, then set any requested identifiers, priority, or processing parameters.

The video can then proceed through the assisted scripting workflow. A completed file transfer is the delivery step; script review and publication follow separately.