Skip to main content
The Melody Device is the interactive haptics hardware we engineered in‑house, paired with the Melody sensation‑scripting ecosystem.
Default Bluetooth (BLE) broadcast name is MEL-############, where ############ - are the 6-byte device BLE MAC address. All command and scripting integrations are handled through the single production API: Melody API: https://api.getmelody.io

​
Glossary

​
General Terms

​
Device Components

​
Position Terminology

​
Velocity Terminology

​
Playback States

​
Data Ranges

​
Device Modes

​
Active Control Modes

Playback mode is selected using the physical mode button on the device.

​
Service / Maintenance Modes

Stroker motion is disabled during service modes for safety.

​
Playback Protocols

​
HDC (Haptics Direct Control)

Supported Transports: WiFi, BLE
Direct position control where you define a target position and movement duration. Best for:
  • Manual control
  • UI‑driven or interactive applications
  • Simple positional motion

​
HSC (Haptics Script Control)

Supported: WiFi only
Device downloads a motion script from a remote URL, while the server orchestrates start, stop, pause, and seek. Best for:
  • Pre‑recorded video or VR content
  • Scripted and synchronized playback

​
HPS (Haptics Points Stream)

Supported Transports: WiFi, BLE
Stream timestamped motion points; the device calculates velocity using time deltas between sequential points. Requirements: Min 2 points to compute motion velocity. Best for:
  • Real‑time streaming experiences
  • Dynamically generated motion content
  • External timeline drivers

​
HLC (Haptics Loop Control)

Supported Transports: WiFi, BLE
Automatic stroking loop inside a defined motion range at a set velocity. Best for:
  • Continuous rhythmic sensation loops
  • Automatic repeating motion patterns

​
API Coverage Summary

​
WiFi vs BLE Protocol Differences

​
Command Size & Encoding

  • WiFi API uses 32/64-bit values (flexible numeric types, larger payloads)
  • BLE API uses packed binary (optimized for MTU limits of ~512 bytes)
Examples:
  • HDC Command WiFi: 2×uint32 (8 bytes) BLE: 2×uint16 (4 bytes, packed binary)
  • HPS Point Stream WiFi: uint32 pos + uint64 time BLE: uint16 pos + uint32 time (6 bytes, packed)
Why: BLE has strict MTU limits and requires compact data types.

​
Position Range

  • Both transports use 0–10000 ranged position values
  • Resolution: 0.01% of full motion range
  • BLE uses uint16 (max 65535, enough for range)
  • WiFi uses 32-bit values for protocol flexibility

​
Time Limits by Protocol

​
Ecosystem Philosophy

Melody was designed to be:
  • Universal – partner devices behave consistently via shared command schemas
  • Seekable – timeline‑driven playback state control
  • Smooth – motion interpolation derived automatically from point streams
  • Secure – protected by JWT bearer authentication as defined in OpenAPI
Hardware + Engine + SDK + Media Scripting = One ecosystem.
Developers implement once, creators script once — every supported device feels in sync.
Next: explore how to upload scripts, start sessions, and stream motion in the dedicated API reference tabs.