Repository navigation
feat(installers): pre-download CorridorKeyBlue checkpoint alongside the green one - #248
Merged
nikopueringer merged 1 commit intoMay 1, 2026
Conversation
…eckpoint
Today the bundled installers (Install_CorridorKey_Linux_Mac.sh and
Install_CorridorKey_Windows.bat) fetch only the green checkpoint
(`CorridorKey_v1.0.safetensors`). When a user later runs the keyer with
`--screen-color blue` (or auto-detection picks blue), the Python runtime
in `_ensure_torch_checkpoint` makes a one-time ~300 MB pull from
HuggingFace before the first frame can render. That's a surprise
mid-session download that's easy to miss in headless / batch contexts
(Nuke, Houdini, render farms).
Adds a parallel download block targeting
`huggingface.co/nikopueringer/CorridorKeyBlue_1.0/resolve/main/CorridorKeyBlue_1.0.safetensors`
right after the green block. Two design choices to call out:
1. The blue download is best-effort. If `curl --fail` returns non-zero
(HF repo deleted, transient 5xx, no network) we log a one-line
informational message and continue, deleting any partial file. The
install still completes successfully so users keying green plates
aren't blocked by an unrelated download. The Python runtime retries
the download on first blue use, so the only cost of a failure here
is a deferred 300 MB pull.
2. The check is "file exists?" not "checksum matches?" — same as the
existing green block. Matches the established convention; keeps the
scripts simple to audit.
Verified locally with `bash -n` for the .sh script. The .bat script
mirrors the same structure as the existing green block byte-for-byte
including the `^(...^)` escapes and `errorlevel 1` checks.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Closes #243.
The bundled installer scripts (
Install_CorridorKey_Linux_Mac.sh,Install_CorridorKey_Windows.bat) currently pre-download only the green checkpoint. Anyone shooting blue gets a surprise ~300 MB HF pull on the first--screen-color bluerun (or whenever auto-detection lands on blue) — handled lazily by_ensure_torch_checkpointin Python. That's fine technically, but it's a foot-gun for headless / Nuke / render-farm contexts where "the keyer mysteriously stalls for a few minutes mid-job" is hard to diagnose.This PR makes the installer fetch both checkpoints up front, the same way it already fetches the green one.
What changes
Both installer scripts now download
CorridorKeyBlue_1.0.safetensorsfromhuggingface.co/nikopueringer/CorridorKeyBlue_1.0right after the green block, into the sameCorridorKeyModule/checkpoints/directory. The block mirrors the existing green logic byte-for-byte.Two design choices worth flagging:
Blue download is best-effort. If
curl --failreturns non-zero (HF repo deleted, transient 5xx, network blocked), the script logs an info message and continues. The install still completes. The Python runtime's_ensure_torch_checkpoint("blue")will retry on first use. Failure here is at most a deferred download, never a broken install.Existence check is "file present?" not "checksum matches?" Same as the existing green block. Keeps the scripts grep-able and easy to audit. If we ever need integrity validation, the place to add it is the Python runtime, not the shell.
How I verified
The .bat script mirrors the existing green block's structure exactly: same
if exist/elseshape, samecurl.exe -L --failflags, sameerrorlevel 1check, same^(...^)escapes. No new constructs.Why this is its own PR
Plan for #241 (the Python feature itself) deliberately scoped installers out — the runtime auto-download path is already exercised and working. This is a UX improvement on top: it doesn't change any code path, just front-loads a download that would otherwise happen lazily. Easier to review and revert independently if a build farm wants to pin the green-only behaviour for some reason.
Test plan
bash -n) passes.Install_CorridorKey_*.sh/batends up with both.safetensorsfiles incheckpoints/).