Configuration Reference

Tuireel uses JSONC (JSON with Comments) configuration files, typically named .tuireel.jsonc. Run tuireel init to scaffold a starter config with JSON Schema support.

General

string

Path or URL to the JSON Schema file for editor autocompletion. Generated automatically by tuireel init.

"mp4" | "webm" | "gif"

default:"mp4"

Output video format.

string

default:"output.mp4"

Output file path for the recording.

"readable-1080p" | "social-quick-share" | "high-motion-demo"

Named timing + readability bundle for common delivery goals. This is the normal authoring path: pick a delivery target first, then override fps, captureFps, or sizing fields only when needed.

integer

default:30

Final output cadence for the rendered video. Must be a positive integer.

integer

Raw capture cadence for terminal state sampling before Tuireel renders the final output at fps.

integer

default:80

Number of terminal columns. Must be a positive integer.

integer

default:24

Number of terminal rows. Must be a positive integer.

Presentation

"polished" | "minimal" | "demo" | "silent"

Apply a built-in presentation preset. Presets configure theme, sound, cursor, and HUD defaults in one line. They stay visual-only, so you can stack them with deliveryProfile. See Presets for details.

Preset	Theme	Sound	Cursor	HUD
`polished`	Catppuccin	Click + Key	Visible	Visible
`minimal`	Tokyo Night	None	Visible	Hidden
`demo`	Dracula	Click + Key	Visible	Visible
`silent`	Default	None	Hidden	Hidden

string | ThemeConfig

Terminal color theme. Pass a built-in theme name as a string, or an inline theme object.

// Built-in theme by name
"theme": "catppuccin"

// Inline theme object
"theme": {
  "background": "#1E1E2E",
  "foreground": "#CDD6F4",
  "colors": {
    "black": "#45475A",
    "red": "#F38BA8",
    "green": "#A6E3A1",
    "yellow": "#F9E2AF",
    "blue": "#89B4FA",
    "magenta": "#F5C2E7",
    "cyan": "#94E2D5",
    "white": "#BAC2DE",
    "brightBlack": "#585B70",
    "brightRed": "#F38BA8",
    "brightGreen": "#A6E3A1",
    "brightYellow": "#F9E2AF",
    "brightBlue": "#89B4FA",
    "brightMagenta": "#F5C2E7",
    "brightCyan": "#94E2D5",
    "brightWhite": "#A6ADC8"
  }
}

See Themes for the full ThemeConfig schema and available built-in themes.

object

Cursor overlay settings.

Show cursor properties

boolean

Whether to render the cursor overlay on the recording.

object

Heads-up display (keystroke overlay) settings.

Show hud properties

boolean

Whether to render the keystroke HUD overlay on the recording.

Sound

object

Sound configuration for the recording.

Show sound properties

object

Sound effect mappings for keypresses.

Show effects properties

1 | 2 | 3 | 4 | string

Sound effect for mouse clicks. Use a number (1-4) for built-in variants, or a file path for a custom sound.

1 | 2 | 3 | 4 | string

Sound effect for key presses. Use a number (1-4) for built-in variants, or a file path for a custom sound.

string

Path to a background audio track. Resolved relative to the config file.

number

Volume for the background track. Range: 0 (silent) to 1 (full volume).

number

Volume for sound effects. Range: 0 (silent) to 1 (full volume).

Behavior

number

Default timeout in milliseconds for wait steps that don’t specify their own timeout. Must be a positive number.

Step[]

required

Array of step objects defining the recording script. Must contain at least one step. See Steps Reference for all step types.

Multi-Video Configuration

Tuireel also supports a multi-video config format for recording multiple videos from a single config file:

{
  "defaults": {
    "deliveryProfile": "readable-1080p",
    "captureFps": 12,
    "fps": 30,
    "cols": 80,
    "rows": 24,
    "preset": "polished",
  },
  "videos": [
    {
      "name": "install",
      "output": "install.mp4",
      "steps": [
        { "type": "launch", "command": "bash" },
        { "type": "type", "text": "npm install mypackage" },
        { "type": "press", "key": "Enter" },
        { "type": "pause", "duration": 3 },
      ],
    },
    {
      "name": "usage",
      "output": "usage.mp4",
      "steps": [
        { "type": "launch", "command": "bash" },
        { "type": "type", "text": "mypackage --help" },
        { "type": "press", "key": "Enter" },
        { "type": "pause", "duration": 2 },
      ],
    },
  ],
}

The defaults object accepts all config fields (except steps and output) and is merged with each video definition. Each video in the videos array requires name, output, and steps.

Complete Example

A full single-video config using all available options:

{
  "$schema": "file:///home/user/.tuireel/schema.json",
  "deliveryProfile": "readable-1080p",
  "preset": "polished",
  "format": "mp4",
  "output": "demo.mp4",
  "captureFps": 12,
  "fps": 30,
  "cols": 100,
  "rows": 30,
  "theme": "catppuccin",
  "cursor": { "visible": true },
  "hud": { "visible": true },
  "sound": {
    "effects": { "click": 1, "key": 2 },
    "track": "./background.mp3",
    "trackVolume": 0.2,
    "effectsVolume": 0.6,
  },
  "defaultWaitTimeout": 10000,
  "steps": [
    { "type": "launch", "command": "bash" },
    { "type": "type", "text": "echo 'Hello, world!'" },
    { "type": "press", "key": "Enter" },
    { "type": "wait", "pattern": "Hello, world!" },
    { "type": "pause", "duration": 2000 },
  ],
}

Get Started

Configuration

Features

Configuration Reference

General

Presentation

Sound

Behavior

Multi-Video Configuration

Complete Example

​General

​Presentation

​Sound

​Behavior

​Multi-Video Configuration

​Complete Example

General

Presentation

Sound

Behavior

Multi-Video Configuration

Complete Example