All WiFi playback requests are executed live against:
https://api.getmelody.io"
Authenticated requests must include:
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 onlyBehavior: 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) |
HDC — Haptics Direct Control
Transport: WiFi, BLEBehavior: 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 |
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 |
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 — “Pause” command)
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 |
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 |