Recording APNGs

Every APNG in this tutorial set was produced the same way: a tiny subject app hosted under daslang-live, then a driver script running in a second shell that toggled visual aids, called record_start, narrated each interaction, performed the action, and called record_stop. This is the meta tutorial — the driver script is the artifact, and the embedded recording demonstrates itself.

Source files:

• examples/tutorial/recording.das — the subject: a one-slider one-button window. Tiny on purpose so every frame in the APNG corresponds to one specific driver call.

• tests/integration/record_recording.das — the driver. Walked through below.

The subject

options gen2

require imgui
require imgui_app
require glfw/glfw_boost
require opengl/opengl_boost
require live/glfw_live
require live/live_api
require live/live_commands
require live/live_vars
require live/opengl_live
require live_host
require imgui/imgui_live
require imgui/imgui_boost_runtime
require imgui/imgui_boost_v2
require imgui/imgui_widgets_builtin
require imgui/imgui_containers_builtin
require imgui/imgui_visual_aids

// =============================================================================
// TUTORIAL: recording — the meta tutorial.
//
// Every previous tutorial's APNG was produced by the same workflow:
//
//   shell 1: daslang-live  hosts a SUBJECT app          (this .das)
//   shell 2: daslang       runs a DRIVER script that:
//              - turns on imgui_mouse_trail + imgui_cursor_sprite
//              - calls record_start
//              - posts imgui_narrate before each interaction
//              - moves the cursor / clicks / drags / sets values
//              - calls record_stop
//
// The DRIVER is the artifact that teaches recording — the subject is
// just whatever app you want to record. This file is intentionally tiny
// (one slider, one button) so the recording recipe is obvious: every
// frame of the APNG corresponds to one specific driver call.
//
// The driver script for this tutorial is:
//   tests/integration/record_recording.das
//
// Read the driver alongside the walkthrough in the RST companion — the
// .das + driver + APNG triple is the tutorial.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/recording.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/recording.das
//
// DRIVE: see tests/integration/record_recording.das
// =============================================================================

[export]
def init() {
    live_create_window("dasImgui recording tutorial", 600, 380)
    live_imgui_init(live_window)
    var io & = unsafe(GetIO())
    io.FontGlobalScale = 1.5
}

[export]
def update() {
    if (!live_begin_frame()) return
    begin_frame()

    ImGui_ImplOpenGL3_NewFrame()
    ImGui_ImplGlfw_NewFrame()
    apply_synth_io_override()
    NewFrame()

    SetNextWindowPos(ImVec2(30.0f, 30.0f), ImGuiCond.FirstUseEver)
    SetNextWindowSize(ImVec2(520.0f, 280.0f), ImGuiCond.FirstUseEver)
    window(REC_WIN, (text = "subject", closable = false,
                     flags = ImGuiWindowFlags.None)) {
        text("Tiny subject — driver narrates what's happening.")
        slider_float(VOLUME, (text = "Volume"))
        if (button(SAVE_BTN, (text = "Save"))) {}
        text("SAVE_BTN.click_count = {SAVE_BTN.click_count}")
    }

    end_of_frame()
    Render()
    var w, h : int
    live_get_framebuffer_size(w, h)
    glViewport(0, 0, w, h)
    glClearColor(0.10f, 0.10f, 0.12f, 1.0f)
    glClear(GL_COLOR_BUFFER_BIT)
    ImGui_ImplOpenGL3_RenderDrawData(GetDrawData())

    live_end_frame()
}

[export]
def shutdown() {
    live_imgui_shutdown()
    live_destroy_window()
}

[export]
def main() {
    init()
    while (!exit_requested()) {
        update()
    }
    shutdown()
}

The subject is a normal dasImgui live-reload app — same shape as every other tutorial’s subject. The recorder doesn’t touch the subject at all; it operates entirely through the live-command HTTP surface.

The driver

options gen2
options indenting = 4
options no_unused_block_arguments = false
options no_unused_function_arguments = false

require imgui public
require imgui/imgui_playwright public
require daslib/json public
require daslib/json_boost public

