BrakeSmith converts selected videos to 10-bit H.265 in MKV with HandBrakeCLI. It scans first, shows exact candidates, and validates each output before publication. The CLI and desktop app use the same processing engine.
BrakeSmith also remembers results. A failed or non-beneficial file does not return in each new candidate list while the file stays unchanged.
| Area | Current state |
|---|---|
| Current release | BrakeSmith 0.6.0 |
| Desktop | macOS ARM64, Windows x64, and Linux x86_64 packages |
| CLI | Python package and standalone executables for macOS, Windows, and Linux |
| Privacy | Local processing only. No account, daemon, telemetry, or upload service. |
| Signing | Public desktop and standalone packages are unsigned. |
BrakeSmith is pre-1.0 software. Review the selected files and destination paths before a large replacement batch.
- Scan local or mounted network libraries recursively.
- Review codec, resolution, size, duration, audio, subtitles, HDR, and warnings.
- Select exact files or export the complete candidate list.
- Use resolution-aware H.265/x265 Main 10 presets for 480p through 4K.
- Keep selected audio and subtitle languages by full name or ISO code.
- Create sealed plans with source identity and destination checks.
- Resume an interrupted plan from its durable journal.
- Validate codec, duration, tracks, chapters, and readability before publication.
- Keep source files by default.
- Replace a source only after a smaller output passes validation.
- Stop a replacement encode when its partial output reaches the source size.
- Classify files as ready, complete, blocked, or stale.
- Remember successful, failed, cancelled, and non-beneficial attempts.
- Exclude unchanged blocked files from later candidate lists.
- Retry or forget selected outcomes when you want another attempt.
- Remove records for moved or deleted files with one prune command.
- Use the same workflow from the Tauri desktop app or CLI.
- Run quick header checks or full frame-decoding health checks.
- Use JSON output, named TOML profiles, and non-interactive options.
- Process mounted SMB and other network shares without cross-filesystem moves.
Download the latest installer from GitHub Releases:
- macOS ARM64: DMG
- Windows x64: MSI or setup executable
- Linux x86_64: AppImage, DEB, or RPM
Desktop packages include the BrakeSmith CLI sidecar. They do not include HandBrakeCLI or FFmpeg tools.
Install with uv:
uv tool install git+https://github.com/me-cedric/BrakeSmith.gitOr install with pipx:
pipx install git+https://github.com/me-cedric/BrakeSmith.gitStandalone CLI executables are also available in GitHub Releases.
BrakeSmith requires:
- HandBrakeCLI for transcoding.
ffprobefrom FFmpeg for inspection and validation.ffmpegfor optional full health checks.
macOS:
brew install handbrake ffmpegWindows:
winget install HandBrake.HandBrake.CLI
winget install Gyan.FFmpegUbuntu or Debian:
sudo apt install handbrake-cli ffmpegCheck the local toolchain:
brakesmith doctorThe HandBrake desktop app does not always install HandBrakeCLI. Install the CLI package if BrakeSmith cannot find it.
Scan the current directory. This command does not change media:
brakesmith scanReview candidates and start an interactive batch:
brakesmith runFor a Tdarr-style replacement batch of five files:
brakesmith run /path/to/library --replace-source --max-files 5BrakeSmith deletes a source only after a smaller output passes validation. It deletes an equal or larger output and records a blocked not-smaller outcome.
For unattended processing:
brakesmith run /path/to/library \
--replace-source \
--max-files 5 \
--format-preset recommended \
--non-interactive \
--unknown-audio keep \
--unknown-subtitles drop \
--yesIn the desktop app:
- Choose a media library.
- Review the Library page and select exact files.
- Build a queue and review its sealed plan.
- Start the plan and monitor Activity.
- Use Outcomes to retry, forget, or prune records.
BrakeSmith stores global state outside media directories. It uses $XDG_STATE_HOME/brakesmith or ~/.local/state/brakesmith on macOS and Linux. Windows uses %LOCALAPPDATA%\brakesmith.
| State | Meaning |
|---|---|
| Ready | The file is a candidate for the current policy. |
| Complete | The file is already suitable or has a matching successful result. |
| Blocked | An unchanged attempt failed or produced no useful size reduction. |
| Stale | The recorded source moved, changed, or no longer exists. |
Inspect state and recent attempts:
brakesmith status /path/to/library
brakesmith history /path/to/library
brakesmith failures listAllow another attempt:
brakesmith retry "/path/to/library/movie.mkv"
brakesmith retry --type not-smallerClean or remove records:
brakesmith failures forget "/path/to/library/movie.mkv"
brakesmith failures prune
brakesmith failures clear --logs-onlyprune removes stale records and orphan diagnostic logs. It does not delete media. A source or policy change also makes the file eligible for evaluation again.
| Command | Purpose |
|---|---|
brakesmith doctor |
Check required tools. |
brakesmith scan [DIRECTORY] |
Inspect supported media. |
brakesmith candidates [DIRECTORY] |
Show or export eligible files. |
brakesmith run [DIRECTORY] |
Review and process a batch. |
brakesmith plan [DIRECTORY] |
Create a sealed plan without encoding. |
brakesmith execute PLAN |
Execute or resume a plan. |
brakesmith status [DIRECTORY] |
Show ready, complete, blocked, and stale files. |
brakesmith history [DIRECTORY] |
Show recent outcomes. |
brakesmith retry FILE... |
Release blocked files for another attempt. |
brakesmith health [DIRECTORY] |
Check media without changing it. |
brakesmith failures |
Inspect and maintain global outcome records. |
Use brakesmith --help or brakesmith COMMAND --help for all options.
Default mode keeps the source. For example, movie.mp4 becomes movie.brakesmith.mkv.
Replacement mode normalizes common codec text. For example, Movie.1080p.x264.mp4 becomes Movie.1080p.x265.mkv.
Safety rules:
- BrakeSmith writes incomplete output to a
.mkv.partfile. - Cancellation and encode failure remove only the incomplete output.
- Existing destinations are never overwritten without validation and an explicit policy.
- BrakeSmith checks source identity before and after each encode.
- A failed source deletion keeps both valid files and records the failure.
--stop-when-largercan stop unhelpful replacement work early.
MKV supports more audio and subtitle formats than MP4. This reduces conversion and information loss.
CLI:
git clone https://github.com/me-cedric/BrakeSmith.git
cd BrakeSmith
uv sync --extra dev
uv run pytest
uv run ruff check .
uv buildDesktop:
cd desktop
npm install
npm run sidecar
npm test
npm run tauri devCI tests Python 3.9 and 3.13 on macOS, Windows, and Linux. It also builds packages and standalone executables. A separate workflow tests and packages the desktop app for all three systems.