Elodin Headless Capture

Headless Elodin capture

This workflow is Linux-only. Gamescope's headless compositor, its PipeWire video source, and the host GPU-driver integration used here are Linux facilities. Keep the related Nix dependencies guarded by stdenv.isLinux.

Run commands from the repository root inside nix develop or nix develop .#run. Do not use sudo: Gamescope and GStreamer must use the same user's PipeWire socket under XDG_RUNTIME_DIR.

Prerequisites

1. Build the release editor:

   cargo build --release -p elodin

   Running a Python example also requires the project virtual environment. If it is not already installed, run just install (venv is auto-active in the nix shell).

2. Check that the host PipeWire service and portable software encoder are available:

   pw-cli info 0
   gst-inspect-1.0 pipewiresrc >/dev/null
   gst-inspect-1.0 x264enc >/dev/null

   On a systemd desktop, start a missing PipeWire service with systemctl --user start pipewire. The host must expose its GPU devices and graphics drivers for accelerated editor rendering; Nix supplies the user-space tools, not the kernel driver.

Automated capture (preferred)

The repository provides scripts/elodin_capture.sh, which performs the PipeWire preflight, selects a vendor-compatible graphics path, starts Gamescope with Nix's Xwayland, validates a hardware encoder when available, falls back to x264, records, decodes a frame, rejects blank output, and cleans up all child processes:

./scripts/elodin_capture.sh --duration 10 --output /tmp/elodin.mp4 examples/cube-sat/main.py

Use --port PORT to isolate the capture from another editor/simulation. The simulation DB uses PORT and its asset server uses PORT + 1, so both must be available:

./scripts/elodin_capture.sh --port 32400 --output /tmp/elodin.mp4 examples/cube-sat/main.py

Run it inside nix develop or nix develop .#run. The default readiness check waits for the simulation database server and then allows a two-second warmup. Use --ready-regex or --warmup for examples with unusual startup behavior. Use --encoder x264 to force the portable fallback, or --encoder vaapi / --encoder nvenc when testing a specific hardware path. Set ELODIN_GPU=mesa or ELODIN_GPU=nvidia before entering the development shell to override automatic GPU selection; ELODIN_GPU=nvk instead drives an NVIDIA GPU through Mesa's NVK driver and needs no proprietary driver, which is the working path on a hybrid Intel + NVIDIA host. An explicitly set GBM_BACKENDS_PATH is always preserved.

The manual workflow below remains useful for debugging capture infrastructure.

Start the editor manually

Use the lowest practical resolution so the editor and encoder consume fewer GPU resources. In terminal 1:

gamescope --backend headless \
  -w 1280 -h 720 -W 1280 -H 720 -r 30 \
  -- ./target/release/elodin editor examples/three-body/main.py

Gamescope starts a nested Xwayland display for the editor and publishes its composited output with the PipeWire media name gamescope. Wait for the editor to finish loading before capturing.

If startup fails on a non-NixOS host because the dynamic linker has not noticed newly installed host driver libraries, run sudo ldconfig once outside the capture workflow and retry as the normal user.

Screenshot

While Gamescope is running, use terminal 2:

gamescopectl screenshot /tmp/elodin.png

Use an absolute output path. Read the image afterward to verify that the scene and editor chrome rendered correctly.

For a one-shot editor screenshot where a composited video is not needed, prefer the editor's ELODIN_SCREENSHOT mechanism documented in the elodin-editor-dev skill.

Record video

In terminal 2, start this after the editor has loaded. Resolve the newest Gamescope node's PipeWire object serial instead of hard-coding its name. Current PipeWire can publish multiple nodes with the same .gamescope-wrapped name, so the serial uniquely identifies the live compositor.

GAMESCOPE_TARGET="$(pw-dump | jq -r '
  [
    .[]
    | select(.type == "PipeWire:Interface:Node")
    | select(.info.props["media.name"] == "gamescope")
    | select(.info.props["object.serial"] != null)
    | {id: .id, serial: (.info.props["object.serial"] | tostring)}
  ]
  | sort_by(.id)
  | last
  | .serial // empty
')"
test -n "$GAMESCOPE_TARGET"

gst-launch-1.0 -e \
  pipewiresrc target-object="$GAMESCOPE_TARGET" do-timestamp=true \
  ! video/x-raw,format=BGRx \
  ! queue \
  ! videoconvert \
  ! video/x-raw,format=I420 \
  ! x264enc bitrate=8000 speed-preset=veryfast \
  ! video/x-h264,profile=main \
  ! h264parse \
  ! mp4mux faststart=true \
  ! filesink location=/tmp/elodin.mp4

This software-encoding command is the reliable baseline and fallback across NVIDIA, AMD, and Intel systems. The first caps filter is required: forcing Gamescope to provide BGRx avoids capture paths that can produce an all-black video. videoconvert then converts the valid BGRx frames to the I420 input used by x264.

The x264 command above is the known-good fallback, but an agent should use a hardware encoder when one is detected and proven to work. Inspect available GStreamer elements for NVENC on NVIDIA or VA-API on AMD/Intel, then validate the candidate before using it for the requested capture:

1. Confirm that the candidate encoder is registered and can initialize.
2. Keep the explicit BGRx filter immediately after pipewiresrc and convert to a format accepted by the selected encoder.
3. Make a short test recording, decode a frame from it, and verify that it is nonblank. Plugin discovery and a valid MP4 alone are not sufficient.
4. Verify hardware-engine activity with an appropriate vendor tool when practical.
5. Use the working hardware path for the full capture. Fall back to the x264 command only if hardware encoding is unavailable or fails validation.

Prefer validated hardware encoding, but never skip output validation or retain a broken hardware path merely to avoid the software fallback.

Stop recording with Ctrl-C. The -e option sends end-of-stream so mp4mux can finalize the MP4. Do not kill GStreamer with SIGKILL, or the output may be unplayable.

Confirm the result:

ffprobe -v error \
  -show_entries stream=codec_name,width,height,avg_frame_rate \
  -of default=noprint_wrappers=1 /tmp/elodin.mp4