video

Video playback — create / play / pause / seek / setRate / setLoop / destroy on render-target-backed video players.The live picture of a webcam or phone camera is cameraInput.

require("@builtin::modules.api.engine.video") -- video (also available as global 'video')

The video namespace: 27 functions.

globals/video/create

video.create(url: string, options: VideoOptions?) -> string

Create a video player. Returns a texture handle (e.g. "video_0") usable directly in material.setTexture() — its frames sample like any other texture.

Parameters

• url string — URL or asset path to an MP4 video file.
• options VideoOptions (optional) — Playback options: loop (default false), autoplay (default false), rate (default 1.0).

Returns string — Texture handle.

local tex = video.create("http://example.com/clip.mp4", { autoplay = true })

globals/video/destroy

video.destroy(handle: string) -> boolean

Destroy a video player and free the render target and all resources.

Parameters

• handle string — Video handle from video.create.

Returns boolean — True if the player was found and destroyed.

video.destroy(rt)

globals/video/getInfo

video.getInfo(handle: string) -> VideoInfo?

Get video information and current playback state. codec is the configuration the stream declares, such as "avc1.64002a", and codecSupported is this host's answer about decoding it: true where it has a decoder, false where it has none, and nil while the answer is still being fetched. state reads "unsupported" for a stream this host has no decoder for, with error naming the codec and what refused it, and no frame is produced for it. The frame counts describe playback since create: framesDecoded is how many frames the decoder produced, framesPresented how many the player handed to its texture, framesExpected how many frames the playback clock reached (one per frame interval a tick landed in), and frameThreadDecodes how many samples were decoded on the engine's frame thread rather than on the decoder's own.

Parameters

• handle string — Video handle.

Returns VideoInfo? — { width, height, duration, currentTime, state, rate, loop, codec, codecSupported, error, framesDecoded, framesPresented, framesExpected, frameThreadDecodes } or nil if the handle is invalid.

local i = video.getInfo(rt); print(i.currentTime, "/", i.duration)

globals/video/pause

video.pause(handle: string) -> boolean

Pause video playback. Can be resumed with video.play.

Parameters

• handle string — Video handle.

Returns boolean — True if the video was playing and is now paused, or was still loading with a play carried and that play is withdrawn. False for a player that was not playing (ready, paused, ended, error, unsupported) and for a handle that names no player.

video.pause(rt)

globals/video/play

video.play(handle: string) -> boolean

Start or resume video playback.

Parameters

• handle string — Video handle from video.create.

Returns boolean — True if the command was accepted: the player is loading (the play is carried until the load lands), ready, playing, paused or ended. False for a handle that names no player and for one in error or unsupported, which never plays.

video.play(rt)

globals/video/seek

video.seek(handle: string, time: number) -> boolean

Seek to a specific time (seconds) in the video.

Parameters

• handle string — Video handle.
• time number — Target time in seconds.

Returns boolean — True if the seek was accepted; false for a handle that names no player and for one in error or unsupported.

video.seek(rt, 30.5)

globals/video/setLoop

video.setLoop(handle: string, loop: boolean) -> boolean

Enable or disable looping.

Parameters

• handle string — Video handle.
• loop boolean — Whether to loop playback.

Returns boolean — True if the setting was applied.

video.setLoop(rt, true)

globals/video/setRate

video.setRate(handle: string, rate: number) -> boolean

Set the playback speed multiplier. 1.0 = normal, 2.0 = double speed, 0.5 = half speed.

Parameters

• handle string — Video handle.
• rate number — Playback rate.

Returns boolean — True if the rate was set.

video.setRate(rt, 2.0)

globals/video/stop

video.stop(handle: string) -> boolean

Stop video playback and reset to the beginning.

Parameters

• handle string — Video handle.

Returns boolean — True if the command was accepted; false for a handle that names no player and for one in error or unsupported.

video.stop(rt)

modules/video/create

create(url: string, options: VideoOptions?): string

Create a video player. Returns a texture handle (e.g. "video_0") usable directly in material.setTexture() — its frames sample like any other texture.

Parameters

• url string — URL or asset path to an MP4 video file.
• options VideoOptions? (optional) — Playback options: loop (default false), autoplay (default false), rate (default 1.0).

local tex = video.create("http://example.com/clip.mp4", { autoplay = true })

modules/video/destroy

destroy(handle: string): boolean

Destroy a video player and free the render target and all resources.

Parameters

• handle string — Video handle from video.create.

video.destroy(rt)

modules/video/getInfo

getInfo(handle: string): VideoInfo?

Get video information and current playback state. codec is the configuration the stream declares, such as "avc1.64002a", and codecSupported is this host's answer about decoding it: true where it has a decoder, false where it has none, and nil while the answer is still being fetched. state reads "unsupported" for a stream this host has no decoder for, with error naming the codec and what refused it, and no frame is produced for it. The frame counts describe playback since create: framesDecoded is how many frames the decoder produced, framesPresented how many the player handed to its texture, framesExpected how many frames the playback clock reached (one per frame interval a tick landed in), and frameThreadDecodes how many samples were decoded on the engine's frame thread rather than on the decoder's own.

Parameters

• handle string — Video handle.

