Media.seek
luastra/mediaMedia.seek(positionMs: number): RequestId
Requests movement of the selected media item to the supplied non-negative millisecond position. The host clamps or rejects values according to the current duration and reports the resulting state asynchronously.
Before you use it
Add luastra/media to this module's dependencies in luastra.json, then import it with require("luastra/media"). Declare media.command in luastra.json. Set an admitted queue before playback, start playback from an explicit user action where required, and implement both app.resolve and media_state handling.
How it fits
The command returns a RequestId for acknowledgement. Actual playback truth arrives independently through app.handle("media_state", target, payload) and must be decoded before rendering.
When to use it
Use Media.seek for a user-operated scrubber, skip control, or explicit chapter jump. Base the target on decoded duration and position, and do not issue a request for every unthrottled pointer movement.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| positionMs | number | Requested non-negative position in milliseconds within the selected item. |
Returns
RequestId — an opaque request identifier used to correlate the asynchronous completion in app.resolve.
What happens next
A RequestId now, then command completion and subsequent decoded live-state updates when playback changes.
Failures and fixes
Missing capability, absent queue, invalid asset/content URI, autoplay policy, interruption, unsupported background behavior, or host failure must remain visible state. Do not optimistically treat command acknowledgement as playback success.
Availability
Public-source alpha API in 0.5.0-alpha; background playback and system controls require target-specific verification.
Focused example
local Media = require("luastra/media")
Media.seek(30_000)