Skip to Content
defold-typescript libraries
Morgeriondefold-mpeg

Morgerion/defold-mpeg

Functions to play MPEG1 videos

  • GitHub: Morgerion/defold-mpeg — pinned to 1.2.0 (released while Defold 1.14.0 was current)
    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 mpeg from "mpeg"
  • Asset Portal: defold-mpeg

Functions

mpeg.open(video: buffer | string, options: table): LuaMultiReturn<[number, string]>

Open a video for decoding. MPEG1 (.mpg) or AV1 in an IVF file (.ivf), recognized by its header.

Parameters

  • video: buffer | string — The video data as a buffer or string. Ownership of the buffer is not transferred.
  • options: table — Optional video settings. loop loops the video. format is "rgb" (default, frames converted to RGB on the CPU) or "yuv" (packed YUV planes for the video_yuv shader). decode_ahead (AV1, default true) decodes on a worker thread into a queue. threads (AV1) sets the decoder threads, by default 1 up to 1080p, 2 up to 1440p and 4 above. audio (MPEG1) makes this decoder decode the audio track too, but the samples are not played - use decode_audio() and a sound component for sound.

Returns

  • handle: number — Returns video handle. Use in subsequent calls.
  • err: string — Error message if video failed to open.

mpeg.close(handle: number)

Close an opened video. This will release an memory allocated by the videoplayer.

Parameters

  • handle: number — The video handle to close.

mpeg.decode(handle: number, seconds: number): boolean

Advance the internal timer by seconds and decode video/audio up to this time.

Parameters

  • handle: number — The video handle to decode.
  • seconds: number — Number of seconds to advance.

Returns

  • has_new_frame: boolean — Returns true if decode produced at least one new video frame.

mpeg.write(handle: number, data: string): LuaMultiReturn<[number, string]>

Write data to the internal stream buffer of a video started with stream(). Use the streaming_buffer_bytes_remaining and streaming_buffer_capacity to determine how much data to write to the buffer.

Parameters

  • handle: number — The video handle to write to.
  • data: string — Bytes with stream data.

Returns

  • bytes_written: number — The number of written bytes or nil if writing failed.
  • error: string — Error message if writing failed for some reason.

mpeg.seek(handle: number, time: number, seek_exact: boolean)

Seek to the specified time. Will seek to the last intra frame just before the desired time.

Parameters

  • handle: number — The video handle to seek on.
  • time: number — Time to seek to.
  • seek_exact: boolean — If value is true the function will seek to the exact time, otherwise it will seek to the last intra frame just before the desired time. Exact seeking can be slow, because all frames up to the seeked one have to be decoded on top of the previous intra frame. Defaults to false.

mpeg.rewind(handle: number)

Rewind video to the beginning.

Parameters

  • handle: number — The video handle to rewind.

mpeg.get_frame(handle: number): buffer

Get the video frame buffer. The video frame buffer will be updated when decode() is called and enough data has been decoded to produce a frame.

Parameters

  • handle: number — The video handle to get frame buffer for.

Returns

  • frame: buffer — The decoded video frame buffer or nil if no video frame buffer is available. The ownership of the buffer is not transferred to the caller.

mpeg.get_frame_serial(handle: number): number

Get a monotonically increasing serial number for decoded video frames.

Parameters

  • handle: number — The video handle to query.

Returns

  • serial: number — The serial number of the latest decoded frame.

mpeg.get_time(handle: number): number

Get the current playback time of a video. Same as get_info().time, without creating a table.

Parameters

  • handle: number — The video handle to query.

Returns

  • time: number — Current playback time in seconds.

mpeg.decode_audio(video: buffer | string): LuaMultiReturn<[string, table | string]>

Decode the whole MPEG audio track of a video, or of an audio-only MPEG file, into a 16-bit stereo PCM WAV file in memory, ready for resource.set_sound() or resource.create_sound_data(). Uses its own decoder, so an opened video handle is not affected.

Parameters

  • video: buffer | string — The video data as a buffer or string.

Returns

  • wav: string — The WAV file, or nil if the video has no audio track.
  • info: table | string — Table with samplerate, channels, duration (exact, in seconds) and decode_ms, or an error message if wav is nil.

mpeg.get_info(handle: number): table

Get information about an opened video.

Parameters

  • handle: number — The video to get info for.

Returns

  • info: table — Video information
    • codec: string — "mpeg1" or "av1".
    • width: number — Video width.
    • height: number — Video height.
    • bytes_per_pixel: number — The number of bytes per pixel.
    • framerate: number — The frame rate (frames per second) of the video stream.
    • samplerate: number — The sample rate (samples per second) of the audio stream.
    • time: number — Current playback time in seconds.
    • duration: number — Estimated duration in seconds - the span between the first and the last timestamp in the file. Accurate on long videos, can be short by up to a second on short clips.
    • convert_ms: number — Time the last frame took to convert to RGB or copy as YUV planes, in milliseconds.
    • format: string — "rgb" or "yuv", as passed to open().
    • texture_width: number — Width of the frame buffer. For "yuv" it is larger than the video.
    • texture_height: number — Height of the frame buffer. For "yuv" it is larger than the video.
    • matrix: string — "bt601" or "bt709": the YUV to RGB matrix of the video. For AV1 known after the first frame.
    • full_range: boolean — Whether the video uses full range YUV instead of limited (studio) range.
    • threads: number — AV1 only - number of decoder threads.
    • queue_frames: number — AV1 only - size of the decode-ahead queue, 0 when decoding synchronously.
    • decode_ms: number — AV1 only - how long the last frame shown took to decode, in milliseconds.
    • is_looping: boolean — If the video is looping or not.
    • is_streaming: boolean — If the video is opened in streaming mode.
    • eos: boolean — If the video has reached the end of stream.
    • streaming_buffer_bytes_remaining: number — The number of unread bytes remaining in the stream buffer when streaming.
    • streaming_buffer_capacity: number — The capacity of the stream buffer in bytes.

On this page