srj-video

Render a tscircuit SimpleRouteJson file as a deterministic autorouter video. Select any built-in autorouter Pipeline from 1 through 10 or load a custom JavaScript/TypeScript autorouter module.

Requires Bun and FFmpeg.

git clone https://github.com/0hmX/srj-video.git
cd srj-video
bun install
bun run install:local

This installs a compiled executable at ~/.local/bin/srj-video. Override the destination with SRJ_VIDEO_INSTALL_DIR=/another/bin.

srj-video board.srj.json
srj-video board.srj.json --pipeline 7
srj-video board.srj.json --pipeline 9 --output routing.mp4

Pipeline 9 is the default. The default timing is designed for inspection:

• playback runs at 0.5x;
• the solver is sampled every 10 iterations;
• consecutive identical visuals are deduplicated;
• meaningful Pipeline stage transitions are held for at least 500 ms;
• the completed Pipeline switches to its clean final-output visualization;
• the final frame is held for 2 seconds.

Usage: srj-video [options] [input]

Options:
  -p, --pipeline <number>       Autorouter Pipeline 1-10 (default: "9")
  -a, --autorouter <file>       Custom JS/TS autorouter module
  --autorouter-export <name>    Select a named export from the custom module
  -o, --output <path>           Output .mp4 or .webm path
  --view <view>                 visualize or preview
  --every <iterations>          Capture every N solver iterations
  --speed <multiplier>          Playback speed multiplier
  --stage-hold <milliseconds>   Hold Pipeline stage changes
  --list-pipelines              List selectable Pipelines

Use srj-video --help for all rendering and safety options. FFmpeg is read from PATH; set SRJ_VIDEO_FFMPEG_PATH to select a different executable.

Pass any local JavaScript or TypeScript module with --autorouter instead of selecting a built-in Pipeline:

srj-video board.srj.json --autorouter ./my-autorouter.ts

The module can export a createSolver factory:

import { MyAutorouter } from "./my-router-code"

export const createSolver = (srj) => new MyAutorouter(srj)

A default-exported factory or solver class also works. The returned solver must provide solved, failed, iterations, step(), and visualize(); optional methods such as preview() and visualizeFinalOutput() are used when present. If the module has one callable named export, it is selected automatically. For files with several callable exports, add --autorouter-export SolverName. Module imports resolve normally relative to the custom file. --autorouter and --pipeline cannot be supplied together.

The CLI carries its own Codex skill, so its workflow and defaults are easy to discover without separate documentation:

# Print the skill
srj-video skill

# Install it for Codex
srj-video skill --install

By default this installs to $CODEX_HOME/skills/srj-video/SKILL.md, or ~/.codex/skills/srj-video/SKILL.md when CODEX_HOME is unset. Use --directory <path> to choose another skills directory. An existing modified skill is preserved unless --force is supplied.

Slower stage-by-stage inspection:

srj-video input.srj.json --pipeline 9 --speed 0.25 --stage-hold 1000

Faster overview:

srj-video input.srj.json --pipeline 7 --speed 1 --every 25