local i = video.getInfo(rt); print(i.currentTime, "/", i.duration)

modules/video/pause

pause(handle: string): boolean

Pause video playback. Can be resumed with video.play.

Parameters

• handle string — Video handle.

video.pause(rt)

modules/video/play

play(handle: string): boolean

Start or resume video playback.

Parameters

• handle string — Video handle from video.create.

video.play(rt)

modules/video/seek

seek(handle: string, time: number): boolean

Seek to a specific time (seconds) in the video.

Parameters

• handle string — Video handle.
• time number — Target time in seconds.

video.seek(rt, 30.5)

modules/video/setLoop

setLoop(handle: string, loop: boolean): boolean

Enable or disable looping.

Parameters

• handle string — Video handle.
• loop boolean — Whether to loop playback.

video.setLoop(rt, true)

modules/video/setRate

setRate(handle: string, rate: number): boolean

Set the playback speed multiplier. 1.0 = normal, 2.0 = double speed, 0.5 = half speed.

Parameters

• handle string — Video handle.
• rate number — Playback rate.

video.setRate(rt, 2.0)

modules/video/stop

stop(handle: string): boolean

Stop video playback and reset to the beginning.

Parameters

• handle string — Video handle.

video.stop(rt)

typed/builtin//modules/api/engine/video/video/create

video.create(url: string, options: VideoOptions?) -> string

Create a video player. Returns a texture handle (e.g. "video_0") usable directly in material.setTexture() — its frames sample like any other texture.

Parameters

• url string — URL or asset path to an MP4 video file.
• options VideoOptions (optional) — Playback options: loop (default false), autoplay (default false), rate (default 1.0).

Returns string — Texture handle.

local tex = video.create("http://example.com/clip.mp4", { autoplay = true })

typed/builtin//modules/api/engine/video/video/destroy

video.destroy(handle: string) -> boolean

Destroy a video player and free the render target and all resources.

Parameters

• handle string — Video handle from video.create.

Returns boolean — True if the player was found and destroyed.

video.destroy(rt)

typed/builtin//modules/api/engine/video/video/getInfo

video.getInfo(handle: string) -> VideoInfo?

Get video information and current playback state. codec is the configuration the stream declares, such as "avc1.64002a", and codecSupported is this host's answer about decoding it: true where it has a decoder, false where it has none, and nil while the answer is still being fetched. state reads "unsupported" for a stream this host has no decoder for, with error naming the codec and what refused it, and no frame is produced for it. The frame counts describe playback since create: framesDecoded is how many frames the decoder produced, framesPresented how many the player handed to its texture, framesExpected how many frames the playback clock reached (one per frame interval a tick landed in), and frameThreadDecodes how many samples were decoded on the engine's frame thread rather than on the decoder's own.

Parameters

• handle string — Video handle.

Returns VideoInfo? — { width, height, duration, currentTime, state, rate, loop, codec, codecSupported, error, framesDecoded, framesPresented, framesExpected, frameThreadDecodes } or nil if the handle is invalid.

local i = video.getInfo(rt); print(i.currentTime, "/", i.duration)

typed/builtin//modules/api/engine/video/video/pause

video.pause(handle: string) -> boolean

Pause video playback. Can be resumed with video.play.

Parameters

• handle string — Video handle.

Returns boolean — True if the video was playing and is now paused, or was still loading with a play carried and that play is withdrawn. False for a player that was not playing (ready, paused, ended, error, unsupported) and for a handle that names no player.

video.pause(rt)

typed/builtin//modules/api/engine/video/video/play

video.play(handle: string) -> boolean

Start or resume video playback.

Parameters

• handle string — Video handle from video.create.

Returns boolean — True if the command was accepted: the player is loading (the play is carried until the load lands), ready, playing, paused or ended. False for a handle that names no player and for one in error or unsupported, which never plays.

video.play(rt)

typed/builtin//modules/api/engine/video/video/seek

video.seek(handle: string, time: number) -> boolean

Seek to a specific time (seconds) in the video.

Parameters

• handle string — Video handle.
• time number — Target time in seconds.

Returns boolean — True if the seek was accepted; false for a handle that names no player and for one in error or unsupported.

video.seek(rt, 30.5)

typed/builtin//modules/api/engine/video/video/setLoop

video.setLoop(handle: string, loop: boolean) -> boolean

Enable or disable looping.

Parameters

• handle string — Video handle.
• loop boolean — Whether to loop playback.

Returns boolean — True if the setting was applied.

video.setLoop(rt, true)

typed/builtin//modules/api/engine/video/video/setRate

video.setRate(handle: string, rate: number) -> boolean

Set the playback speed multiplier. 1.0 = normal, 2.0 = double speed, 0.5 = half speed.

Parameters

• handle string — Video handle.
• rate number — Playback rate.

Returns boolean — True if the rate was set.

video.setRate(rt, 2.0)

typed/builtin//modules/api/engine/video/video/stop

video.stop(handle: string) -> boolean

Stop video playback and reset to the beginning.

Parameters

• handle string — Video handle.

Returns boolean — True if the command was accepted; false for a handle that names no player and for one in error or unsupported.

video.stop(rt)