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.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- bevySkill
- branch-regressionSkill
- elodin-alephSkill
- elodin-craneliftSkill
- elodin-dbSkill
- elodin-devSkill
- elodin-editor-devSkill
- elodin-monte-carloSkill
- elodin-nixSkill
- elodin-simulationSkill
- elodin-tracySkill
- gltf-asset-optimizationSkill
- kdl-to-python-schematicSkill
- nox-py-devSkill
- qa-test-planSkill
- rustSkill
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
- Very specific: line 12
Run commands from the repository root inside nix develop or nix develop .#run.
- Distinctive: line 28
Check that the host PipeWire service and portable software encoder are available:
- Very specific: line 54
Use --port PORT to isolate the capture from another editor/simulation.
- Very specific: line 62
Run it inside nix develop or nix develop .#run.
- Distinctive: line 77
Use the lowest practical resolution so the editor and encoder consume fewer GPU resources.
- Very specific: line 90
If startup fails on a non-NixOS host because the dynamic linker has not noticed newly installed host driver libraries, run sudo ldconfig …
- Distinctive: line 102
Use an absolute output path.
- Very specific: line 156
Keep the explicit BGRx filter immediately after pipewiresrc and convert to a format accepted by the selected encoder.
- Distinctive: line 160
Verify hardware-engine activity with an appropriate vendor tool when practical.
- Distinctive: line 162
Use the working hardware path for the full capture.
- Distinctive: line 165
Prefer validated hardware encoding, but never skip output validation or retain a broken hardware path merely to avoid the software fallback.
- Very specific: line 168
Stop recording with Ctrl-C.
- Distinctive: line 186
After every capture, check the stream metadata and decode a representative frame.
- Distinctive: line 195
A hardware encoder is missing or fails to initialize: use the documented x264 pipeline.
- Very specific: line 199
No
gamescopesource: make sure Gamescope is already running. - Very specific: line 203
PipeWire connection refused: check echo "$XDG_RUNTIME_DIR" and pw-cli info 0.
- Very specific: line 205
All-black recording: ensure the video/x-raw,format=BGRx filter appears immediately after pipewiresrc.
- Distinctive: line 208
Partially loaded recording: wait longer before starting GStreamer, or use a lighter example and lower resolution.
- Very specific: line 210
Stale editor process or DB/assets port conflict: stop the previous Gamescope child or choose another free DB/assets pair with --port.
≈ “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.
Files
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
Build the release editor:
cargo build --release -p elodinRunning 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).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/nullOn 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.pyUse --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.pyRun 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.pyGamescope 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.pngUse 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.mp4This 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:
- Confirm that the candidate encoder is registered and can initialize.
- Keep the explicit BGRx filter immediately after
pipewiresrcand convert to a format accepted by the selected encoder. - 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.
- Verify hardware-engine activity with an appropriate vendor tool when practical.
- 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.mp4Verify 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
pipewiresrcis missing: enter a freshnix develop; the shell adds the PipeWire GStreamer plugin toGST_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 withrm -f ~/.cache/gstreamer-1.0/registry.*.binbefore probing again. - No
gamescopesource: make sure Gamescope is already running. Inspect video node names and media names withpw-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"andpw-cli info 0; run both terminals as the same non-root user. - All-black recording: ensure the
video/x-raw,format=BGRxfilter appears immediately afterpipewiresrc. 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 usingELODIN_GPU=nvk.
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
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.

