Media.decodeState
luastra/mediaMedia.decodeState(payload: string): DecodeResult
Validates and decodes a media-state payload into a discriminated Media.DecodeResult containing the typed playback State or a bounded failure. This keeps host strings outside trusted application state until checked.
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
Media.decodeState synchronously validates a media_state or Media.state payload. On success, playback fields are under result.state.
When to use it
Use Media.decodeState for every media_state event and successful Media.state response before updating controls, lock-screen-facing state, or persistence. Preserve the previous known state when decoding fails.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| payload | string | Untrusted media-state event or state-response payload. |
Returns
DecodeResult — a discriminated decode result; branch on success before reading decoded fields or failure data.
What happens next
A tagged result containing result.state or a bounded decode error.
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")
local result = Media.decodeState(payload)
if result.success then positionMs = result.state.positionMs else errorMessage = result.error endContinue with a complete recipe
This checked recipe uses Media.decodeState inside complete authored files with the required manifest, test, and run steps.
Open play packaged audio recipe