Headless

Headless and Terminal Usage

BPM can be used from the terminal for validation, audio inspection, export, project utilities, and hardware diagnostics. The CLI is mode-based: instead of a large flag-only interface, you start by choosing a command such as export, verify, or inspect-audio.

The examples below use bpm. On Windows, that usually means bpm.exe or ./bpm.exe, depending on how the binary is installed.

Basic Command Shape

Running bpm without arguments starts the GUI.

bpm

For terminal work, use this structure:

bpm <mode> [options]

Examples:

bpm verify --project projects/show.project.jsonc
bpm inspect-audio --audio audio/track.wav
bpm export --project projects/show.project.jsonc --out renders/show.h265

What Works Well in the Terminal

BPM is especially useful in the terminal for these tasks:

• validating project files before preview or export
• exporting renders in scripted or repeatable workflows
• inspecting WAV audio and generating analysis artifacts
• checking hardware surface export compatibility

Not every CLI mode is fully headless. preview, for example, is started from the terminal but opens a preview window.

Verify Projects and Files

Use verify when you want a fast correctness check before spending time on rendering.

Validate a full project:

bpm verify --project projects/show.project.jsonc

Validate a single document:

bpm verify --file scenes/show.manifest.jsonc

You can also verify a scene shader directly:

bpm verify --file scenes/show.wgsl

When the input is a WGSL scene shader, BPM verifies the shader together with its sidecar manifest. This makes verify a good first step in CI, local QA, or batch authoring workflows.

Inspect Audio from the Terminal

Use inspect-audio to analyze a WAV file and generate reusable analysis outputs.

bpm inspect-audio --audio audio/track.wav

inspect-audio currently requires a .wav file. After the run, BPM writes these files beside the source audio:

• track.analysis.json
• track.analysis.svg
• track.analysis.schema.json

This is useful when you want to inspect tempo, structure, buckets, and derived series outside the GUI, or when another tool in your pipeline consumes BPM's analysis output.

Export from the Terminal

export is the main production command for terminal rendering.

Export from a project:

bpm export --project projects/show.project.jsonc --out renders/show.h265 --width 1920 --height 1080 --fps 60

Export directly from a shader:

bpm export --shader scenes/look.wgsl --out renders/look.h264 --width 1280 --height 720 --fps 30 --seconds 12

Important rules:

• use either --project or --shader, never both
• supported production codecs are h264 and h265
• supported export backends are hardware-oriented backends such as surface and nvidia
• quality profiles are ultra-fast, fast, and production

Example with explicit backend and quality:

bpm export --project projects/show.project.jsonc --backend surface --quality production --codec h265 --out renders/show.h265

About --headless

You can add --headless to an export command when you want a quieter batch-style run:

bpm export --project projects/show.project.jsonc --out renders/show.h265 --headless

In practice, this is useful for automation, background jobs, and tool-driven execution where you do not want live progress output in the terminal.

Audio and MP4 Remux

If the exported project includes audio and ffmpeg is available in PATH, BPM can remux the encoded video stream into an MP4 after rendering. That makes terminal export suitable for pipelines that want a raw encoded stream during rendering and a delivery-friendly container at the end.

Preview from the Terminal

Use preview when you want to launch a shader preview quickly from the command line:

bpm preview --shader scenes/look.wgsl --width 1920 --height 1080

This is terminal-launched, but it is not a fully headless mode. BPM opens the preview runtime window. Also note that preview accepts --shader, not --project.

Surface Export Diagnostics

Use probe-surface when you need to inspect hardware-path compatibility for H.264 or H.265 surface export.

bpm probe-surface --codec h265 --out diagnostics/surface-probe-h265.txt

BPM writes a text report that records the attempted surface path combinations and their child-process results. This is primarily useful for debugging platform-specific export behavior.

Practical Terminal Workflow

A solid terminal-first workflow often looks like this:

1. verify the project or shader 2. inspect audio if the project depends on a new WAV source 3. export with explicit resolution, FPS, backend, and output path 4. use --headless only when you want minimal terminal chatter or automation-friendly behavior

Example:

bpm verify --project projects/show.project.jsonc
bpm inspect-audio --audio audio/track.wav
bpm export --project projects/show.project.jsonc --backend surface --quality production --codec h265 --out renders/show.h265

Summary

BPM's terminal usage is best understood as a production and validation interface. Use it when you want repeatable exports, fast verification, offline audio inspection, and pipeline-friendly execution. Use the GUI when you need interactive editing, and use preview when you want a command-line launch point for shader iteration with a live window.