cleanvid is a little script to mute profanity in video files in a few simple steps:
- The user provides as input a video file and matching
.srtsubtitle file. If subtitles are not provided explicitly, they will be extracted from the video file if possible; if not,subliminalis used to attempt to download the best matching.srtfile. pysrtis used to parse the.srtfile, and each entry is checked against a list of profanity or other words or phrases you'd like muted. Mappings can be provided (eg., map "sh*t" to "poop"), otherwise the word will be replaced with *****.- A new "clean"
.srtfile is created. with only those phrases containing the censored/replaced objectional language. ffmpegis used to create a cleaned video file. This file contains the original video stream, but the specified audio stream is muted during the segments containing objectional language. That audio stream is re-encoded and remultiplexed back together with the video. Optionally, the clean.srtfile can be embedded in the cleaned video file as a subtitle track.
You can then use your favorite media player to play the cleaned video file together with the cleaned subtitles.
As an alternative to creating a new video file, cleanvid can create a simple EDL file (see the mplayer or KODI documentation) or a custom JSON definition file for PlexAutoSkip.
cleanvid is part of a family of projects with similar goals:
- 📼 cleanvid for video files (using SRT-formatted subtitles)
- 🎤 monkeyplug for audio and video files (using either Whisper or the Vosk-API for speech recognition)
- 📕 montag for ebooks
Using pip, to install the latest release from PyPI:
python3 -m pip install -U cleanvid
Or to install directly from GitHub:
python3 -m pip install -U 'git+https://github.com/mmguero/cleanvid'
cleanvid requires:
- Python 3
- FFmpeg
- babelfish
- delegator.py
- pysrt
- subliminal
To install FFmpeg, use your operating system's package manager or install binaries from ffmpeg.org. The Python dependencies will be installed automatically if you are using pip to install cleanvid.
usage: cleanvid [-h] [-s <srt>] -i <input video> [-o <output video>] [--plex-auto-skip-json <output JSON>] [--plex-auto-skip-id <content identifier>] [--subs-output <output srt>]
[-w <profanity file>] [-l <language>] [-p <int>] [-e] [-f] [--subs-only] [--offline] [--edl] [--json] [--re-encode-video] [--re-encode-audio] [-b] [-v VPARAMS] [-a APARAMS]
[-d] [--audio-stream-index <int>] [--audio-stream-list] [--threads-input <int>] [--threads-encoding <int>] [--threads <int>]
options:
-h, --help show this help message and exit
-s <srt>, --subs <srt>
.srt subtitle file (will attempt auto-download if unspecified and not --offline)
-i <input video>, --input <input video>
input video file
-o <output video>, --output <output video>
output video file
--plex-auto-skip-json <output JSON>
custom JSON file for PlexAutoSkip (also implies --subs-only)
--plex-auto-skip-id <content identifier>
content identifier for PlexAutoSkip (also implies --subs-only)
--subs-output <output srt>
output subtitle file
-w <profanity file>, --swears <profanity file>
text file containing profanity (with optional mapping)
-l <language>, --lang <language>
language for extracting srt from video file or srt download (default is "eng")
-p <int>, --pad <int>
pad (seconds) around profanity
-e, --embed-subs embed subtitles in resulting video file
-f, --full-subs include all subtitles in output subtitle file (not just scrubbed)
--subs-only only operate on subtitles (do not alter audio)
--offline don't attempt to download subtitles
--edl generate MPlayer EDL file with mute actions (also implies --subs-only)
--json generate JSON file with muted subtitles and their contents
--re-encode-video Re-encode video
--re-encode-audio Re-encode audio
-b, --burn Hard-coded subtitles (implies re-encode)
-v VPARAMS, --video-params VPARAMS
Video parameters for ffmpeg (only if re-encoding)
-a APARAMS, --audio-params APARAMS
Audio parameters for ffmpeg
-d, --downmix Downmix to stereo (if not already stereo)
--audio-stream-index <int>
Index of audio stream to process
--audio-stream-list Show list of audio streams (to get index for --audio-stream-index)
--threads-input <int>
ffmpeg global options -threads value
--threads-encoding <int>
ffmpeg encoding options -threads value
--threads <int> ffmpeg -threads value (for both global options and encoding)
Alternately, a Dockerfile is provided to allow you to run cleanvid in Docker. You can build the oci.guero.top/cleanvid:latest Docker image with build_docker.sh, then run cleanvid-docker.sh inside the directory where your video/subtitle files are located.
If you'd like to help improve cleanvid, pull requests will be welcomed!
- Seth Grover - Initial work - mmguero
This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.
Thanks to:
- the developers of FFmpeg
- Mattias Wadman for his ffmpeg image
- delegator.py developer Kenneth Reitz and contributors
- pysrt developer Jean Boussier and contributors
- subliminal developer Antoine Bertin and contributors