ComfyUI-CineSpatial

ComfyUI-CineSpatial

Owned, API-oriented ComfyUI nodes for CineSpatial's cinematic 5.1 analysis worker. ComfyUI is an execution engine; the CineSpatial Studio UI and deterministic renderer live outside this package.

Nodes

• CineSpatialWorkerHealth
• CineSpatialBanditSeparate
• CineSpatialTranscribeAlignDialogue
• CineSpatialDetectActiveSpeaker
• CineSpatialClassifyAudioEvents
• CineSpatialGroundVisualSources
• CineSpatialQuerySeparateEvent
• CineSpatialValidateArtifact

Safety boundary

The package registers without installing heavyweight or mutually incompatible research dependencies into ComfyUI. Model operations call only the fixed loopback endpoint http://127.0.0.1:8199/v1; the node package never launches a program, evaluates code, reads an environment-selected command, or accepts a caller-selected service address. Missing services or invalid artifacts fail explicitly.

Release 0.1.4 exposes authenticated GET /cinespatial/health. It asks the loopback service for boolean checkpoint and operation readiness; no checkpoint path or administrative command is returned. The orchestrator uses this report to avoid treating node registration or a matching filename as inference proof.

Isolated runtime configuration

Install the separate cinespatial core/runner package beside the worker and start its administrator-owned loopback gateway:

cinespatial-runner --config /opt/cinespatial/runner.json

The gateway configuration contains fixed absolute argv arrays, model roots, and allowed ComfyUI input/output roots. It binds to loopback only and rejects arbitrary paths. Each heavyweight model keeps its own Python environment.

Each configured backend receives --request <json> --response <json>, must return a CineSpatial 0.1 response, and runs in its own dependency environment. The request contains an operation-scoped output_directory. Responses must list the exact required artifact roles for that operation. Every file is confined to that directory, checked for non-zero length, and SHA-256 verified. The node then replaces absolute paths with downloadable ComfyUI output references. Missing commands, roles, files, or mismatched hashes fail explicitly; model success is never inferred from registration or a filename.

The gateway distinguishes checkpoint missing/invalid, backend absent, and an operation that is actually ready. README files, notebooks, source files, IDE metadata, and undersized files never count as model checkpoints.

Required artifact roles:

separate_soundtrack:       dialogue, music, effects, separation_provenance
transcribe_align_dialogue: dialogue_alignment
detect_active_speaker:     dialogue_alignment, active_speaker_evidence
classify_audio_events:     effects_evidence
ground_visual_sources:     visual_evidence
query_separate_event:      isolated_event, parent_residual, isolation_report

Installation

Install this repository using ComfyUI Nodes Manager's Git URL installer, then restart or reload the managed worker. Verify node registration through /object_info before submitting workflows.

License

Apache-2.0. Model weights retain their respective upstream licenses.