Morgerion/defold-mpeg/mpeg.gui_video
Plays an MPEG1 or AV1 video on a GUI box node, optionally with its sound.
It is built on the mpeg native extension. Call init from the GUI script's
init, update from its update and final from its final, passing the
script's self: the module keeps each player on it. Map
/mpeg/video_yuv.material in the GUI scene as video_yuv to convert frames on the
GPU instead of the CPU.
- GitHub: Morgerion/defold-mpeg — pinned to
1.2.0- This repo publishes no stable release. Pick a tag from Morgerion/defold-mpeg tags and add its Source code (zip) URL — for the pinned tag,
https://github.com/Morgerion/defold-mpeg/archive/refs/tags/1.2.0.zip— togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as gui_video from "mpeg.gui_video"
- This repo publishes no stable release. Pick a tag from Morgerion/defold-mpeg tags and add its Source code (zip) URL — for the pinned tag,
Functions
init(self: object, options:Options):Playerupdate(self: object, dt: number, field?: string)final(self: object, field?: string)is_finished(self: object, field?: string): booleaninit_many(self: object, options_list:Options[]):Player[]update_all(self: object, dt: number, fields?: string[])final_all(self: object, fields?: string[])are_finished(self: object, fields?: string[]): boolean
init(self: object, options: Options): Player
Start a video player on self, replacing the one in the same field.
It shows the first frame at once and, with sound, decodes the whole audio track
and starts it. Throws when the video, its material or its node cannot be used.
Parameters
self:object— The GUI script'sself, which holds the player.options:Options— The node, the video and how to play it.
Returns
Player
update(self: object, dt: number, field?: string)
Advance one video player.
It moves by dt scaled by its playback speed or, while its sound plays, to the
sound's position. A non-looping video that ends with stop_on_last_frame keeps its
last frame and is finished.
Parameters
self:object— The GUI script'sself.dt:number— The game frame's time step, in seconds.field?:string— The player'sfield. Defaults to the single-video field.
final(self: object, field?: string)
Stop one video player and release what it holds.
It stops the sound, closes the decoder and releases the runtime texture and atlas.
Call it from final, or reopening the GUI leaks them.
Parameters
self:object— The GUI script'sself.field?:string— The player'sfield. Defaults to the single-video field.
is_finished(self: object, field?: string): boolean
Whether one video has stopped on its last frame.
A looping video, one with stop_on_last_frame off, or a field with no player
never has.
Parameters
self:object— The GUI script'sself.field?:string— The player'sfield. Defaults to the single-video field.
Returns
boolean
init_many(self: object, options_list: Options[]): Player[]
Start several video players at once. When one fails, those already started are finalized before the error is rethrown.
Parameters
self:object— The GUI script'sself.options_list:Options[]— One options table per video, each with its ownfield.
Returns
Player[]
update_all(self: object, dt: number, fields?: string[])
Advance the given video players, or every one self holds.
Parameters
self:object— The GUI script'sself.dt:number— The game frame's time step, in seconds.fields?:string[]— The players' fields. Defaults to every player, in start order.
final_all(self: object, fields?: string[])
Finalize the given video players, or every one self holds, in reverse order.
Parameters
self:object— The GUI script'sself.fields?:string[]— The players' fields. Defaults to every player.
are_finished(self: object, fields?: string[]): boolean
Whether every given video has stopped on its last frame, or every one self holds.
false when there is none.
Parameters
self:object— The GUI script'sself.fields?:string[]— The players' fields. Defaults to every player.
Returns
boolean
Types
type Player = Opaque<"gui_video_player">
type Options = ResourceOptions | DataOptions
ResourceOptions
interface ResourceOptions extends CommonOptions
ResourceOptions.video_resource: string
Path of the video in custom_resources.
ResourceOptions.video_data?: string | Opaque<"buffer">
The video's data; when given, it is played instead of loading video_resource.
CommonOptions
CommonOptions.node: string | Hash
Id of the box node that shows the video.
CommonOptions.field?: string
Field on self that holds this player, for a GUI with several videos.
Defaults to one shared field, so a single video needs none.
CommonOptions.gui_url?: Url
URL of the GUI component the runtime atlas is added to. Defaults to msg.url().
CommonOptions.sound?: string | Hash | Url
URL of a sound component to play the audio track through. Without it the video plays silently.
CommonOptions.audio_resource?: string
A separate MPEG audio file to play instead of the video's own track.
It is a custom_resources path. An AV1 video needs it for sound.
CommonOptions.audio_data?: string | Opaque<"buffer">
A separate MPEG audio file's data, used instead of audio_resource.
CommonOptions.sound_resource?: string | Hash
The sound resource the sound component plays.
Its data is replaced with the decoded track. Defaults to
/mpeg/video_sound.wavc; two videos with sound at once each need their own copy.
CommonOptions.gain?: number
Gain of the sound. Defaults to 1.
CommonOptions.yuv?: boolean
Whether frames are converted to RGB by the YUV material.
true requires the material and throws when it is not mapped; false always
converts on the CPU. Defaults to using the material when it is mapped.
CommonOptions.yuv_material?: string | Hash
Name of the YUV material in the GUI scene. Defaults to video_yuv.
CommonOptions.loop?: boolean
Loop the video and its sound. Defaults to true.
CommonOptions.stop_on_last_frame?: boolean
Stop a non-looping video on its last frame. Defaults to true.
CommonOptions.blend_frames?: boolean
Crossfade between neighbouring frames, using a clone of the node. Defaults to false.
CommonOptions.playback_speed?: number
Speed multiplier, applied to the sound as well. Defaults to 1.
CommonOptions.playback_fps?: number
Playback frame rate; when set, it overrides playback_speed.
CommonOptions.fallback_fps?: number
Frame rate to use when the file stores none. Defaults to 24.
CommonOptions.max_frames_per_update?: number
Most video frames decoded in one game frame. Defaults to 2.
CommonOptions.max_lag?: number
With sound, how far in seconds the picture may fall behind it.
Past that it jumps to the nearest key frame. Defaults to 0.3.
CommonOptions.enable_node?: boolean
Enable the node once the video is ready. Defaults to true.
CommonOptions.runtime_name?: string
Base name of the runtime texture and atlas paths. Defaults to gui_video.
CommonOptions.texture_key?: string
Key the runtime atlas is added to the GUI under. Defaults to video.
CommonOptions.animation_id?: string
Id of the runtime atlas animation the node plays. Defaults to white.
DataOptions
interface DataOptions extends CommonOptions
DataOptions.video_data: string | Opaque<"buffer">
The video's data.
DataOptions.video_resource?: string
Name of the video in error messages.