//! Driver script: record ``recording.apng`` against an
//! **already-running** daslang-live. This driver is also the tutorial
//! topic — the RST walks through every line below.
//!
//! Workflow (two shells):
//!
//!     # window 1 — host with cwd = the asset dir so the APNG lands there:
//!     cd modules/dasImgui/doc/source/_static/tutorials
//!     ../../../../../../bin/Release/daslang-live.exe \
//!         ../../../../examples/tutorial/recording.das
//!
//!     # window 2 — fire the driver, exits when done:
//!     bin/Release/daslang.exe modules/dasImgui/tests/integration/record_recording.das

let BASE_URL = "http://127.0.0.1:9090"
let OUTPUT   = "recording.apng"

def widget_bbox(var snap : JsonValue?; ident : string) : float4 {
    //! Pull (x_min, y_min, x_max, y_max) out of the snapshot for one
    //! widget. The `?[...]` chain returns null on a missing path; the
    //! `?? 0.0f` coalesces missing axes to zero so callers don't have
    //! to null-check each component.
    var b = snap?["globals"]?[ident]?["bbox"]
    return float4(
        b?["x"] ?? 0.0f,
        b?["y"] ?? 0.0f,
        b?["z"] ?? 0.0f,
        b?["w"] ?? 0.0f
    )
}

def widget_center(var snap : JsonValue?; ident : string) : tuple<float; float> {
    //! Cursor-target helper — the driver moves the synth cursor to the
    //! center of the widget's bbox so the trail visibly travels to it.
    let b = widget_bbox(snap, ident)
    return ((b.x + b.z) * 0.5f, (b.y + b.w) * 0.5f)
}

[export]
def main {
    // ---- 1. Connect to the live host ----
    // ImguiApp bundles the HTTP transport + base URL into a value the
    // playwright helpers (post_command, move_to, click_at, ...) all
    // take as their first arg.
    let app = ImguiApp(
        base_url = BASE_URL,
        feature_path = "",
        transport <- live_api_transport(BASE_URL)
    )
    print("[record] connecting to {BASE_URL}\n")
    if (!wait_until_ready(app, 5.0f)) {
        panic("daslang-live not responding on {BASE_URL} — is it running with recording.das?")
    }

    // ---- 2. Resolve widget centers from a snapshot ----
    // wait_for_render polls imgui_snapshot until the named widget
    // appears (covers the cold-start gap where the subject is up but
    // first frame hasn't rendered). 10s timeout is generous.
    let T_VOLUME = "REC_WIN/VOLUME"
    let T_SAVE   = "REC_WIN/SAVE_BTN"
    var snap = wait_for_render(app, T_SAVE, 10.0f)
    if (snap == null) {
        panic("{T_SAVE} never rendered — wrong app running on {BASE_URL}?")
    }
    let p_volume = widget_center(snap, T_VOLUME)
    let p_save   = widget_center(snap, T_SAVE)

    // Volume drag: 15% to 80% along the slider's bbox width.
    let vol_bb = widget_bbox(snap, T_VOLUME)
    let vol_y  = (vol_bb.y + vol_bb.w) * 0.5f
    let vol_x0 = vol_bb.x + (vol_bb.z - vol_bb.x) * 0.15f
    let vol_x1 = vol_bb.x + (vol_bb.z - vol_bb.x) * 0.80f

    // ---- 3. Enable visual aids BEFORE record_start ----
    // mouse_trail draws the fading line behind the synth cursor;
    // cursor_sprite draws a visible pointer at io.MousePos so the
    // recording shows what's clicking what. Enable both first so the
    // very first frame of the APNG already has the cursor visible.
    post_command(app, "imgui_mouse_trail",   JV((enabled = true)))
    post_command(app, "imgui_cursor_sprite", JV((enabled = true)))

    // ---- 4. record_start: opens the APNG writer ----
    // file lands next to daslang-live's cwd (we set that to
    // doc/source/_static/tutorials/ in shell 1). max_seconds caps the
    // recording so a runaway driver doesn't churn disk forever.
    post_command(app, "record_start", JV((file = OUTPUT, fps = 30, max_seconds = 30)))

    //! Pacing rule (LOCKED): `frames` is the app's frame counter (60 fps
    //! under vsync), NOT the recorder's fps. For ~3s readable narrate:
    //!     frames = 180   →  3.0s visible
    //!     sleep  = 3500u →  narrate disappears with ~500ms gap before next
    //! Then ~1500ms result dwell after the action.

    // ---- 5. Narrate then act — repeat ----

    // Stage 1: slider drag
    post_command(app, "imgui_narrate", JV((
        text = "imgui_narrate posts a sticky-note over a target.",
        target = T_VOLUME,
        frames = 200
    )))
    move_to(app, p_volume)
    sleep(3500u)
    var slider_events : array<JsonValue?>
    slider_events |> drag_along(0, (vol_x0, vol_y), (vol_x1, vol_y), 1400)
    post_command(app, "imgui_mouse_play", JV((events = slider_events)))
    sleep(2500u)

    // Stage 2: click the button
    post_command(app, "imgui_narrate", JV((
        text = "imgui_mouse_play feeds a scripted timeline of events.",
        target = T_SAVE,
        frames = 200
    )))
    move_to(app, p_save)
    sleep(3500u)
    var save_events : array<JsonValue?>
    save_events |> click_at(0, p_save)
    post_command(app, "imgui_mouse_play", JV((events = save_events)))
    sleep(1500u)

    // ---- 6. record_stop: flushes the APNG writer, prints stats ----
    // The response carries (frames, duration_s, dropped, saved) — a quick
    // sanity check for the driver author.
    let stopped = post_command(app, "record_stop", null)
    let stop_dump = stopped != null ? write_json(stopped) : "<null>"
    print("[record] record_stop -> {stop_dump}\n")
    print("[record] APNG saved to {OUTPUT} (next to daslang-live's CWD)\n")

    // ---- 7. Disable visual aids ----
    // The host stays alive after the driver exits; clean up so the next
    // driver (or a developer poking at the live host manually) starts
    // from a clean state.
    post_command(app, "imgui_cursor_sprite", JV((enabled = false)))
    post_command(app, "imgui_mouse_trail",   JV((enabled = false)))
}

