Click Builder

Build click-track videos from a YAML song definition and a source lyric video.

click-builder parses a project file, generates beat-accurate click and cue audio, then muxes that audio back into the source video with FFmpeg.

What It Does

• Parse a YAML project file into a validated AST
• Generate a beat-accurate timeline from tempo, meter, and structure
• Render click and cue stems into a mixed WAV file
• Mux the generated audio back into the source video
• Support self-contained project files with input and output video paths in YAML

Quick Start

Prerequisites

You need:

• Node.js 20 or newer
• ffmpeg and ffprobe available on your PATH

Install Node.js

If you do not already have Node.js installed, install the current LTS release.

Windows

winget install OpenJS.NodeJS.LTS

macOS

brew install node

Ubuntu / Debian

sudo apt update
sudo apt install nodejs npm

Install FFmpeg

Windows

winget install Gyan.FFmpeg

macOS

brew install ffmpeg

Ubuntu / Debian

sudo apt update
sudo apt install ffmpeg

Verify Your Install

node --version
npm --version
ffmpeg -version
ffprobe -version

If all four commands succeed, you are ready to run click-builder.

Run Without Installing Globally

The easiest way to try it is with npx:

npx @popscode/click-builder ./project.yaml

If your YAML includes input_video_path and output_video_path, that is enough.

Install Globally

If you use click-builder regularly, install it globally:

npm install -g @popscode/click-builder

Then run:

click-builder ./project.yaml

Run From This Repository

If you are using the source checkout directly:

npm install
npm run build
npm install -g .
click-builder ./project.yaml

Example Project File

The recommended format is a self-contained YAML project file with video paths and explicit stems.

name: "My Song"
tempo: 137
time_signature: 4/4
video_downbeat_offset_ms: 400
click_profile: assets/click-profiles/PraiseCharts.config.yml

input_video_path: ./My Song - Lyric Video - Instrumental.mp4
output_video_path: ./My Song - Lyric Video - Click.mp4

count_in_enabled: true
section_markers_enabled: true
downbeat_emphasis_enabled: true
mid_beat_filler_enabled: false

stems:
  - id: instrumental_full
    source:
      type: source-video-audio
    routing:
      left_percent: 100
      right_percent: 100

  - id: click
    source:
      type: generated
      generated_stem: click
    routing:
      left_percent: 100
      right_percent: 100

  - id: cue
    source:
      type: generated
      generated_stem: cue
    routing:
      left_percent: 100
      right_percent: 100

structure:
  - section: "Click"
    measures: 2
  - section: "Intro"
    measures: 2
  - section: "Verse 1"
    measures: 8
  - section: "Chorus"
    measures: 8
  - section: "Outro"
    measures: 4

YAML Configuration Reference

This section documents every supported YAML attribute and how it behaves.

Top-Level Fields

Field	Type	Required	Default	Notes
name	string	yes	none	Project name for metadata/logging.
tempo	number	yes	none	Base BPM used by sections unless overridden per section.
time_signature	string (X/Y)	yes	none	Base meter used by sections unless overridden per section.
video_downbeat_offset_ms	number >= 0	yes	none	Downbeat offset in milliseconds.
click_profile	string path	no	assets/click-profiles/PraiseCharts.config.yml	Click/cue asset mapping profile.
input_video_path	string path	no**	none	Source video path; can be provided via CLI arg instead.
output_video_path	string path	no**	none	Output video path; can be provided via CLI arg instead.
count_in_enabled	boolean	no	true	Base default for section count-in behavior.
divisions	positive integer	no	none	Pulses per measure override; applies to any time signature.
section_markers_enabled	boolean	no	true	Base default for section cue announcements.
downbeat_emphasis_enabled	boolean	no	true	Emits click.downbeat on beat/pulse 1 when enabled.
mid_beat_filler_enabled	boolean	no	false	Inserts click.between halfway between pulses.
stems	array	no	none	Stem routing configuration (see Stem Fields).
structure	array<section>	yes	none	Ordered song/click sections (see Section Fields).

** Runtime requires paths from either CLI args or YAML fields.

Stem Fields (stems[])

Each stem entry supports:

Field	Type	Required	Default	Notes
id	string	yes	none	Identifier for your project organization.
source.type	generated | source-video-audio	yes	none	Stem source selector.
source.generated_stem	click | cue	when source.type=generated	none	Selects generated stem type.
routing.left_percent	0..100 integer	no	100	Left channel gain percent.
routing.right_percent	0..100 integer	no	100	Right channel gain percent.

Notes:

• Routing is currently applied to generated stems (click, cue).
• source-video-audio is accepted by schema and parser for forward compatibility, but generated mix behavior currently centers on generated stems.

Section Fields (structure[])

Each structure entry supports:

