Skip to Content
defold-typescript libraries
Morgeriondefold-mpeg

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
    1. 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 — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as gui_video from "mpeg.gui_video"

Functions

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's self, 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's self.
  • dt: number — The game frame's time step, in seconds.
  • field?: string — The player's field. 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's self.
  • field?: string — The player's field. 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's self.
  • field?: string — The player's field. 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's self.
  • options_list: Options[] — One options table per video, each with its own field.

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's self.
  • 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's self.
  • 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's self.
  • 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.

On this page

Functionsinit(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[]): booleanTypestype Player = Opaque<"gui_video_player">type Options = ResourceOptions | DataOptionsResourceOptionsinterface ResourceOptions extends CommonOptionsResourceOptions.video_resource: stringResourceOptions.video_data?: string | Opaque<"buffer">CommonOptionsCommonOptions.node: string | HashCommonOptions.field?: stringCommonOptions.gui_url?: UrlCommonOptions.sound?: string | Hash | UrlCommonOptions.audio_resource?: stringCommonOptions.audio_data?: string | Opaque<"buffer">CommonOptions.sound_resource?: string | HashCommonOptions.gain?: numberCommonOptions.yuv?: booleanCommonOptions.yuv_material?: string | HashCommonOptions.loop?: booleanCommonOptions.stop_on_last_frame?: booleanCommonOptions.blend_frames?: booleanCommonOptions.playback_speed?: numberCommonOptions.playback_fps?: numberCommonOptions.fallback_fps?: numberCommonOptions.max_frames_per_update?: numberCommonOptions.max_lag?: numberCommonOptions.enable_node?: booleanCommonOptions.runtime_name?: stringCommonOptions.texture_key?: stringCommonOptions.animation_id?: stringDataOptionsinterface DataOptions extends CommonOptionsDataOptions.video_data: string | Opaque<"buffer">DataOptions.video_resource?: string