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)- 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 mpeg from "mpeg"
- 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,
- Asset Portal: defold-mpeg
Functions
mpeg.open(video: buffer | string, options: table): LuaMultiReturn<[number, string]>mpeg.close(handle: number)mpeg.decode(handle: number, seconds: number): booleanmpeg.write(handle: number, data: string): LuaMultiReturn<[number, string]>mpeg.seek(handle: number, time: number, seek_exact: boolean)mpeg.rewind(handle: number)mpeg.get_frame(handle: number): buffermpeg.get_frame_serial(handle: number): numbermpeg.get_time(handle: number): numbermpeg.decode_audio(video: buffer | string): LuaMultiReturn<[string, table | string]>mpeg.get_info(handle: number): table
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.looploops the video.formatis "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 withsamplerate,channels,duration(exact, in seconds) anddecode_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 informationcodec: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.