🛠️ toolkitrs
WIP - Current version is a prototype
A unified FFmpeg workflow CLI and interactive TUI for common media tasks.
A fast, single-binary replacement for mixed PowerShell/Go media scripts. Built with Rust, it provides safe, cross-platform media conversion workflows with progress feedback, interactive batch processing, a beautiful Terminal UI, and rich CLI help.
✨ Features
- Interactive TUI: A beautiful, keyboard-driven terminal UI for browsing files and running workflows with live progress
- Unified CLI: One binary for all media workflows (
ts2mp4,mkv2mp3,mp32mp4,vidwrap) - GitHub Contributions Exporter: Fetch and format a user's GitHub commits within a date range into a clean text file
(
gh-contrib) - Batch Processing: Automatic directory scanning with skip/overwrite logic
- Interactive Sibling Discovery: If you provide one file and related files exist nearby, toolkitrs can ask whether to process them too
- Error Policies: Choose whether to stop, skip, or prompt after each file during batch processing
- Safe Defaults: Prevents accidental data loss with explicit
--forceflags - Rich UX: Spinners, progress lines, colored output, and interactive prompts
- CI/CD Friendly: Non-interactive mode avoids hanging and chooses safe defaults
- Testable Core: Dependency-injected FFmpeg runner for deterministic testing
- Zero Runtime Dependencies: Single static binary, no PowerShell or Go required
📦 Installation
Quick Install (Linux / macOS)
|
To install a specific version:
|
Quick Install (Windows)
Open PowerShell and run:
irm https://raw.githubusercontent.com/seyallius/toolkitrs/main/install.ps1 | iex
To install a specific version:
iex "& { $(irm https://raw.githubusercontent.com/seyallius/toolkitrs/main/install.ps1) } -Version v0.1.8"
Pre-built Binary (via Cargo Binstall)
# Install cargo-binstall first if you haven't
# Then install toolkitrs instantly
From crates.io (Compile from source)
From Source
Prerequisites
- FFmpeg must be installed and available in your PATH (for media workflows)
- Optional: Use
--ffmpeg-path <PATH>to specify a custom FFmpeg location
🚀 Usage
You can use toolkitrs in two ways: via the Interactive TUI (default) or via CLI subcommands for scripting and
automation.
# Launch the interactive TUI (just run it without arguments!)
# Or run a specific CLI workflow
Run help for CLI commands:
🖥️ Interactive Terminal UI (TUI)
If you prefer a visual, keyboard-driven experience, simply run toolkitrs without any arguments to launch the
interactive Terminal UI.
The TUI provides:
- Workflow Selection: Choose between
ts2mp4,mkv2mp3,mp32mp4,vidwrap, andgh-contrib. - Visual File Browser: Navigate your directories and select files using vim-style bindings (
h/j/k/l). - Live Execution: Watch real-time
ffmpeglogs and per-file progress gauges as your batch processes. - Smart Inputs: Context-aware inputs (e.g. type
todayoryesterdayfor GitHub date ranges).
Note: The TUI requires an interactive terminal. If run in a CI/CD pipeline or piped to a file, it will safely exit and suggest using the CLI subcommands instead.
🔁 Interactive Batch Processing (CLI)
For supported CLI commands, if you provide a single input file and toolkitrs finds compatible sibling files in the same directory, it can ask what to do.
Example:
If the directory contains more .ts files, toolkitrs prompts:
Found 4 TS files in /videos
How would you like to proceed?
1. Process the input only
2. Process the whole path (return on error, report at the end)
3. Process the whole path (skip on error, report at the end)
4. Process the whole path (prompt user on each new video)
Choice [4]:
The default is option 4: process the whole path, prompting after each file.
When prompting after each file, toolkitrs asks:
Continue?
1. yes
2. no
3. yes to all
Choice [1]:
Choosing yes to all continues with all remaining files without prompting again.
Explicit Batch Mode
You can also explicitly process a whole directory:
Explicit batch commands support an error policy:
| Policy | Behavior |
|---|---|
stop |
Stop on first error and print a report |
skip |
Skip failed files and continue, printing a report at the end |
prompt |
Ask after each processed file whether to continue |
If --on-error is omitted:
- Interactive terminals default to
prompt - Non-interactive terminals default to
skip
📌 Batch Arguments
All batch commands (ts2mp4, mkv2mp3, mp32mp4) share these options:
| Flag | Default | Description |
|---|---|---|
--output-dir <DIR> |
./out |
Directory for converted files (created automatically) |
--force |
false |
Overwrite existing output files instead of skipping |
--batch |
false |
Process all matching files in the current directory |
--input-dir <DIR> |
None | Process all matching files in the given directory |
--on-error <POLICY> |
None | Batch error policy: stop, skip, or prompt |
🧰 Commands
ts2mp4 — Remux TS to MP4
Convert Transport Stream files to MP4 via stream copy (no re-encoding).
# Convert all .ts files in current directory
# Convert a specific file
# Convert specific files to custom output directory
# Explicitly batch-process a directory
# Overwrite existing outputs
mkv2mp3 — Extract Audio from MKV
Convert MKV files to MP3 with optional cover art extracted from video frames.
# Default: 320kbps, 600px cover art
# Custom bitrate and cover size
# Explicitly batch-process a directory
# Force overwrite existing MP3s
mp32mp4 — Create Video from MP3
Convert MP3 files to MP4 videos using embedded cover art as the video track.
# Use embedded cover art (black video fallback if missing)
# Skip files without embedded cover art
# Custom audio bitrate
# Explicitly batch-process a directory
vidwrap — Wrap Video with Thumbnail
Combine a video with a companion image to create a new video with an embedded thumbnail.
# Requires a same-basename image (e.g., video.mp4 + video.jpg)
# Batch-process all MP4 videos in the current directory
# Batch-process all MP4 videos in a specific directory
# Batch-process and skip errors
Supported companion image formats, in priority order:
.png, .jpg, .jpeg, .bmp, .gif, .webp
Notes:
- Single-file mode preserves the interactive post-processing prompt.
- Batch mode keeps original and source image files by default to avoid destructive prompts.
- Previously generated
*_with_image.mp4files are excluded from batch discovery.
gh-contrib — Export GitHub Contributions
Fetches GitHub commits for a specified user within a date range, filters out merge and revert commits, and exports them to a beautifully formatted text file. Optionally includes repository READMEs.
Note: Requires a
GITHUB_TOKENenvironment variable withrepoandread:userscopes. You can generate one at github.com/settings/tokens.
# Export commits for a specific date range
# Skip fetching repository READMEs to speed up the process
# Specify a custom output file path
TUI Bonus: When using gh-contrib inside the Interactive TUI, the date inputs support natural language! You can
simply type today or yesterday instead of manually typing out the YYYY-MM-DD format.
🔧 Development
# Build debug binary
# Run tests
# Clippy linting
# Format check