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 <YOUR_JWT_TOKEN>
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`	`uint64`	ms	Timestamp in the sender’s timescale
`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 percentage range.

⚙ Set Loop Parameters (Write)

Field	Type	Range	Description
`velocity`	`uint32`	`0 → 100%`	Percent of max velocity
`lowLimit`	`uint32`	`0–99%`	Loop low position, must be < highLimit
`highLimit`	`uint32`	`1–100%`	Loop high position, must be > lowLimit

▶ Start Loop (Write)

Begins automatic haptic loop.

⏸ Stop Loop (Write — “Pause” command)

Stops loop playback safely and clears active loop state.

📊 Loop Status (Read)

Field	Type	Description
`playing`	`bool`	Whether loop is active
`velocity`	`uint32`	Current loop velocity (%)
`lowLimit`	`uint32`	Active low loop position (%)
`highLimit`	`uint32`	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 WiFi

Melody BLE

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 — “Pause” command)

📊 Loop Status (Read)

Summary

Getting started

Melody

Melody WiFi

Melody BLE

​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 — “Pause” command)

​📊 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 — “Pause” command)

📊 Loop Status (Read)

Summary