Transcoder Tools

transcoder-tools is a Bash toolkit for running common ffmpeg transcoding workflows through small, readable config files instead of long command lines.

The main CLI is vtx, a config-driven video transcoder that turns one input video or live RTMP stream into one or more outputs using friendly concepts such as 720p, h264, aac, video_bitrate, audio_bitrate, and quality.

Why we need it?

ffmpeg is powerful, but routine transcoding jobs are easy to make inconsistent and hard to review when every invocation is hand-written. vtx puts a narrow, opinionated layer on top:

• user-friendly abstraction over raw ffmpeg flags
• config-driven jobs that are easy to save and rerun
• simple first version that supports MP4, file-to-HLS, and live RTMP-to-HLS workflows while staying extensible for later OBS operations work

Quick start

Requirements: Bash 4+ and ffmpeg.

See Installation for ffmpeg setup, executable permissions, and optional PATH configuration.

If you want the fastest path to a working live stream, start with Live streaming quick start. It covers starting a local MediaMTX container, OBS setup, starting vtx, and opening the browser HLS test player.

Not sure which example to start with? See the Workflow guide for a Mermaid decision diagram covering basic, multi-video, multi-output, file-to-HLS, and live RTMP-to-HLS jobs.

Basic usage:

./bin/vtx.sh --version
./bin/vtx.sh list-presets
./bin/vtx.sh validate --job ./jobs/example-multi-video.conf
./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf --dry-run
./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf --verbose --log ./logs/transcode.log
./bin/vtx.sh transcode --job ./jobs/example-hls.conf --dry-run --verbose
./bin/vtx.sh transcode --job ./jobs/example-live-hls.conf --dry-run --verbose

Make the script executable on Linux if needed:

chmod +x ./bin/vtx.sh

Core concepts

vtx uses job files, profile files, friendly preset names, and a small quality model to hide most raw ffmpeg flags from end users.

See Core concepts for how jobs, profiles, presets, and quality values work.

Dry-run mode

Dry-run mode fully resolves and validates the configs, then prints the generated ffmpeg commands without executing them:

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

Use --log <path> with transcode when you want to save generated commands, verbose resolution details, and ffmpeg output for later analysis:

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

Directory overview

transcoder-tools/
  bin/
  lib/
  presets/
  jobs/
  profiles/
  docs/

• bin/vtx.sh: main CLI entrypoint
• lib/: parser, presets, validation, and ffmpeg command builder
• jobs/: sample job configs
• profiles/: sample output profile configs
• presets/: preset reference files
• docs/: user-facing docs

Example commands

./bin/vtx.sh list-presets
./bin/vtx.sh validate --job ./jobs/example-multi-video.conf
./bin/vtx.sh transcode --job ./jobs/example-multi-video.conf
./bin/vtx.sh transcode --job ./jobs/example-custom.conf --dry-run --verbose
./bin/vtx.sh transcode --job ./jobs/example-hls.conf --dry-run --verbose
./bin/vtx.sh transcode --job ./jobs/example-live-hls.conf --dry-run --verbose

Documentation

• Installation: ffmpeg setup and vtx shell configuration
• Live streaming quick start: fastest path for MediaMTX ingest, OBS publishing, live HLS transcoding, and browser playback testing
• CLI reference: commands, flags, and examples
• Workflow guide: decision diagram for choosing basic, multi-video, multi-output, file-to-HLS, or live RTMP-to-HLS jobs
• Core concepts: how jobs, profiles, presets, and quality values work
• Config format: required fields, optional fields, and override rules
• HLS mode: file-to-HLS and live RTMP-to-HLS jobs, playlists, segments, master playlists, and the browser test player
• Preset details: preset dimensions, width/height overrides, and codec mappings
• References: external FFmpeg, HLS, CORS, and player resources
• Changelog: version-specific release notes