Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

recorder

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.

Functions

recorder.start(options: recorder.Options, callback: (self: unknown, event: recorder.Event, result: recorder.Result) => void): LuaMultiReturn<[boolean | undefined, string | undefined]>N

  • Since Defold 1.14.1

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.

const [ok, err] = recorder.start(
  {
    path: sys.get_save_file("my_game", "capture.mp4"),
    fps: 30,
    audio: false,
  },
  (self, event, result) => {
    if (event === recorder.EVENT_STOPPED) {
      print("Saved:", result.path);
    } else if (event === recorder.EVENT_ERROR) {
      print(result.error);
    }
  },
);
if (!ok) print(err);
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

Parameters

Returns

  • accepted: boolean | undefined — true if accepted, otherwise nil
  • error: string | undefined — reason the request was rejected

recorder.stop(): LuaMultiReturn<[boolean | undefined, string | undefined]>N

  • Since Defold 1.14.1

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.

Returns

  • accepted: boolean | undefined — true if accepted, otherwise nil
  • error: string | undefined — reason the request was rejected

Constants

recorder.EVENT_ERROR: number & { readonly __brand: "recorder.EVENT_ERROR" }N

  • Since Defold 1.14.1

Recording failed; result.error contains the reason.

recorder.EVENT_STARTED: number & { readonly __brand: "recorder.EVENT_STARTED" }N

  • Since Defold 1.14.1

Recording has started.

recorder.EVENT_STOPPED: number & { readonly __brand: "recorder.EVENT_STOPPED" }N

  • Since Defold 1.14.1

Recording has stopped and the MP4 is ready to read.

Types

type recorder.Event = typeof recorder.EVENT_STARTED | typeof recorder.EVENT_STOPPED | typeof recorder.EVENT_ERROR

interface recorder.Options { path: string; fps?: number; audio?: boolean; }

interface recorder.Result { path: string; width: number; height: number; fps: number; audio: boolean; error?: string; }

On this page