Skip to content

cli.md

Latest commit

 

History

History
147 lines (98 loc) · 3.44 KB

cli.md

File metadata and controls

147 lines (98 loc) · 3.44 KB
Raw

CLI reference

Main entrypoint:

./bin/vtx.sh

Commands

list-presets

Print all supported root presets with resolved dimensions, default bitrates, and a short description.

./bin/vtx.sh list-presets

validate

Validate one job file and every profile it references.

./bin/vtx.sh validate --job ./jobs/example-multi-video.conf

Validation checks include:

  • job file exists
  • file inputs exist when input_mode=file
  • RTMP inputs are validated as RTMP URLs when input_mode=rtmp
  • referenced profile files exist
  • job mode is supported
  • required profile fields are present after preset resolution
  • preset names or preset file paths are supported
  • dimensions and bitrate rules are valid
  • quality settings are valid
  • job-level cpu_limit is valid when present

The command exits nonzero on failure.

transcode

Run a transcode job.

./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf

By default, jobs use mode=sequential, which runs one FFmpeg command per output profile. Jobs can also use:

  • mode=multi-output for one MP4-oriented FFmpeg command with multiple outputs
  • mode=hls for file-to-HLS packaging
  • mode=live-hls for RTMP ingest to live HLS output

--dry-run

Resolve and validate the job, then print generated ffmpeg commands without executing them.

./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf --dry-run

--verbose

Print resolved config values, preset dimensions, codec mappings, bitrate mappings, CPU thread resolution, and execution details.

./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf --verbose

--log

Write transcode output to a log file. During real transcodes, ffmpeg output is appended to the same log file.

./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf --verbose --log ./logs/transcode.log

The log directory is created automatically if needed. Existing log files are overwritten at the start of the transcode run.

Dry-run logging is useful for reviewing generated commands:

./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf --dry-run --verbose --log ./logs/dry-run.log

--version

Print the CLI version.

./bin/vtx.sh --version

Flags

  • --job <path>: path to a job config file
  • --dry-run: print generated commands only
  • --verbose: print resolved details for debugging and review
  • --log <path>: save generated commands, verbose transcode messages, and ffmpeg output to a file; only supported with transcode
  • --version: print vtx version
  • --help: show usage

Examples

List presets:

./bin/vtx.sh list-presets

Validate before running:

./bin/vtx.sh validate --job ./jobs/example-basic.conf

Generate commands only:

./bin/vtx.sh transcode --job ./jobs/example-custom.conf --dry-run --verbose

Generate one multi-output FFmpeg command:

./bin/vtx.sh transcode --job ./jobs/example-multi-output-mode.conf --dry-run --verbose

Generate a file-to-HLS command and planned master playlist:

./bin/vtx.sh transcode --job ./jobs/example-hls.conf --dry-run --verbose

Generate a live RTMP-to-HLS command:

./bin/vtx.sh transcode --job ./jobs/example-live-hls.conf --dry-run --verbose

Run multiple outputs sequentially and save detailed logs:

./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf --verbose --log ./logs/multi-video.log