davinci-resolve-mcp 2.69.3 → 2.70.0

package/docs/reference/headless-cli.md

@@ -0,0 +1,751 @@
+# Running DaVinci Resolve headless
+
+Blackmagic's scripting README gives headless mode two sentences: launch with
+`-nogui` and "the various scripting APIs will continue to work as expected."
+That is close enough to true to be misleading, because it says nothing about
+what an agent should *do* differently — and this repository's own working notes
+had drifted to the opposite belief, that Gallery and still-export surfaces were
+headless-only failures.
+
+This page replaces both with measurements. Everything under "Verified" was
+observed on this machine against DaVinci Resolve Studio 19.1.3.7 on macOS;
+everything under "Present but not exercised" was read out of the application
+binary and has not been run. The distinction is kept because an unverified flag
+that an agent tries anyway is worse than one it never heard of.
+
+The differential itself lives in
+[headless-capability-matrix.md](headless-capability-matrix.md), regenerated by
+`scripts/headless_differential.py`.
+
+## The headline, and its limits
+
+**Headless is not a capability-reduced mode.** Across 238 paired observations —
+139 read-only API probes plus 13 write scenarios covering pages, media pool,
+timeline editing, colour, Fusion comps, Gallery, render-to-disk, interchange
+export, layout presets, playhead and project settings — there were **zero**
+capabilities that worked with a UI and failed without one.
+
+The one difference found runs the other way: headless cannot raise a modal
+dialog, and modals are the most common way an agent-driven Resolve session
+wedges.
+
+**That is a claim about capability and about modals. It is not a claim about
+stability.** See the next section before pointing a long delivery at it.
+
+## What is and is not measured about stability
+
+Measured, and clean: **10 consecutive ProRes 422 HQ renders in one headless
+session**, from a 1045-frame JPEG 2000 / MXF OP1A / 12-bit source — the decode
+path a DCP video track file takes — with no crash, no death, and no leak. See
+the stress table below. That covers repeated jobs in one session, heavy source
+decode, and the encoder teardown at the end of every write, ten times over.
+
+Still **not** measured:
+
+- **Sustained encode over hours.** Ten 45-second renders is not a feature-length
+  delivery. Thermal behaviour and codec-library state over thousands of frames
+  remain untested.
+- **The operator's actual footage, codec settings and durations.**
+- **ProRes into MXF** — not because it was skipped, but because this build does
+  not offer it: `GetRenderCodecs` returns ProRes only under `mov`.
+
+**Field report:** rendering ProRes from DCP sources has crashed *on completion of
+writes* in headless sessions on this machine. The stress leg above exercises that
+same teardown path ten times without a failure, so the write-completion path is
+not trivially broken headless — but ten short renders cannot disprove a fault
+that appears on a long one, and this does not.
+
+Note what changed here. An earlier version of this page reported the headless
+stress leg as hanging reproducibly at 0/10, which read as evidence for headless
+instability. It was not: the harness was calling `SaveProject()` on the
+never-saved `Untitled Project`, which blocks the whole application. **A harness
+bug had been sitting in the "headless is unstable" column.** Once guarded, the
+leg ran straight through on the first attempt.
+
+Two artefacts worth keeping from the log investigation:
+
+- A per-session GUI/headless marker for classifying logs after the fact:
+  `Show splash screen` appears in GUI sessions and never in headless ones.
+- A full WARN/ERROR diff between known-headless and known-GUI sessions found
+  **nothing headless-specific**. In particular `Encoder audio was not flushed` —
+  the most suggestive warning for a write-completion crash — occurs in both
+  modes, and more often in the GUI ones. It is not a headless marker.
+
+**Practical rule:** headless is qualified for orchestration, edit, conform,
+analysis and renders of this scale. Qualify it on your own footage before a
+long-form or professional-container delivery, and keep a GUI fallback for those.
+
+### Differencing the two modes exhaustively
+
+`scripts/mode_matrix.py` is the second-generation differential, and it exists
+because the first one **could not have found the `SaveProject` hang**. That
+harness called everything in one process with no timeouts, so a call that never
+returns simply ended the run; its clean report of "zero mode-dependent failures"
+was partly a description of what it was able to survive.
+
+Three changes make exhaustive comparison possible:
+
+- **`hang` is a first-class verdict.** A call that returns `False` is
+  survivable; one that never returns takes the session with it and degrades the
+  instance afterwards. Collapsing them into "failed" hides the worse bug.
+- **Supervisor and worker are separate processes.** The worker streams one
+  flushed JSONL result per probe, in catalogue order. When it dies, the
+  supervisor knows the first unrecorded probe was in flight, records it as
+  `hang`, restarts Resolve, waits for health, and resumes after it. A hang costs
+  one probe and one restart, not the run. Nothing in-process can do this: a
+  Python signal handler cannot preempt a thread parked in fusionscript's
+  `pthread_cond_wait`, which is why the alarm-based approach only ever worked by
+  luck.
+- **State is part of each probe.** `SaveProject` is harmless on a named project
+  and fatal on the never-saved default, so probes declare which project must be
+  current. A catalogue that only ever ran against a well-formed scratch project
+  is exactly what reported no differences the first time.
+
+Phase breadcrumbs distinguish a hang in a probe's own call from a hang while
+reaching its state — a real distinction, since setting up the "untitled" state
+means closing a project, and closing a *modified* project raises the GUI save
+dialog. Without the breadcrumb that dialog was attributed to the probe that
+never got to run.
+
+### Stressing it without production assets
+
+`scripts/render_stress.py` closes most of that gap before real footage is
+available. It renders repeatedly in one session and watches for the things that
+distinguish *causes* rather than merely recording that something died:
+
+- `crash_archive.txt` is bracketed per iteration, so a stack is attached to the
+  render that produced it. Resolve appends every crash to one growing file with
+  no timestamps, so without the bracket "did this render crash" is guesswork.
+- The Resolve PID is watched from outside, so a hard exit is a recorded result
+  instead of a hung harness.
+- Resident memory is sampled through each render. A leak and a teardown bug both
+  present as "it crashes eventually"; the RSS curve separates them.
+- `--restart-on-crash` continues past the first death, because failing on
+  iteration 2 and failing on iteration 40 are different findings.
+
+The synthetic source is JPEG 2000 in MXF OP1A at 12-bit 1998×1080, written by
+ffmpeg. Resolve identifies it as `JPEG 2000 / MXF OP1A / 12 bit` — the decode
+path a DCP video track file takes. `--source` swaps in real media later with
+nothing else changing.
+
+One thing to get right about the target: **this build offers ProRes in no MXF
+flavour.** `GetRenderCodecs` returns ProRes only under `mov`; neither
+`mxf_op1a` (76 codecs) nor `mxf` (47) lists it. So "MXF to ProRes" means
+J2K-MXF in, ProRes-QuickTime out, and a harness that tried to render ProRes into
+MXF would fail for that reason rather than for any reason worth reporting.
+
+```bash
+python scripts/render_stress.py --mode headless --iterations 20 --duration 60 \
+    --restart-on-crash --report headless.json
+python scripts/render_stress.py --mode gui --iterations 20 --duration 60 \
+    --restart-on-crash --report gui.json
+```
+
+Confirming a crash on the real job still needs the real job — same source and
+preset, both modes, `ResolveDebug.txt` kept from each. The harness narrows where
+to look; it does not replace that.
+
+### Stress results: both modes, 10 ProRes renders each
+
+10 renders per leg, 1045-frame JPEG 2000 timeline, ProRes 422 HQ QuickTime,
+~553 MB per render, identical parameters.
+
+| | GUI | headless |
+| --- | --- | --- |
+| completed | 10 / 10 | **10 / 10** |
+| process deaths | 0 | **0** |
+| crash blocks captured | 0 | **0** |
+| bytes per render | 553,050,011 | 553,050,011 (identical) |
+| render time mean | 22.6s | **21.5s** |
+| render time first → last | 21.8 → 22.7s | 21.4 → 22.4s |
+| peak RSS first → last | 2096 → 2104 MB | **2002 → 2010 MB** |
+
+**Headless is clean, and marginally better than the GUI on both axes** — about
+1.1s faster per render and ~95 MB lighter throughout. No leak in either mode:
+8 MB of RSS drift across ten renders, which is noise. Output is byte-identical.
+
+An earlier version of this page reported the headless leg as "hung during setup,
+0/10, reproducibly". That was true at the time and the cause was **not** render
+instability: the harness was hitting `SaveProject()` on the never-saved
+`Untitled Project`, which blocks the whole application (see the modal trap
+above). Once that was guarded, the leg ran straight through on the first
+attempt. A harness bug had been sitting in the "headless is unstable" column.
+
+**What this still does not settle:** the field report of crashes on completion of
+writes during DCP→ProRes delivery. This is 10 renders of ~45 seconds each from
+synthetic J2K. It exercises the decode and encode paths and the teardown at the
+end of every write, ten times, without a single failure — but it is not hours of
+sustained encode, and it is not the operator's footage, codec settings or
+durations. Treat it as "the write-completion path is not trivially broken
+headless", not as a clearance for long-form delivery.
+
+### Differencing the two modes exhaustively
+
+`scripts/mode_matrix.py` is the second-generation differential, and it exists
+because the first one **could not have found the `SaveProject` hang**. That
+harness called everything in one process with no timeouts, so a call that never
+returns simply ended the run; its clean report of "zero mode-dependent failures"
+was partly a description of what it was able to survive.
+
+Three changes make exhaustive comparison possible:
+
+- **`hang` is a first-class verdict.** A call that returns `False` is
+  survivable; one that never returns takes the session with it and degrades the
+  instance afterwards. Collapsing them into "failed" hides the worse bug.
+- **Supervisor and worker are separate processes.** The worker streams one
+  flushed JSONL result per probe, in catalogue order. When it dies, the
+  supervisor knows the first unrecorded probe was in flight, records it as
+  `hang`, restarts Resolve, waits for health, and resumes after it. A hang costs
+  one probe and one restart, not the run. Nothing in-process can do this: a
+  Python signal handler cannot preempt a thread parked in fusionscript's
+  `pthread_cond_wait`, which is why the alarm-based approach only ever worked by
+  luck.
+- **State is part of each probe.** `SaveProject` is harmless on a named project
+  and fatal on the never-saved default, so probes declare which project must be
+  current. A catalogue that only ever ran against a well-formed scratch project
+  is exactly what reported no differences the first time.
+
+Phase breadcrumbs distinguish a hang in a probe's own call from a hang while
+reaching its state — a real distinction, since setting up the "untitled" state
+means closing a project, and closing a *modified* project raises the GUI save
+dialog. Without the breadcrumb that dialog was attributed to the probe that
+never got to run.
+
+### Stressing it without production assets
+
+`scripts/render_stress.py` closes most of that gap before real footage is
+available. It renders repeatedly in one session and watches for the things that
+distinguish *causes* rather than merely recording that something died:
+
+- `crash_archive.txt` is bracketed per iteration, so a stack is attached to the
+  render that produced it. Resolve appends every crash to one growing file with
+  no timestamps, so without the bracket "did this render crash" is guesswork.
+- The Resolve PID is watched from outside, so a hard exit is a recorded result
+  instead of a hung harness.
+- Resident memory is sampled through each render. A leak and a teardown bug both
+  present as "it crashes eventually"; the RSS curve separates them.
+- `--restart-on-crash` continues past the first death, because failing on
+  iteration 2 and failing on iteration 40 are different findings.
+
+The synthetic source is JPEG 2000 in MXF OP1A at 12-bit 1998×1080, written by
+ffmpeg. Resolve identifies it as `JPEG 2000 / MXF OP1A / 12 bit` — the decode
+path a DCP video track file takes. `--source` swaps in real media later with
+nothing else changing.
+
+One thing to get right about the target: **this build offers ProRes in no MXF
+flavour.** `GetRenderCodecs` returns ProRes only under `mov`; neither
+`mxf_op1a` (76 codecs) nor `mxf` (47) lists it. So "MXF to ProRes" means
+J2K-MXF in, ProRes-QuickTime out, and a harness that tried to render ProRes into
+MXF would fail for that reason rather than for any reason worth reporting.
+
+```bash
+python scripts/render_stress.py --mode headless --iterations 20 --duration 60 \
+    --restart-on-crash --report headless.json
+python scripts/render_stress.py --mode gui --iterations 20 --duration 60 \
+    --restart-on-crash --report gui.json
+```
+
+Confirming a crash on the real job still needs the real job — same source and
+preset, both modes, `ResolveDebug.txt` kept from each. The harness narrows where
+to look; it does not replace that.
+
+### First stress results (2026-08-01, Studio 19.1.3.7)
+
+10 renders per leg, 1045-frame J2K timeline, ProRes 422 HQ QuickTime, ~553 MB
+per render.
+
+| | GUI | headless |
+| --- | --- | --- |
+| iterations completed | 10 / 10 | **0 — hung during setup** |
+| process deaths | 0 | 0 (hung, did not die) |
+| crash blocks captured | 0 | 0 |
+| render time first → last | 21.8s → 22.7s | — |
+| peak RSS first → last | 2096 MB → 2104 MB | — |
+
+**The GUI leg is clean.** Ten consecutive ProRes renders, no crash, no leak (8 MB
+of RSS drift across the run), no degradation in render time. Nothing in the
+write-completion path failed with a UI present.
+
+**The headless leg never rendered.** Twice, the harness connected, reported
+`headless=True`, and then blocked forever in `Fusion::RemoteApp::WaitPkt` during
+project setup — before generating any media. In both cases a second client
+found `GetCurrentDatabase()` returning `None` on the same instance.
+
+What is and is not established:
+
+- **Established:** a headless instance can reach a state where scripted project
+  work hangs indefinitely, and that state coincides with a null current
+  database. Reproduced twice.
+- **Established:** it is not inherent to headless. An earlier headless session
+  the same day created a project, rendered, exported five interchange formats,
+  and tore down cleanly.
+- **Not established:** the trigger. Both hangs happened when headless was
+  started *after* other heavy Resolve activity — once after force-killing a
+  wedged instance, once immediately after a 10-render GUI leg and a clean
+  `Quit()`. That is a suggestive pattern, not a cause.
+- **Not established:** whether the null database is cause or symptom. The
+  reading was taken from a second client while the first was blocked, so it may
+  reflect the block rather than explain it.
+
+So the honest state of the stability question is: **the GUI path is measured
+clean at this scale, and the headless path has a real, reproducible failure that
+is not yet pinned down.** That is consistent with the field report of headless
+instability, and it is a reason to keep a GUI fallback for deliveries until the
+trigger is understood.
+
+## Verified
+
+### Launch and teardown
+
+```bash
+"/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/MacOS/Resolve" -nogui
+```
+
+Launch the **binary inside the bundle**, not `open -a`. `open` hands the
+argument list to LaunchServices, which starts the app normally and drops
+`-nogui` on the floor — you get a GUI and no error.
+
+| Observation | Measured |
+| --- | --- |
+| Launch → `scriptapp("Resolve")` answers | under 3s (warm cache) |
+| Launch → `ProjectManager` answers `GetProjectListInCurrentFolder()` | same instant, no extra wait |
+| `resolve.Quit()` → process gone | 2.1s |
+| Resident memory, idle, no project | ~1.9 GB |
+| Scripting listener | TCP 15000, bound to all interfaces, same as GUI |
+
+`Quit()` is the correct teardown. It discards the open project without
+prompting, which is exactly what you want from a batch process and exactly what
+`CloseProject` on an unsaved project must never be asked to do.
+
+`scriptapp()` answering is *not* proof the ProjectManager is ready. It was ready
+immediately here, but earlier sessions on this codebase recorded it lagging, so
+`scripts/headless_differential.py` polls
+`GetProjectListInCurrentFolder()` rather than trusting the handle. Keep that
+pattern; the failure it prevents looks like "headless cannot see any projects".
+
+### Everything that works headless
+
+Verified working, identically to the GUI:
+
+- **All seven pages.** `OpenPage()` returns True for media, cut, edit, fusion,
+  color, fairlight and deliver, and `GetCurrentPage()` reads each one back.
+  There is no window, but the page concept is real and page-gated calls behave.
+- **Render to disk.** Format and codec enumeration, `SetRenderSettings`,
+  `AddRenderJob`, `StartRendering(isInteractiveMode=False)`, status polling to
+  `Complete`, and a non-empty file on disk.
+- **Interchange export.** AAF, EDL, FCP7 XML, DRT and OTIO all written non-empty.
+- **`Project.ExportCurrentFrameAsStill()`.** Returns True and writes a real PNG.
+  This contradicts a 2026-07-03 working note that recorded it as a headless-only
+  failure — see "Corrections" below.
+- **`Timeline.GrabStill()`.** Returns a live still object.
+- **Fusion.** `resolve.Fusion()`, `Fusion.GetCurrentComp()`, and per-clip
+  `AddFusionComp` / `GetFusionCompNameList` / comp counting.
+- **Colour.** Node graph access, `GetNumNodes`, `GetNodeLabel`, `GetLUT`,
+  `SetNodeEnabled`, and colour group create / assign / delete.
+- **Layout presets.** `SaveLayoutPreset`, `ExportLayoutPreset` (170 KB written),
+  `LoadLayoutPreset`, `DeleteLayoutPreset` — all True, with no UI to lay out.
+  Included in the probe precisely because it was expected to fail; it does not.
+- **Ordinary editorial.** Markers, tracks, track names, clip properties, media
+  pool folders, project settings, playhead timecode.
+
+### The modal trap — and why headless is WORSE, not immune
+
+**An earlier version of this page claimed headless was immune to modal dialogs
+and therefore the safer mode. That was wrong, and it was the most consequential
+error in the study.** Headless is not immune. It cannot *display* a dialog, but
+it still tries to raise one — and the call then never returns.
+
+`ProjectManager.SaveProject()` on the default, never-saved project named
+`Untitled Project`:
+
+| | GUI | headless |
+| --- | --- | --- |
+| result | returns `False` | **blocks forever** |
+| observed | immediate | no return after 45s; client parked in `Fusion::RemoteApp::WaitPkt` |
+| recoverable by | a human clicking the dialog | nothing — the client must be killed |
+
+Measured on a cold headless boot with the database verified attached
+immediately before the call, so nothing else was wrong with the instance.
+
+The project has no location to save to and the API offers no `SaveProjectAs`, so
+Resolve wants a Save-As dialog. With a UI it can ask and move on. Without one it
+waits for an answer that can never arrive.
+
+**This inverts the usual advice.** The standard defence against losing work on a
+project switch — "call `SaveProject()` first" — is the exact call that hangs a
+headless session, and it hangs on precisely the project that made you want to
+call it. In the GUI the same situation costs a human one click; headless it
+costs the run.
+
+It also degrades: after a hung `SaveProject` was interrupted, the same instance
+began returning `None` from `SaveProject` instantly, and in other runs reached
+the no-database wedge described below. So the first hang is not the end of it.
+
+**The rule:** never call `SaveProject()` in a headless session without first
+checking that the current project is not the never-saved `Untitled Project`.
+Check `GetCurrentProject().GetName()` and skip the save — there is nothing to
+save, and the call cannot succeed.
+
+```python
+project = pm.GetCurrentProject()
+if project is not None and project.GetName() != "Untitled Project":
+    pm.SaveProject()          # safe: it has a location
+# else: nothing to save, and calling it headless blocks forever
+```
+
+Name-matching is a blunt guard — a real project deliberately named
+"Untitled Project" would be skipped — but skipping a save on a named project
+costs nothing here, while calling it on the default one costs the session.
+
+### Detecting headless
+
+**There is no API tell.** `GetCurrentPage()` answers with a real page,
+`GetProductName()` and `GetVersionString()` are unchanged, and every UI-shaped
+call the probe tried returns the same value as the GUI. Anything that inspects
+the `resolve` handle to decide whether it has a UI is guessing.
+
+The only reliable signal is the process's own argument vector — `-nogui` in the
+command line of the running `…/Contents/MacOS/Resolve`. That is what
+`src/utils/resolve_runtime.py` reads.
+
+### The wedge: a Resolve with no database attached
+
+The most dangerous failure state found so far, because every cheap health check
+passes through it.
+
+After an unclean shutdown, a headless instance came back up **attached to no
+project database**. It accepted scripting connections. `GetProductName`,
+`GetVersionString`, `GetCurrentPage` and `GetCurrentProject` all answered
+normally. And yet:
+
+- `CreateProject` and `LoadProject` returned `False` — indefinitely, not flakily.
+- `SaveProject` returned `None`.
+- Some calls never returned at all: the client sat in
+  `Fusion::RemoteApp::WaitPkt` forever while a *different* client got instant
+  answers from the same instance.
+- It did not recover. Only a restart cleared it.
+
+**The tell is `ProjectManager.GetCurrentDatabase()` returning `None`.** Healthy
+looks like `{"DbType": "Disk", "DbName": "Local Database"}`.
+`resolve_control(action="runtime_mode")` reports this as `database_attached`,
+and flips its guidance to `WEDGED:` when it is false. Check it before doing work
+in an unattended session — a liveness check that only proves the API answers
+will sail straight past this.
+
+Two related observations from the same episode:
+
+- **Slow startup is not a hang.** That instance took **2 minutes 5 seconds** to
+  start its script server, against under 3 seconds for a clean boot, sitting at
+  0% CPU in an idle Qt run loop the whole time. A 90-second readiness timeout
+  gave up 15 seconds early. Allow at least 5 minutes before declaring a launch
+  failed, and never start a second instance on a timeout — that converts a slow
+  start into singleton contention.
+- **A stale database entry costs startup time every boot.** This machine's
+  `~/Library/Preferences/Blackmagic Design/DaVinci Resolve/dblist.conf` lists a
+  disk database whose path no longer exists, and each start logs
+  `Cannot connect to <name> database: path not found`. Worth pruning on any
+  machine that runs Resolve unattended.
+
+- **Killing a scripting client mid-render can wedge the instance it was driving.**
+  Prefer letting a render finish, or `Quit()`, over killing the client.
+
+### Singleton rules
+
+One Resolve per machine. The application, a render node, and any scripted launch
+all contend for the same singleton, and losing that contention has produced
+crash loops in this codebase's history rather than a clean error — every
+project open/close collision died in Fairlight page teardown.
+
+Before starting a headless instance, confirm nothing else has one:
+
+```bash
+ps -Ao pid=,command= | grep "MacOS/Resolve" | grep -v grep
+```
+
+An empty result is the only safe state. If a render node manages Resolve on this
+machine, turn it off first.
+
+## The expanded sweep: 105 probes, still no real mode differences
+
+The catalogue grew from 92 to 105 probes, adding the surfaces most likely to
+behave differently without a UI: long-running and Studio-AI operations
+(`TranscribeAudio`, `AutoSyncAudio`, `CreateSubtitlesFromAudio`, proxy
+link/unlink), editorial constructs (compound clips, Fusion clips, take
+selectors, nested timelines, clip linking) and project-level delivery
+(render presets, burn-in presets, `ArchiveProject`, multi-job render queues).
+
+Result across 2 GUI × 2 headless runs: **86 parity, 14 both-failed, 0 flaky, and
+5 apparent mode differences that all evaporated under isolation.**
+
+### Not API-reachable at all
+
+Worth stating because their absence is easy to mistake for a headless problem:
+**retimes/speed changes, transitions, and multicam have no scripting API** in
+this reference. Nothing can round-trip what cannot be created. `CreateCompoundClip`
+and `CreateFusionClip` are documented but raise `TypeError` on 19.1.3 — present
+in the docs, absent from this build.
+
+### Five false findings, and the rule they produced
+
+A full sweep reported `editorial.nested_timeline` and `editorial.set_clips_linked`
+as `headless_degraded`, and take selectors, multi-job queues and render presets
+as `divergent`. Re-run with `--only` against a fresh fixture, **all five are
+identical in both modes.**
+
+The cause is ordering. Probes run in catalogue order against one shared fixture,
+so a probe near the end carries ~90 destructive probes' worth of accumulated
+state, and the two modes drift apart for reasons unrelated to the mode. The
+report now carries that warning inline, and the rule is simple:
+
+**An actionable finding from a full sweep is a hypothesis. Re-run it with
+`--only` in both modes before believing it.**
+
+That is the third distinct class of false positive this study has produced —
+after single-run flake (fixed by requiring repetition) and mixing catalogue
+versions (fixed by fingerprinting). Every one of them looked like a real
+headless bug first.
+
+## Rendered pixels are identical
+
+The strongest result in this study, and the one everything else was missing.
+Every earlier comparison was of structure and return values; none of them could
+have caught a headless render that completes, produces a file of the right
+length in the right codec, and contains the wrong image.
+
+Five timelines rendered in each mode to ProRes 422 HQ, compared **after
+decoding** with ffmpeg `framemd5` so container metadata cannot influence the
+result:
+
+| effect | changed the picture? | pixels across modes |
+| --- | --- | --- |
+| plain | — | **identical** |
+| transform (zoom/pan/rotate) | yes | **identical** |
+| CDL grade | yes | **identical** |
+| 3D LUT | yes | **identical** |
+| Fusion comp (MediaIn→Blur→MediaOut) | yes | **identical** |
+
+The middle column is the control that makes the result mean anything. If a grade
+did not change the picture relative to plain, then "the modes agree" would only
+mean both rendered the same ungraded image. Every treatment is proven to have
+changed the output first — which took two corrections to achieve:
+
+- **`SetLUT` silently refused an absolute path.** It returns False and reads
+  back an empty string for a LUT Resolve has not "discovered". The first run
+  recorded `applied: False` and rendered pixels identical to plain, which would
+  have been written up as "LUT survives headless" — a pass produced by a grade
+  that never happened. Staging the LUT into the master LUT directory
+  (`src/utils/lut_paths.py:ensure_lut_in_master`) and referencing it relatively
+  fixes it.
+- **An empty Fusion comp cannot change anything**, so adding one and finding the
+  pixels unchanged proves nothing about whether Fusion reaches the renderer.
+
+## Fusion comps DO render from the API — if the graph is rooted
+
+Correcting this repository's own note, which said a comp created on a media clip
+through the API is "never applied at render".
+
+A comp wired `MediaIn → Blur → MediaOut`, created entirely through the API on an
+ordinary media clip, **renders in both modes**: PSNR between the plain and
+Fusion renders of the same timeline is 22.7 dB (identical would be infinite) and
+the file shrinks 22.5 MB → 14.8 MB, exactly as a blur should.
+
+The distinguishing factor appears to be whether MediaOut descends from MediaIn.
+The original observation — a MediaOut fed only by a Text+ with no MediaIn path,
+rendering the untouched clip — was not re-measured and stands for that
+configuration.
+
+A related failure worth knowing: a first attempt wired only `MediaOut → Blur`,
+leaving the Blur with no source. That did not silently bypass the comp — the
+**render job came back `Failed` with an 887-byte file.** An unrooted graph can
+take the render down.
+
+## Network scripting reaches a headless instance
+
+Confirmed rather than assumed: `scriptapp("Resolve", "127.0.0.1")` and the repo's
+`connect_resolve` with `RESOLVE_SCRIPT_HOST` both connect to a `-nogui` instance
+and see its database and all 242 projects. Headless and network scripting
+compose.
+
+`fuscript -p Resolve` also **discovers** a headless instance over the network,
+reporting hostname, IP, version and platform with no Python involved — useful
+for a supervisor checking what is running. Its script-execution forms (`-x` and a
+script file, Lua or py3) printed only the interpreter banner and produced no
+output in this build; not pursued further.
+
+**The in-app bridge cannot work headless.** The bridge listener only exists once
+someone runs Workspace > Scripts > resolve_bridge *inside* Resolve, and that menu
+requires a UI. Since external scripting is Studio-only, this means **the free
+edition cannot be driven headless at all** — the bridge is its only transport,
+and headless is the one mode where the bridge cannot be started.
+
+## Isolated instances: yes. Parallel instances: no.
+
+The `BMD_RESOLVE_*_DIR` variables found in the binary **do work**, and they
+isolate more thoroughly than expected — but they do not defeat the singleton.
+
+**Measured, launching a second `-nogui` instance with isolated directories while
+one was already running:** the second process started, created a complete
+private tree — `config/config.dat`, `support/Resolve Project Library`,
+`support/Fairlight`, `support/DolbyVision`, `support/easyDCP` — and then **exited
+silently**, logging nothing beyond two log4cxx lines. The first instance was
+unharmed and kept port 15000. So **parallel headless workers on one machine are
+not possible this way.** That closes the biggest open architectural question on
+this list, in the negative.
+
+**Running alone, the same isolated instance works completely** — its own
+database with **zero projects**, entirely separate from the user's 242. That is
+still valuable: a CI or render worker that cannot see, lock, or damage the
+operator's projects.
+
+One non-obvious step is required. A fresh config does **not** enable external
+scripting, so an isolated instance starts unreachable — it runs, opens no
+listener, and looks like a hang. The user's own config has
+`System.Scripting.Mode = 1`; a fresh one has no such key. `config.dat` is plain
+ASCII, so seeding it is a one-liner:
+
+```bash
+ISO=/path/to/isolated
+mkdir -p "$ISO"/{config,support,logs,lut}
+
+# One boot to generate the default config, then enable external scripting.
+BMD_RESOLVE_CONFIG_DIR="$ISO/config" BMD_RESOLVE_SUPPORT_DIR="$ISO/support" \
+BMD_RESOLVE_LOGS_DIR="$ISO/logs"     BMD_RESOLVE_LUT_DIR="$ISO/lut" \
+  "/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/MacOS/Resolve" -nogui &
+sleep 30; pkill -f "MacOS/Resolve"; sleep 8
+echo "System.Scripting.Mode = 1" >> "$ISO/config/config.dat"
+
+# Now it is scriptable, with its own empty project library.
+BMD_RESOLVE_CONFIG_DIR="$ISO/config" BMD_RESOLVE_SUPPORT_DIR="$ISO/support" \
+BMD_RESOLVE_LOGS_DIR="$ISO/logs"     BMD_RESOLVE_LUT_DIR="$ISO/lut" \
+  "/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/MacOS/Resolve" -nogui &
+```
+
+`BMD_RESOLVE_LOGS_DIR` is the one that did not fully take: the isolated tree got
+`LogArchive/` and `gpudetect.bin` but no main log.
+
+## `-fastmode`: starts, and is not scriptable
+
+Exercised in the isolated sandbox. `Resolve -nogui -fastmode` starts a process
+that stays alive at 0% CPU and **never opens the scripting listener** — port
+15000 is not bound at all, and it was still unreachable after two minutes.
+Whatever it is for, it is not usable for automation. Do not use it.
+
+## Deliberately NOT exercised
+
+`-activate` and `-deactivate` are left untested **on purpose**, not by omission.
+The strings beside them ("License activated successfully.", "An activation
+already exists on this machine.", "License deactivated successfully.") say
+plainly that they mutate this machine's Studio licence activation. Running
+`-deactivate` to find out what it does could cost the operator their activation,
+and no finding here is worth that. If licence automation is ever needed, test it
+on a machine whose activation is expendable.
+
+## Present but not exercised
+
+Read out of the application binary's argument table, adjacent to `-nogui` in the
+same string block. Their existence is certain; their behaviour is not tested,
+and none should be used in automation without qualifying it first.
+
+| Flag | Adjacent strings suggest |
+| --- | --- |
+| `-fastmode` | Unknown. No accompanying diagnostic strings. |
+| `-activate` / `-deactivate` | Licence activation from the command line — "License activated successfully.", "An activation already exists on this machine.", "License deactivated successfully.", and an interactive `Please enter q or Q to exit:` prompt. Plausibly the supported way to licence a render node without a GUI. |
+| `-versionUpdate` | Update check. |
+| `-reportCrash` | Crash reporter entry point. |
+| `-test_suite` / `-test_suite_gui` | Blackmagic-internal test harness. |
+| `-psn` | macOS process serial number, passed by LaunchServices. |
+
+Environment variables in the same binary, likewise unexercised, that appear to
+relocate Resolve's per-user directories — the mechanism an isolated CI instance
+would need:
+
+`BMD_RESOLVE_CONFIG_DIR`, `BMD_RESOLVE_LICENSE_DIR`, `BMD_RESOLVE_LOGS_DIR`,
+`BMD_RESOLVE_LUT_DIR`, `BMD_RESOLVE_SUPPORT_DIR`.
+
+Whether setting these actually lets two Resolve instances coexist is **the open
+question worth answering next**. It would decide whether parallel headless
+render workers are possible at all.
+
+## Environment variables that are verified
+
+The scripting ones, required for any external Python to find the API:
+
+```bash
+export RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting"
+export RESOLVE_SCRIPT_LIB="/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so"
+export PYTHONPATH="$PYTHONPATH:$RESOLVE_SCRIPT_API/Modules/"
+```
+
+On Linux the paths are `/opt/resolve/Developer/Scripting` and
+`/opt/resolve/libs/Fusion/fusionscript.so`, with the binary at
+`/opt/resolve/bin/resolve`; on Windows, `%PROGRAMDATA%\Blackmagic Design\DaVinci
+Resolve\Support\Developer\Scripting` and `C:\Program Files\Blackmagic
+Design\DaVinci Resolve\fusionscript.dll`, with `Resolve.exe` taking `-nogui`
+directly.
+
+`RESOLVE_SCRIPT_HOST` and `RESOLVE_SCRIPT_TIMEOUT` select this server's network
+scripting mode; see the network-mode notes in `docs/SKILL.md`. The listener a
+headless instance opens on port 15000 is the same one that mode connects to, so
+headless and network scripting compose.
+
+## Corrections to earlier notes
+
+A 2026-07-03 working note recorded Gallery `ExportStills` and
+`export_frame_as_still` as **headless-only failures**. Settling this took three
+attempts, and the sequence is worth keeping because each wrong answer was
+confidently held:
+
+1. The original note: headless-only failure.
+2. A hand-written test found it failing in the GUI too, and "corrected" the note.
+   That test was bad — its `GrabStill` had returned `False`, so `ExportStills`
+   was handed nothing to export and its `False` said nothing about anything.
+3. Two proper sweeps then showed GUI `True/2 files` versus headless `False/0`,
+   which looked like a clean confirmation of the original note.
+4. Four controlled sweeps (2 per mode, same catalogue version) showed it
+   returning `False` in **all four**, both modes — with `GrabStill` succeeding
+   in all four.
+
+**The answer is that it is panel-dependent, not mode-dependent.** The variable
+that changed between the one GUI success and the four failures is whether the
+Gallery panel was visible on the Color page — restored workspace state, which
+the harness does not control. Headless can never satisfy it; a GUI session
+satisfies it only sometimes. So *in practice* it never works headless, but
+"headless" is not the cause and switching to a GUI session is not a fix.
+
+`ExportCurrentFrameAsStill`, by contrast, worked in all four runs in both modes.
+Use it.
+
+Two methodological lessons, both learned the hard way here:
+
+- **A negative result needs its preconditions verified as carefully as a
+  positive one.** Step 2 above was a confident correction built on an
+  unverified precondition.
+- **One run per mode reports noise as findings.** Before repetition was added,
+  `app.keyframe_mode` was reported as `headless_degraded` in one comparison and
+  `gui_degraded` in another — it returns `0` and `None` in *both* modes
+  depending on the run. The comparison now requires a probe to be internally
+  consistent within a mode before it may be called a difference between modes,
+  and reports the rest as `flaky`.
+
+This page is regenerable — rerun the sweeps rather than trusting it after a
+Resolve upgrade.
+
+## Reproducing
+
+```bash
+# 1. GUI baseline
+python scripts/headless_differential.py record --label gui --out /tmp/gui.json
+
+# 2. quit Resolve, then
+"/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/MacOS/Resolve" -nogui &
+python scripts/headless_differential.py record --label headless --out /tmp/headless.json
+
+# 3. difference them
+python scripts/headless_differential.py compare /tmp/gui.json /tmp/headless.json \
+    --out docs/reference/headless-capability-matrix.md
+```
+
+`record` refuses to run if the `--label` contradicts the running process's argv,
+which is the mistake that would otherwise silently invert every verdict. It
+creates and deletes its own scratch project and saves the incumbent first, but
+it does switch projects — do not point it at a session with unsaved work.