Anatomy of a driver

1. Connect to the live host. ImguiApp bundles the base URL + transport into a value every playwright helper takes as its first argument. wait_until_ready polls until the HTTP server answers, so the driver can be launched concurrently with daslang-live and recover from the cold-start gap.

2. Resolve widget centers. wait_for_render polls imgui_snapshot until the named widget shows up in the registry (covers the first-frame gap where the subject’s window exists but hasn’t rendered yet). The helper widget_bbox / widget_center extract the geometry from the snapshot JSON.

3. Enable visual aids — BEFORE ``record_start``.

   post_command(app, "imgui_mouse_trail",   JV((enabled = true)))
   post_command(app, "imgui_cursor_sprite", JV((enabled = true)))
   

   imgui_mouse_trail draws a fading line behind the synthetic cursor. imgui_cursor_sprite draws a visible pointer at io.MousePos. Without these, the recording shows widget state changing but no cursor — confusing for viewers.

4. ``record_start``. Opens an APNG writer at file (relative to daslang-live’s cwd, which is why every tutorial’s shell-1 command cd\s into the asset directory first). fps controls the time stamps written into the APNG frame headers — not how often frames are captured. max_seconds caps the recording length.

   The writer pulls from a PBO ring on the GL side (4 buffers by default) — glReadPixels returns immediately, the actual readback happens 3 frames later, the encoder runs on a worker thread. Frames drop only if the worker can’t keep up with the GL output rate, and even then dropping is graceful (the APNG just gets slightly choppier — never breaks).

5. Narrate, then act — repeat. The locked pacing rule:

   frames = 180   →  3.0 s of visible narrate
   sleep  = 3500u →  narrate disappears with ~500 ms gap
   sleep  = 1500u →  result-dwell after the action
   

   frames counts the APP’s frame counter (60 fps under vsync), NOT the recorder’s fps. So frames = 180 is 3 seconds of real time, regardless of whether the recorder is at 30 fps or 60 fps.

6. ``record_stop``. Flushes the APNG writer, joins the encoder thread, returns (saved, frames, duration_s, dropped, ok) so the driver can spot-check stats.

7. Disable visual aids. The host stays alive after the driver exits — clean up the cursor sprite + trail so the next driver (or a developer poking at the live host manually) starts from a clean slate.

The visual-aids stack

Four [live_command] toggles in imgui_visual_aids.das:

