Stroker Setup

Read the stroker’s live motion state and calibration bounds, and set the software limits it moves within. All requests go to:

https://api.getmelody.io

All protected requests require:

Authorization: Bearer <SESSION_TOKEN>
X-Device-Key: <DEVICE_KEY>
Content-Type: application/json

Stroker Status (Read)

Dynamic positional and velocity state of the linear haptic actuator (“Stroker”).

Field	Type	Description
`current_pos_angle`	`float`	Current stroker position (radians)
`current_pos_range`	`int32`	Current position (0–10000 points)
`target_pos_angle`	`float`	Current motion target position (radians)
`target_pos_range`	`int32`	Target position (0–10000 points)
`current_vel_angle`	`float`	Current velocity (radians/second)
`current_vel_range`	`int32`	Current velocity (points/s)

Stroker Calibration Info (Read)

Hardware-derived physical motion boundaries captured during calibration.

Field	Type	Description
`calib_low_position`	`float`	Lowest physically blocked position (rad)
`calib_high_position`	`float`	Highest physically blocked position (rad)
`calibration_length`	`float`	Total stroke length detected during calibration (rad)
`hall_low_position`	`float`	Hall sensor reading at low calibration limit (rad)
`hall_high_position`	`float`	Hall sensor reading at high calibration limit (rad)
`calib_shift`	`float`	Offset applied after calibration when only the encoder is used (rad)

Calibration values are reported in radians. The user limits in Stroker Settings below are the ones expressed in millimeters.

Stroker Settings (Read/Write)

Software limits and motion preferences that operate inside calibration bounds.

Field	Type	Description
`low_position_shift`	`float`	User offset from calibrated low limit (mm)
`high_position_shift`	`float`	User offset from calibrated high limit (mm)
`max_velocity`	`float`	Upper speed limit, on the device’s own scale: `10` by default, `50` at the top (the device screen shows it as 20 steps). This is not the same number as `current_vel_range`, which reports points per second, or the HLC `velocity`, which is a percentage
`playback_rate`	`float`	Playback speed multiplier (1.0 = normal speed)

POST /device/stroker/settings is a partial update, like POST /device/settings: send only the fields you want to change and the rest keep their current values. A 0 you do send is a value, not an omission, and an unknown field name is rejected with 400.

Notes

Adjust position shifts and the velocity cap only after a successful calibration.
Keep user motion bounds inside the calibration limits detected by the hardware.
Apply a velocity cap when streaming (HPS) or looping (HLC).
Position shifts are in millimeters, relative to the calibration bounds.

For the endpoints behind these fields — GET /device/stroker/status, GET /device/stroker/calibration, and GET/POST /device/stroker/settings — see the Melody API Reference.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Stroker Status (Read)

Stroker Calibration Info (Read)

Stroker Settings (Read/Write)

Notes

​Stroker Status (Read)

​Stroker Calibration Info (Read)

​Stroker Settings (Read/Write)

​Notes

Stroker Status (Read)

Stroker Calibration Info (Read)

Stroker Settings (Read/Write)

Notes