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 asvideo-123_vr_.mp4orvideo-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.