Vid Cleaner

PyPI - Python Version

Tools to transcode, inspect and convert videos. This package provides convenience wrappers around ffmpeg and ffprobe to make it easier to work with video files. The functionality is highly customized to my personal workflows and needs. I am sharing it in case it is useful to others.

Features

Remove commentary tracks and subtitles
Remove unwanted audio and subtitle tracks
Determine a video's original language from its filename, its container metadata, or the TMDb, Radarr, and Sonarr APIs
Convert to H.265 or VP9
Convert 4k to 1080p
Downmix any surround layout (5.1, 7.1, and Atmos above 7.1) into a stereo track when one is missing, or recreate an existing stereo track with --force, using a dialogue-forward filter that keeps speech clear
Remove unwanted audio and subtitle tracks, optionally keeping the original language audio track
Create clips from a video file
Search for video files under a directory that match specific criteria

Install

Before installing vid-cleaner, the following dependencies must be installed:

ffmpeg
ffprobe
python 3.11+

To install vid-cleaner, run:

# With uv
uv tool install vid-cleaner

# With pip
python -m pip install --user vid-cleaner

Usage

Run vidcleaner --help to see the available commands and options.

Configuration

Defaults for vid-cleaner are set in the configuration file located at ~/.config/vid-cleaner/config.toml. When vid-cleaner is run, it will create this file if it does not exist. All options can be overridden on the command line.

If you've updated your user config file, the flags for the cli will work in reverse order. For example, if you've set downmix_stereo = true in your user config file, the flag --downmix will actually disable downmixing.

Important: Vid-cleaner makes decisions about which audio and subtitle tracks to keep based on the original language of the video. To find that language, it looks for an IMDb or TMDB id in three places, stopping at the first one that resolves:

The filename, matching either a bare tt0245712 or the {tmdb-55} naming convention.
The container's own IMDB and TMDB metadata tags, as written by tools like mkvmerge.
A Radarr or Sonarr title search.

The first two need only tmdb_api_key in the configuration file. Set the radarr_ and sonarr_ keys if you want the title search as a fallback.

# Languages to keep (list of ISO 639-1 codes)
langs_to_keep = ["en"]

# Keep subtitles matching the local language(s) even when the audio is not in the local language(s)
keep_local_subtitles = false

# Keep commentary audio
keep_commentary = false

# Force dropping local subtitles even if audio is not default language
drop_local_subs = false

# Keep all subtitles
keep_all_subtitles = false

# Drop original language audio if not specified in langs_to_keep
drop_original_audio = false

# Always create a stereo track
downmix_stereo = false

# External services used to determine the original language of a movie or TV show
radarr_api_key = ""
radarr_url     = ""
sonarr_api_key = ""
sonarr_url     = ""
tmdb_api_key   = ""

File Locations

Vid-cleaner uses the XDG specification for determining the locations of configuration files, logs, and caches.

Configuration file: ~/.config/vid-cleaner/config.toml
Cache: ~/.cache/vid-cleaner

Contributing

See CONTRIBUTING.md for more information.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vid_cleaner-0.10.2.tar.gz (166.2 kB view details)

Uploaded Jul 23, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

vid_cleaner-0.10.2-py3-none-any.whl (65.2 kB view details)

Uploaded Jul 23, 2026 Python 3

File details

Details for the file vid_cleaner-0.10.2.tar.gz.

File metadata

Download URL: vid_cleaner-0.10.2.tar.gz
Upload date: Jul 23, 2026
Size: 166.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.14

File hashes

Hashes for vid_cleaner-0.10.2.tar.gz
Algorithm	Hash digest
SHA256	`e1ebddec422f94af56b21ec3c4e1a29ce388ce2dc7c43116b523027419acadce`
MD5	`d2f4d972458096ced5481bba7e4d3c22`
BLAKE2b-256	`30cbcb4623e396ec51867fd9a232958334f625a6402a27109590e878088204b0`

See more details on using hashes here.

File details

Details for the file vid_cleaner-0.10.2-py3-none-any.whl.

File metadata

Download URL: vid_cleaner-0.10.2-py3-none-any.whl
Upload date: Jul 23, 2026
Size: 65.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.14

File hashes

Hashes for vid_cleaner-0.10.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`97ea3f731974588825bbff7d7833bed45f4f9adf106c6d769f15649aede4176d`
MD5	`0ae3be6ac65e8c362f0b67b0c097d8e0`
BLAKE2b-256	`51429862ddedf900988afa18308358665708dc552773d085ced7097798c69783`