Playback Protocols

The Melody device is our in‑house engineered interactive haptic hardware hub.
All WiFi playback requests are executed live against: https://api.getmelody.io" Authenticated requests must include:

Authorization: Bearer <SESSION_TOKEN>
X-Device-Key: <DEVICE_KEY>
Content-Type: application/json

1. Playback Protocol (Read / Write)

Select the active playback protocol before issuing any control commands.

Field	Type	Values
`playbackProtocol`	`enum`	`HDC`, `HSC`, `HPS`, `HLC`

Playback Source (Read)

Indicates the current origin of device control.

Field	Type	Values
`playbackSource`	`enum`	`IDLE`, `MANUAL`, `WIFI`, `BLE`

HSC — Haptics Script Control

Transport: WiFi only
Behavior: Script playback from a remote .funscript file via URL. The server orchestrates timeline playback.

Start Playback (Write)

Field	Type	Description
`time`	`uint32`	Start time in milliseconds
`scriptUrl`	`string`	Public URL of the funscript file
`scriptSize`	`uint32`	Script size in bytes

Stop Playback (Write)

Interrupt and stop script playback.

Script Status (Read)

Field	Type	Description
`playing`	`bool`	Whether script playback is active
`currentScriptTime`	`uint32`	Current playback time (ms)
`currentScriptIndex`	`uint32`	Current script frame index
`playbackRate`	`float`	Playback speed multiplier (configurable in settings)

Use for: synchronized sensations for videos, VR players, and timeline-driven playback systems.

HDC — Haptics Direct Control

Transport: WiFi, BLE
Behavior: Immediate position control. Every new command interrupts active movement.

Motion Command (Write)

Field	Type	Range	Description
`position`	`uint32`	`0 → 10000`	Target position (0.01% resolution)
`time`	`uint32`	ms	Movement duration in milliseconds

Motion Status (Read)

Field	Type	Description
`playing`	`bool`	Whether movement is active
`destinationPosition`	`uint32`	Last issued target position

Use for: UI manual controls, external timeline drivers, and interruptible positional motion.

HPS — Haptics Points Stream

Transport: WiFi, BLE Behavior: Stream sequential position + timestamp points. The device calculates velocity using time‑delta differences between points. Requirements:

Minimum 2 points required for velocity calculation
Maximum 64 points per message

Add Points (Write)

Field	Type	Range	Description
`time`	`uint32`	ms	Timestamp in milliseconds
`pos`	`uint32`	`0 → 10000`	Position (0.01% resolution)

Note: If time delta between points is negative, the previous point timestamp is treated as 0.

Play Stream (Write)

Starts stream playback using buffered points.

Pause Stream (Write)

Pauses without clearing the buffer.

Flush Stream (Write)

Clears the buffered point queue.

Stream Status (Read)

Field	Type	Description
`playing`	`bool`	Whether point stream is active
`currentStreamTime`	`uint32`	Current playback time (ms)
`pointsLeft`	`uint32`	Remaining points in the buffer

Use for: Real-time haptic streaming, dynamic timelines, and smooth motion derived from time‑delta input.

HLC — Haptics Loop Control

Transport: WiFi, BLE Behavior: Automatic, repeating up/down stroking loop inside a defined range.

Set Loop Parameters (Write)

Field	Type	Description
`velocity`	`float`	Loop velocity
`lowLimit`	`float`	Loop low position, must be < highLimit
`highLimit`	`float`	Loop high position, must be > lowLimit

Start Loop (Write)

Begins automatic haptic loop.

Stop Loop (Write)

Stops loop playback safely and clears active loop state.

Loop Status (Read)

Field	Type	Description
`playing`	`bool`	Whether loop is active
`velocity`	`float`	Current loop velocity
`lowLimit`	`float`	Active low loop position
`highLimit`	`float`	Active high loop position

Use for: Continuous and rhythmic motion patterns driven by firmware.

Summary

Protocol	Interruptible	Transport	Timing Model
HSC	✗	WiFi only	Script timeline
HDC	✓	WiFi, BLE	Client duration
HPS	✓	WiFi, BLE	Time‑delta velocity
HLC	✓	WiFi, BLE	Firmware auto‑loop

You’re ready to send playback and motion commands — just set the protocol first, then explore the reference tabs for deeper technical detail.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Playback Protocols

1. Playback Protocol (Read / Write)

Playback Source (Read)

HSC — Haptics Script Control

Start Playback (Write)

Stop Playback (Write)

Script Status (Read)

HDC — Haptics Direct Control

Motion Command (Write)

Motion Status (Read)

HPS — Haptics Points Stream

Add Points (Write)

Play Stream (Write)

Pause Stream (Write)

Flush Stream (Write)

Stream Status (Read)

HLC — Haptics Loop Control

Set Loop Parameters (Write)

Start Loop (Write)

Stop Loop (Write)

Loop Status (Read)

Summary

​1. Playback Protocol (Read / Write)

​Playback Source (Read)

​HSC — Haptics Script Control

​Start Playback (Write)

​Stop Playback (Write)

​Script Status (Read)

​HDC — Haptics Direct Control

​Motion Command (Write)

​Motion Status (Read)

​HPS — Haptics Points Stream

​Add Points (Write)

​Play Stream (Write)

​Pause Stream (Write)

​Flush Stream (Write)

​Stream Status (Read)

​HLC — Haptics Loop Control

​Set Loop Parameters (Write)

​Start Loop (Write)

​Stop Loop (Write)

​Loop Status (Read)

​Summary

1. Playback Protocol (Read / Write)

Playback Source (Read)

HSC — Haptics Script Control

Start Playback (Write)

Stop Playback (Write)

Script Status (Read)

HDC — Haptics Direct Control

Motion Command (Write)

Motion Status (Read)

HPS — Haptics Points Stream

Add Points (Write)

Play Stream (Write)

Pause Stream (Write)

Flush Stream (Write)

Stream Status (Read)

HLC — Haptics Loop Control

Set Loop Parameters (Write)

Start Loop (Write)

Stop Loop (Write)

Loop Status (Read)

Summary