> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmelody.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Playback Protocols

> Select and control haptic playback protocols (HDC, HSC, HPS, HLC) on the Melody hardware device using WiFi transport over Melody API.

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:

```http theme={null}
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.