cleanvid mutes profanity in video files by using subtitle-based detection and audio stream editing. It supports fast audio muting, subtitle cleaning, and hardware-accelerated video encoding (GPU) for maximum performance.
- Mute audio segments containing profanity (based on subtitles and a customizable word list)
- Create clean subtitle files with censored phrases
- Optionally embed or hardcode subtitles
- Generate EDL and PlexAutoSkip JSON files for external players
- Fast processing: copy video, re-encode audio only, or fully re-encode video
- NEW: Automatic GPU acceleration (
--gpu) for NVIDIA, Intel, or AMD
- Python 3.7 or newer
- FFmpeg (v6 or newer recommended)
- Install via your OS package manager (e.g.,
sudo apt install ffmpeg) or from ffmpeg.org
- Install via your OS package manager (e.g.,
python3 -m venv .venv
source .venv/bin/activategit clone https://github.com/giveen/cleanvid.git
cd cleanvid
pip install -e .pip install babelfish pysrt subliminalcleanvid --helpcleanvid -i input.mp4 -s subs.srt -o output.mp4 --re-encode-audiocleanvid -i input.mp4 -o output.mp4 -a "-c:a aac -b:a 224k -ar 48000" -v "-c:v copy"cleanvid -i input.mp4 -o output.mp4 --re-encode-video -v "-c:v libx264 -preset fast -crf 22 -threads 8" -a "-c:a aac -b:a 224k -ar 48000"cleanvid -i input.mp4 -o output.mp4 --re-encode-video --gpuThis will auto-detect your GPU and select the best encoder (e.g., h264_nvenc for NVIDIA).
cleanvid --helpNote: The GUI is experimental and is in active development. Use these instructions to run the development GUI locally.
- Create and activate the virtual environment (if you haven't already):
python3 -m venv .venv
source .venv/bin/activate- Install the package in editable mode (this will also install GUI/runtime dependencies declared in the project):
pip install -e .- Launch the GUI (from the repository root):
python src/cleanvid/cleanvid_gui.pyIf you encounter missing dependency errors, run pip install -e . again or install the missing package directly. The GUI is intended for development and testing; usage instructions and features may change.
-i,--inputInput video file (required)-o,--outputOutput video file-s,--subsSubtitle file (.srt)-w,--swearsProfanity list file-v,--video-paramsCustom ffmpeg video parameters-a,--audio-paramsCustom ffmpeg audio parameters--re-encode-videoForce video re-encoding--re-encode-audioForce audio re-encoding--gpuEnable GPU acceleration (auto-detects and selects best encoder)--embed-subsEmbed subtitles in output--burnHardcode subtitles (implies re-encode)--subs-onlyOnly operate on subtitles--edlGenerate EDL file--jsonGenerate JSON file for muted segments
- How do I enable GPU?
Add
--gputo your command. cleanvid will auto-detect NVIDIA, Intel, or AMD and select the best encoder. - What if I have multiple GPUs?
cleanvid uses the first detected GPU. For advanced control, manually set
-v "-c:v h264_nvenc"or similar. - What if no GPU is found?
cleanvid falls back to CPU encoding (
libx264).
Build the image:
./docker/build_docker.shRun in Docker:
sudo docker run --rm \
-v "$PWD:/videos" \
--entrypoint cleanvid \
oci.guero.org/cleanvid:latest \
-i /videos/input.mp4 --re-encode-video -o /videos/output.mp4- ffmpeg not found: Install ffmpeg and ensure it is in your PATH.
- Missing Python packages: Run
python3 -m pip install -U -r requirements.txt. - GPU not detected: Ensure drivers and runtime libraries are installed. Use
nvidia-smi(NVIDIA),vainfo(Intel/AMD) to verify.
BSD 3-Clause License — see LICENSE
Pull requests are welcome! If you’d like to help improve cleanvid, feel free to fork and submit changes.
** Original Author ** Seth Grover — mmguero
** Re-write Author: Giveen**
BSD 3-Clause License — see LICENSE
Thanks to:
- FFmpeg
- Mattias Wadman for his static-ffmpeg image
- delegator.py by Kenneth Reitz
- pysrt by Jean Boussier
- subliminal by Antoine Bertin
- FFmpeg
- pysrt
- subliminal
- babelfish