Field	Type	Required	Default	Notes
section	string	yes	none	Section name used for cue lookup normalization.
measures	positive integer	yes	none	Number of measures in this section.
final_measure_beats	positive integer	no	full measure	Limits click count in the final measure (clamped to meter top).
time_signature	string (X/Y)	no	inherited from top-level time_signature	Per-section meter override.
tempo	number	no	inherited from top-level tempo	Per-section BPM override.
section_designator	song | click	no	auto (click if section normalizes to click, else song)	Affects some cue behaviors.
count_in_enabled	boolean	no	inherited from top-level count_in_enabled (true)	Enables intro lead-in cue counts behavior.
divisions	positive integer	no	inherited from top-level divisions	Per-section pulse override for any meter.
section_markers_enabled	boolean	no	inherited, except auto-false for section_designator=click	Emits cue.section:<name>.
downbeat_emphasis_enabled	boolean	no	inherited from top-level (true)	Downbeat vs upbeat click behavior.
mid_beat_filler_enabled	boolean	no	inherited from top-level (false)	Inserts midpoint clicks in each pulse interval.
count_cues_enabled	boolean	no	false	Emits cue.count:2..N during first measure.
section_cue_override	string	no	none	Replaces section name used for cue asset lookup.

Inheritance and Override Rules

• Top-level tempo and time_signature define the base.
• Section-level tempo and time_signature override only that section.
• Boolean behavior flags inherit from top-level defaults unless overridden on the section.
• section_designator defaults to:
  • click when normalized section name is click
  • song for all other section names

Section Name Normalization for Cue Lookup

Section cue keys are normalized before lookup:

• Lowercased
• Non-alphanumeric characters replaced with _

Examples:

• Verse 1 -> verse_1
• Post-Chorus -> post_chorus
• Refrain 2 -> refrain_2

The renderer then resolves cue.section:<normalized_name> through the click profile mapping.

Timing and Pulse Details

• Beat duration is calculated from BPM and denominator:
  • quarter note duration: 60000 / bpm
  • beat duration: quarter_note_duration * (4 / denominator)
• Pulses per measure:
  • default: numerator (X in X/Y)
  • if divisions is set globally or on a section: that integer value is used
  • examples:
    • 4/4 with divisions: 2 -> two clicks at beats 1 and 3
    • 6/8 with divisions: 2 -> two clicks at beats 1 and 4
    • 12/8 with divisions: 4 -> four clicks at beats 1, 4, 7, and 10
• final_measure_beats applies only to the last measure in a section:
  • clamped between 1 and full beats-per-measure
  • pulse count scales proportionally and is rounded to at least 1

Cue Emission Behavior

• Section markers (cue.section:*):
  • emitted when section_markers_enabled is true
  • timing is one measure before the section downbeat when possible
  • first section cue is emitted at timeline start
• Auto intro count cues:
  • apply when section is intro-like (intro, intro_1, etc.), count_in_enabled=true, and section is not designator click
  • for non-first intro sections, count cues are emitted during the preceding measure
  • for first intro section, count cues can emit on the first measure pulses
• Explicit count cues (count_cues_enabled=true):
  • emits cue.count:2..N on the first measure of the section

Path Resolution and CLI Precedence

Input/output video paths are resolved in this precedence order:

1. CLI args: click-builder <config> [input-video] [output-video]
2. YAML: input_video_path and output_video_path
3. error if unresolved

Advanced Example (Section Overrides)

name: "Advanced Song"
tempo: 120
time_signature: 4/4
video_downbeat_offset_ms: 250

count_in_enabled: true
section_markers_enabled: true
divisions: 2

structure:
  - section: "Click"
    measures: 2
    section_designator: click
    section_markers_enabled: false

  - section: "Intro"
    measures: 2
    time_signature: 6/8
    divisions: 2

  - section: "Verse 1"
    measures: 8
    tempo: 124

  - section: "Tag"
    measures: 2
    final_measure_beats: 2
    section_cue_override: "Tag"
    count_cues_enabled: true

CLI Usage

click-builder [--allow-reencode] <config.yaml> [input-video] [output-video]

Path precedence is:

1. CLI arguments
2. YAML input_video_path and output_video_path
3. error if neither provides the required path

In most cases, the recommended approach is to keep paths in the YAML so the project file is self-contained.

Troubleshooting

ffmpeg not found

Install FFmpeg and make sure ffmpeg is on your PATH.

ffprobe not found

Install FFmpeg and make sure ffprobe is on your PATH.

Node version too old

Upgrade to Node.js 20 or newer.

Command not found after global install

Make sure npm global binaries are on your shell PATH, or run with npx instead.

Optional: Use fnm

If you prefer a Node version manager, fnm is a good lightweight option.

Windows

winget install Schniz.fnm
fnm install --lts
fnm use lts-latest

macOS

brew install fnm
fnm install --lts
fnm use lts-latest

Then verify:

node --version
npm --version

Development

Install dependencies:

npm install

Build:

npm run build

Run the main test suites:

npm run test
npm run test:coverage
npm run test:bdd

Generate deterministic real-mux fixtures:

npm run fixtures:video-sync

Unit tests live next to the source they exercise as *.test.ts files.

BDD tests live under tests/bdd/ as .feature files with matching step definitions.

Project Structure

• docs/ - product and planning documentation
• openspec/ - proposal, design, specs, and archived changes
• src/ - CLI pipeline source code
• assets/ - click profiles and runtime assets
• tests/ - BDD coverage and fixtures

Notes

• Internal timing values are stored as floating-point millisecond values.
• The generated click stem is the timing foundation for leader-aware muxing.
• Existing YAML files without stems still work, but new project files should prefer the explicit stem-routing format.

Documentation

• PRD
• Release Process