• imgui_mouse_trail — fading line behind io.MousePos. Args: enabled, fade (seconds), color (RGBA uint).

• imgui_cursor_sprite — visible pointer drawn at io.MousePos. Without it the cursor only exists in the OS layer, which screen recordings don’t capture.

• imgui_narrate — a sticky-note callout with optional connector line to a target widget. Auto-fits to avoid sibling overlap; frames controls visibility duration.

• imgui_highlight — a colored rectangle around a widget’s bbox for N frames. Useful for “look here” without text. imgui_auto_highlight flips a global flag that fires highlight on every accepted live command — a one-shot debug aid.

Two more for keyboard work:

• imgui_key_hud — bottom-center keycap overlay + modifier strip. Pops a keycap for every synth key event; lights modifier pills while held. Useful for input-heavy demos.

• imgui_focus_rect — a rectangle around io.active_widget so the viewer can tell which widget keystrokes will land in.

The driver workflow in shell

The two-shell pattern every tutorial uses:

# shell 1 — host with cwd = the asset dir so the APNG lands there
cd modules/dasImgui/doc/source/_static/tutorials
../../../../../../bin/Release/daslang-live.exe \
    ../../../../examples/tutorial/recording.das

# shell 2 — fire the driver, exits when done
bin/Release/daslang.exe modules/dasImgui/tests/integration/record_recording.das

The host stays alive after the driver exits; if the recording was bad, re-run shell 2 — no need to restart daslang-live. The driver script nukes the previous file (rm -f <name>.apng) at the top, or record_start returns {"error":"already recording"} if a prior session leaked.

Stop conditions

record_stop is the clean exit. Three other ways the writer finalizes:

• max_seconds expires — same APNG, frame count + duration match the cap.

• stbi_apng_frame returns an error (rare; usually disk full or permission denied) — writer auto-stops, returns the partial APNG.

• daslang-live shuts down — the [on_app_exit] hook on the recorder finalizes any in-flight ring before tearing down GL state.

In practice record_stop is the only exit you’ll see; the others are safety nets.

Replay stability

The same driver run against the same subject produces APNGs that look the same to a viewer — but they’re not byte-identical. ImGui’s frame times jitter, vsync alignment shifts, the PBO ring may stall once or twice on encoder backpressure. dropped in the response is the useful metric: anything under capture_pbo_count + a few is fine. Higher means the encoder couldn’t keep up — try lowering the subject’s render rate, simplifying the subject, or raising capture_pbo_count.

Standalone vs live

The whole recording surface — visual aids, record_start / record_stop, the playwright helpers — runs only under daslang-live. Standalone daslang.exe runs the subject, but the HTTP-bound live commands aren’t registered. The driver script itself is a normal daslang.exe script — it just talks HTTP to a host running on another process.

Driving from outside

The same JSON commands the driver issues are reachable from curl:

curl -X POST -d '{"name":"imgui_mouse_trail","args":{"enabled":true}}'      localhost:9090/command
curl -X POST -d '{"name":"imgui_cursor_sprite","args":{"enabled":true}}'    localhost:9090/command
curl -X POST -d '{"name":"record_start","args":{"file":"manual.apng","fps":30,"max_seconds":15}}' \
     localhost:9090/command

# do whatever interactions interactively in the live window ...

curl -X POST -d '{"name":"record_stop"}' localhost:9090/command

Use this for ad-hoc captures when the scripted driver would be overkill — bug repros, “show me what this looks like” pings.

The end of the curriculum

The 12 tutorials in this set walk the dasImgui surface end-to-end: basics, widgets, layout, docking, style, identity, state, containers, live reload, the JSON-driven view, the visual aids tour, and this recording recipe. Beyond the curriculum, every examples/features/ demo is a richer reference for one specific surface — those are the go-to once the tutorials are familiar.

See also

Subject source: examples/tutorial/recording.das

Driver source: tests/integration/record_recording.das

Recorder implementation: modules/dasOpenGL/opengl/opengl_live.das (record_start / record_stop plus the PBO ring).

Visual aids: modules/dasImgui/widgets/imgui_visual_aids.das.

Playwright helpers: modules/dasImgui/widgets/imgui_playwright.das.

Previous tutorial: Visual aids tour

Curriculum top: dasImgui tutorials