Media.setQueue
luastra/mediaMedia.setQueue(items: { QueueItem }, selectedIndex: number?): RequestIdReplaces the host playback queue with validated QueueItem values and optionally selects a one-based item, returning a RequestId. The host reports later playback changes through media_state events.
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.setQueue before play when the application owns a new playlist, meditation sequence, or sound set. Keep stable item IDs, validate the selected index, and avoid rebuilding an unchanged queue on every render.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| items | { QueueItem } | Bounded ordered QueueItem values with stable IDs and admitted sources. |
| selectedIndex | number? | Optional one-based item selected after the queue is installed. |
| items[].id | string (1..128 bytes) | Stable application-owned item identifier. |
| items[].source | asset:* | content:* | Admitted project asset URI or scoped content grant. |
| items[].title | string (1..256 bytes) | Track title shown by application and host playback surfaces. |
| items[].artist | string (1..256 bytes) | Artist or collection label shown by playback surfaces. |
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.setQueue({ { id = "intro", source = "asset:audio/intro", title = "Intro", artist = "Luastra" } })Continue with a complete recipe
This checked recipe uses Media.setQueue inside complete authored files with the required manifest, test, and run steps.
Open play packaged audio recipe