Composer Reference Guide R2-2026-2.6.9674.23655

Projects

A project is a single .prj file plus the optional script(s) and media that go with it. The file stores every input, operator, target, connector, scene layout, and project-level setting; media files live separately and are referenced by path (see Media management in Getting Started).

The project format is human-readable XML. You can open a .prj in a text editor to inspect or hand-edit, and Composer will accept the result as long as the XML stays valid.

Saving a project

Composer Desktop offers two save commands from the File menu:

  • File → Save (Ctrl+S) — writes the working .prj to its existing path, overwriting in place. The first save of an untitled project falls through to Save As… and prompts for a location.
  • File → Save As… — writes the working .prj to a new path of your choice. The new path becomes the working file; the original is left untouched.

The on-disk format is human-readable XML. Every input, operator, target, connector, scene, layer, and project-level setting is serialised into a single .prj file; project scripts (.js) and media files are not embedded — they're referenced by path. For moving a project together with its media to another host, see Working across hosts below.

The default save location is the Projects subfolder of your Documents area, configurable as Projects directory in Settings → General. Avoid using the literal name default.prj — that file is reset on Composer updates and your work would be overwritten.

Backups Composer keeps around saves

Composer maintains three automatic backup mechanisms so a corrupt save, a lost edit, or a regrettable change can be recovered. The detailed reference is the Backup files page; the short version:

  • <projectname>.bak — a rolling backup written next to the working .prj every ~5 minutes whenever the project has been modified. Controlled by Automatically create project backups in Settings → General (default: on). First port of call if a save goes wrong or a recent edit needs to come back.
  • Autosave history — timestamped snapshots written to Projects/Autosave/<projectname>.<timestamp>.prj at the configured cadence (every 10 minutes by default), retained for 30 days / 30 entries by default. Configured on the Settings → Autosave tab, with an in-app restore UI on the same tab.
  • Dated archive in BackupDirectory\<MachineName>\ — when Settings → General → Backup directory is set to an existing folder different from the projects directory, Composer additionally writes one dated copy per File → Save there, named <YYYY-MM-DD>_<projectname>.prj. Optional and off by default; useful for keeping copies on a separate drive or share that survive the working folder being deleted.

The three mechanisms run independently — leave them all on for layered safety, or trim back via the Settings tabs above.

Working across hosts

Project paths inside a .prj are stored verbatim, which makes a project tied to the host that authored it. Two helpers make moving a project portable:

  • File → Consolidate Media — copies all referenced media into a Media/ folder next to the project and rewrites the project's references to relative paths. After consolidating, the project + Media/ folder is portable to any host.
  • File → Export → Export project and assets… — duplicates the project plus every referenced media file into a target folder. Media lands in a Media/ subfolder; the .prj and any project script sit at the folder root. If Decklink Capture inputs are active, video snapshots export automatically into a Snapshots folder, including any Stillstore captures.

Subfolders inside the Projects directory are not supported; keep .prj files in the root and rely on Media/ for organization.

Transferring a project to a different machine

The recommended approach is:

  1. Run File → Export → Export project and assets… to produce a self-contained folder.
  2. Compress the exported folder into a .zip or .tar.gz.
  3. Move the archive to the destination host and extract.

Both Composer Desktop and Composer Runtime can open and run the resulting project, and it works across platforms — a project authored on Windows Desktop runs as-is on a Linux Runtime host (provided every input / target type the project uses is supported on the destination platform).

Encrypted projects

Composer supports an encrypted project format with the .prjp extension. Both endpoints (the host that exports and the host that imports) must hold matching encryption keys; the import fails on a mismatch. Use File → Export encrypted project and File → Import encrypted project to round-trip a .prjp. This is intended for distributing projects to third parties without exposing the underlying configuration in plaintext.

Managing projects programmatically (DevOps)

Everything above is the interactive Desktop workflow, but projects can also be managed over the network — useful for CI/CD pipelines, fleet orchestration, and headless Composer Runtime deployments where no operator is present. Two API surfaces cover this, and they are complementary:

Runtime API — process lifecycle and project-file management

The Runtime API is the headless control plane. It listens on its own dedicated port (--runtime-api-port) under the /runtime/ prefix, is always reachable regardless of playback state, and is the right surface for orchestration and deployment automation. It is Runtime-only (not exposed by Desktop).

# Deploy and run a new project on a headless Runtime
curl --data-binary @show.prj "http://host:9000/runtime/project/upload?fileName=show.prj"
curl "http://host:9000/runtime/load?fileName=show.prj"
curl "http://host:9000/runtime/status"

Project HTTP API — project content and control

The Project HTTP API runs on the Web API port (HttpApiPort, default 44433) under the /api/ prefix and is available on both Desktop and Runtime. It is oriented toward the content of the currently loaded project rather than the process: /api/project/save, /api/project/getxml, /api/project/load, /api/project/list, /api/project/loadlatestversion, and per-property edits via /api/project/setproperty. The same port also carries everything else for driving a running show — Connectors, component commands, statistics — so it's the surface a control room or front-end talks to.

Automatic version rollout

For deployments where a content team publishes new builds of a live project, Composer's Project Management feature rolls a host forward on its own. Publish a versioned sibling — <projectname>-version-NNNNNN.prj — into the watched folder and, with the feature enabled, Composer resolves to the highest-numbered version when it opens, can watch the folder while running and reload the moment a newer version appears, and falls back to the previous version if a publish step temporarily breaks the chain. The /api/project/loadlatestversion endpoint mentioned above is the API trigger for the same mechanism — wire it into a CI step so the host scans and rolls forward on demand. Enable and tune the behaviour on the Settings → Project Management tab. Note that an automatic reload during a live show momentarily cuts every output, so schedule rollouts accordingly.

Media on the target host

A deployed .prj only records paths to its media, not the media itself. When a project lands on a host whose storage is laid out differently from where it was authored, that host resolves every referenced file through its Assets finder settings — so a successful deployment also depends on the target's search locations (or a host-wide Path Search and Replace rule) lining up with where the media actually sits.

Which one? Reach for the Runtime API to manage the process and the project files around it (deploy, start/stop, swap projects, back up); reach for the Project HTTP API to read or change what's inside the loaded project. The Runtime API overview has a side-by-side comparison table. Both honour an optional API key (apikey header or query parameter).