Video recording

Record the game window to an MP4 file. One recording may run at a time, shared with the engine's HTTP recording service.

Recording is supported by desktop debug engines. The module is omitted from release, headless, mobile and web builds, and when recording is excluded through an app manifest. Unsupported desktop operating systems or capture environments return an error from [ref:recorder.start]. Application audio support depends on the platform; audio is disabled by default.

Version: alpha (1.14.1)

RECORDS
recorder.options	recording options
recorder.result	recording event result

ENUMS
recorder.EVENT	recording events

FUNCTIONS
recorder.start()	start recording
recorder.stop()	stop recording

Records

recorder.options

recording options

FIELDS

`path`	`string`	Writable MP4 output path, for example from sys.get_save_file. Uses the host path encoding (Windows ANSI code page; UTF-8 elsewhere). The parent directory must exist.
`[fps]`	`integer`	Capture rate from 1 to 60; defaults to 30.
`[audio]`	`boolean`	Record application audio; defaults to false.

recorder.result

recording event result

FIELDS

`path`	`string`	Output file path, preserving the path supplied to recorder.start.
`width`	`integer`	Recorded video width in pixels.
`height`	`integer`	Recorded video height in pixels.
`fps`	`integer`	Capture rate.
`audio`	`boolean`	Whether application audio is included.
`[error]`	`string`	Failure reason, present for recorder.EVENT_ERROR.

Enums

recorder.EVENT

recorder.EVENT: integer

recording events

VALUES

`recorder.EVENT_STARTED`	Recording has started.
`recorder.EVENT_STOPPED`	Recording has stopped and the MP4 is ready to read.
`recorder.EVENT_ERROR`	Recording failed; result.error contains the reason.

Functions

recorder.start()

recorder.start(options:recorder.options, callback:fun(self:script_instance, event:recorder.EVENT, result:recorder.result))→(accepted:boolean|nil, error:string|nil)

Starts an asynchronous recording of the game window at its native pixel size. The caller owns the output file, which remains on disk after engine shutdown. An existing file at the specified path may be overwritten. A successful return only means the request was accepted. The callback receives recorder.EVENT_STARTED when capture starts, followed by recorder.EVENT_STOPPED or recorder.EVENT_ERROR. Startup failure produces only EVENT_ERROR. Callbacks run during engine update, never inside start/stop. Window resizing stops and finalizes the recording. Deleting the calling script discards its callback but does not stop recording. Engine shutdown finalizes recording without invoking callbacks.

PARAMETERS

`options`	`recorder.options`	recording options
`callback`	`function( self:script_instance, event:recorder.EVENT, result:recorder.result)`	recording event callback

RETURNS

`accepted`	`boolean` `nil`	true if accepted, otherwise nil
`error`	`string` `nil`	reason the request was rejected

EXAMPLES

local ok, err = recorder.start({
    path = sys.get_save_file("my_game", "capture.mp4"),
    fps = 30,
    audio = false,
}, function(self, event, result)
    if event == recorder.EVENT_STOPPED then
        print("Saved:", result.path)
    elseif event == recorder.EVENT_ERROR then
        print(result.error)
    end
end)
if not ok then print(err) end

recorder.stop()

recorder.stop()→(accepted:boolean|nil, error:string|nil)

Requests finalization of the current recording, including one started through HTTP. Wait for recorder.EVENT_STARTED before calling stop for a Lua recording. The original start callback receives recorder.EVENT_STOPPED only after the MP4 is finalized and ready to read, or recorder.EVENT_ERROR on failure. Returns an error if no recording is active or an operation is pending.

PARAMETERS

None

RETURNS

`accepted`	`boolean` `nil`	true if accepted, otherwise nil
`error`	`string` `nil`	reason the request was rejected