agentleFS
elodin-syselodin-sys/elodin/.cursor/skills/elodin-headless-capture/SKILL.md

elodin-headless-capture

Skill553 starsChanged 5 months agoApache-2.0View on GitHub

Run the Elodin Editor without a physical display in Gamescope, take screenshots, and record video through PipeWire and GStreamer. Use for visual testing or capture on a headless Linux GPU host.

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. About 0 are common, 9 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run commands from the repository root inside nix develop or nix develop .#run.

    line 12
  2. Distinctive:

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

    line 28
  3. Very specific:

    Use --port PORT to isolate the capture from another editor/simulation.

    line 54
  4. Very specific:

    Run it inside nix develop or nix develop .#run.

    line 62
  5. Distinctive:

    Use the lowest practical resolution so the editor and encoder consume fewer GPU resources.

    line 77
  6. Very specific:

    If startup fails on a non-NixOS host because the dynamic linker has not noticed newly installed host driver libraries, run sudo ldconfig …

    line 90
  7. Distinctive:

    Use an absolute output path.

    line 102
  8. Very specific:

    Keep the explicit BGRx filter immediately after pipewiresrc and convert to a format accepted by the selected encoder.

    line 156
  9. Distinctive:

    Verify hardware-engine activity with an appropriate vendor tool when practical.

    line 160
  10. Distinctive:

    Use the working hardware path for the full capture.

    line 162
  11. Distinctive:

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

    line 165
  12. Very specific:

    Stop recording with Ctrl-C.

    line 168
  13. Distinctive:

    After every capture, check the stream metadata and decode a representative frame.

    line 186
  14. Distinctive:

    A hardware encoder is missing or fails to initialize: use the documented x264 pipeline.

    line 195
  15. Very specific:

    No gamescope source: make sure Gamescope is already running.

    line 199
  16. Very specific:

    PipeWire connection refused: check echo "$XDG_RUNTIME_DIR" and pw-cli info 0.

    line 203
  17. Very specific:

    All-black recording: ensure the video/x-raw,format=BGRx filter appears immediately after pipewiresrc.

    line 205
  18. Distinctive:

    Partially loaded recording: wait longer before starting GStreamer, or use a lighter example and lower resolution.

    line 208
  19. Very specific:

    Stale editor process or DB/assets port conflict: stop the previous Gamescope child or choose another free DB/assets pair with --port.

    line 210

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Verify rendering and output

Gamescope and Elodin should create graphics contexts and increase GPU utilization while the editor is rendering. Use the appropriate vendor tool if available. Software x264 encoding is expected to use the CPU.

After every capture, check the stream metadata and decode a representative frame. Confirm visually, or with image statistics, that the decoded frame is not all black. This catches a valid-looking MP4 produced from invalid capture buffers.

Troubleshooting

  • pipewiresrc is missing: enter a fresh nix develop; the shell adds the PipeWire GStreamer plugin to GST_PLUGIN_PATH.
  • A hardware encoder is missing or fails to initialize: use the documented x264 pipeline. If hardware encoding is important, verify the host driver and device permissions, re-enter nix develop, and clear a stale plugin cache with rm -f ~/.cache/gstreamer-1.0/registry.*.bin before probing again.
  • No gamescope source: make sure Gamescope is already running. Inspect video node names and media names with pw-dump | jq '.[] | select(.type == "PipeWire:Interface:Node") | .info.props | select(."media.class" == "Video/Source") | {node_name: ."node.name", media_name: ."media.name"}'.
  • PipeWire connection refused: check echo "$XDG_RUNTIME_DIR" and pw-cli info 0; run both terminals as the same non-root user.
  • All-black recording: ensure the video/x-raw,format=BGRx filter appears immediately after pipewiresrc. Do not let a downstream encoder negotiate the source format directly.
  • Partially loaded recording: wait longer before starting GStreamer, or use a lighter example and lower resolution.
  • Stale editor process or DB/assets port conflict: stop the previous Gamescope child or choose another free DB/assets pair with --port.
  • Gamescope dies as soon as recording starts, and the script then reports that no encoder works: on an Intel iGPU, Gamescope can segfault inside Mesa's ANV driver while allocating the PipeWire capture buffers. Confirm it with gdb, then capture through the discrete GPU using ELODIN_GPU=nvk.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.