Playback Protocols

The Melody Device supports four playback protocols. Select one, then send the control commands that belong to it. All WiFi playback requests go to: 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, via GET/POST /device/mode.

Field	Type	Values
`playback_protocol`	`enum`	`hdc`, `hsc`, `hps`, `hlc`

HSC — Haptic Script Control

Transport: WiFi only
Behavior: the device plays a funscript that you upload first; the server then orchestrates timeline playback. Playback is a two-step flow: 1. Upload the script — POST /device/hsc/upload (up to 10 MB):

Field	Type	Description
`name`	`string`	Script name
`content`	`string`	Funscript JSON, as text

2. Start playback — POST /device/hsc/start:

Field	Type	Description
`time`	`uint32`	Start time in milliseconds
`server_time_ms`	`uint64`	The server time in milliseconds according to the client
`loop`	`bool`	Play the script cyclically

server_time_ms is optional; time is required. Seek, pause, and stop are POST /device/hsc/{seek,pause,stop}.

Script Status (Read) — `GET /device/hsc/status`

Field	Type	Description
`is_playing`	`bool`	Whether script playback is active
`script_time`	`uint32`	Current playback time (ms)
`script_position`	`uint32`	Current script position (0–10000)

HDC — Haptic 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. Required — `time: 0` is rejected with `400 time must be set`

Motion Status (Read) — `GET /device/hdc/status`

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

HPS — Haptic 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
Over WiFi, up to 10,000 points per POST /device/hps/signal request (the 64-points-per-write limit applies to BLE only)

Add Points (Write)

Points travel inside a points array — the body is {"points": [{"time": …, "pos": …}, …]}, not a bare point.

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. Accepts an optional loop (bool) field to replay the buffer.

Pause Stream (Write)

Pauses without clearing the buffer.

Flush Stream (Write)

Clears the buffered point queue.

Stream Status (Read) — `GET /device/hps/status`

Field	Type	Description
`is_playing`	`bool`	Whether the point stream is active
`stream_time`	`uint32`	Current playback time (ms)
`points_left`	`uint32`	Remaining points in the buffer

HLC — Haptic 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, `0 → 100`. Outside that range the request is rejected with `400`
`low_limit`	`float`	Loop low position, `0 → 10000`. Must be ≤ high_limit
`high_limit`	`float`	Loop high position, `0 → 10000`. Must be ≥ low_limit

Equal limits are accepted — the check is low_limit > high_limit, so a zero-width range is not an error. Every bound above is validated server-side and answered with 400 and a message naming the field.

Start Loop (Write)

Begins automatic haptic loop.

Pause Loop (Write)

Pauses the loop, keeping the configured range and velocity.

Stop Loop (Write)

Stops loop playback safely and clears active loop state.

Loop Status (Read) — `GET /device/hlc/status`

Field	Type	Description
`is_playing`	`bool`	Whether the loop is active
`velocity`	`float`	Current loop velocity
`low_limit`	`float`	Active low loop position
`high_limit`	`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

Set the protocol first, then send its commands. Full request and response schemas are in the Melody API Reference.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Playback Protocols

1. Playback Protocol (Read / Write)

HSC — Haptic Script Control

Script Status (Read) — `GET /device/hsc/status`

HDC — Haptic Direct Control

Motion Command (Write)

Motion Status (Read) — `GET /device/hdc/status`

HPS — Haptic Points Stream

Add Points (Write)

Play Stream (Write)

Pause Stream (Write)

Flush Stream (Write)

Stream Status (Read) — `GET /device/hps/status`

HLC — Haptic Loop Control

Set Loop Parameters (Write)

Start Loop (Write)

Pause Loop (Write)

Stop Loop (Write)

Loop Status (Read) — `GET /device/hlc/status`

Summary

​1. Playback Protocol (Read / Write)

​HSC — Haptic Script Control

​Script Status (Read) — GET /device/hsc/status

​HDC — Haptic Direct Control

​Motion Command (Write)

​Motion Status (Read) — GET /device/hdc/status

​HPS — Haptic Points Stream

​Add Points (Write)

​Play Stream (Write)

​Pause Stream (Write)

​Flush Stream (Write)

​Stream Status (Read) — GET /device/hps/status

​HLC — Haptic Loop Control

​Set Loop Parameters (Write)

​Start Loop (Write)

​Pause Loop (Write)

​Stop Loop (Write)

​Loop Status (Read) — GET /device/hlc/status

​Summary

1. Playback Protocol (Read / Write)

HSC — Haptic Script Control

Script Status (Read) — `GET /device/hsc/status`

HDC — Haptic Direct Control

Motion Command (Write)

Motion Status (Read) — `GET /device/hdc/status`

HPS — Haptic Points Stream

Add Points (Write)

Play Stream (Write)

Pause Stream (Write)

Flush Stream (Write)

Stream Status (Read) — `GET /device/hps/status`

HLC — Haptic Loop Control

Set Loop Parameters (Write)

Start Loop (Write)

Pause Loop (Write)

Stop Loop (Write)

Loop Status (Read) — `GET /device/hlc/status`

Summary