Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mmguero/cleanvid
cleanvid is a little script to mute profanity in video files
https://github.com/mmguero/cleanvid
ffmpeg objectional-language obscenity profanity profanity-detection profanity-filter profanityfilter python python3 srt subtitle swear-filter video video-files
Last synced: about 12 hours ago
JSON representation
cleanvid is a little script to mute profanity in video files
- Host: GitHub
- URL: https://github.com/mmguero/cleanvid
- Owner: mmguero
- License: bsd-3-clause
- Created: 2015-08-19T16:15:52.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2024-11-19T03:11:30.000Z (about 1 month ago)
- Last Synced: 2024-12-15T10:05:49.402Z (8 days ago)
- Topics: ffmpeg, objectional-language, obscenity, profanity, profanity-detection, profanity-filter, profanityfilter, python, python3, srt, subtitle, swear-filter, video, video-files
- Language: Python
- Homepage:
- Size: 436 KB
- Stars: 58
- Watchers: 5
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# cleanvid
[](https://pypi.python.org/pypi/cleanvid/) [](https://github.com/mmguero/cleanvid/pkgs/container/cleanvid)
**cleanvid** is a little script to mute profanity in video files in a few simple steps:
1. The user provides as input a video file and matching `.srt` subtitle file. If subtitles are not provided explicitly, they will be extracted from the video file if possible; if not, [`subliminal`](https://github.com/Diaoul/subliminal) is used to attempt to download the best matching `.srt` file.
2. [`pysrt`](https://github.com/byroot/pysrt) is used to parse the `.srt` file, and each entry is checked against a [list](./src/cleanvid/swears.txt) 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 *****.
3. A new "clean" `.srt` file is created. with *only* those phrases containing the censored/replaced objectional language.
4. [`ffmpeg`](https://www.ffmpeg.org/) is 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 `.srt` file 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](http://www.mplayerhq.hu/DOCS/HTML/en/edl.html) or KODI [documentation](https://kodi.wiki/view/Edit_decision_list)) or a custom JSON definition file for [PlexAutoSkip](https://github.com/mdhiggins/PlexAutoSkip).
**cleanvid** is part of a family of projects with similar goals:
* 📼 [cleanvid](https://github.com/mmguero/cleanvid) for video files (using [SRT-formatted](https://en.wikipedia.org/wiki/SubRip#Format) subtitles)
* 🎤 [monkeyplug](https://github.com/mmguero/monkeyplug) for audio and video files (using either [Whisper](https://openai.com/research/whisper) or the [Vosk](https://alphacephei.com/vosk/)-[API](https://github.com/alphacep/vosk-api) for speech recognition)
* 📕 [montag](https://github.com/mmguero/montag) for ebooks
## Installation
Using `pip`, to install the latest [release from PyPI](https://pypi.org/project/cleanvid/):
```
python3 -m pip install -U cleanvid
```
Or to install directly from GitHub:
```
python3 -m pip install -U 'git+https://github.com/mmguero/cleanvid'
```
## Prerequisites
[cleanvid](./src/cleanvid/cleanvid.py) requires:
* Python 3
* [FFmpeg](https://www.ffmpeg.org)
* [babelfish](https://github.com/Diaoul/babelfish)
* [delegator.py](https://github.com/kennethreitz/delegator.py)
* [pysrt](https://github.com/byroot/pysrt)
* [subliminal](https://github.com/Diaoul/subliminal)
To install FFmpeg, use your operating system's package manager or install binaries from [ffmpeg.org](https://www.ffmpeg.org/download.html). The Python dependencies will be installed automatically if you are using `pip` to install cleanvid.
## usage
```
usage: cleanvid [-h] [-s ] -i [-o ] [--plex-auto-skip-json ] [--plex-auto-skip-id ] [--subs-output ]
[-w ] [-l ] [-p ] [-e] [-f] [--subs-only] [--offline] [--edl] [--json] [--re-encode-video] [--re-encode-audio] [-b] [-v VPARAMS] [-a APARAMS]
[-d] [--audio-stream-index ] [--audio-stream-list] [--threads-input ] [--threads-encoding ] [--threads ]
options:
-h, --help show this help message and exit
-s , --subs
.srt subtitle file (will attempt auto-download if unspecified and not --offline)
-i , --input
input video file
-o , --output
output video file
--plex-auto-skip-json
custom JSON file for PlexAutoSkip (also implies --subs-only)
--plex-auto-skip-id
content identifier for PlexAutoSkip (also implies --subs-only)
--subs-output
output subtitle file
-w , --swears
text file containing profanity (with optional mapping)
-l , --lang
language for extracting srt from video file or srt download (default is "eng")
-p , --pad
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
Index of audio stream to process
--audio-stream-list Show list of audio streams (to get index for --audio-stream-index)
--threads-input
ffmpeg global options -threads value
--threads-encoding
ffmpeg encoding options -threads value
--threads ffmpeg -threads value (for both global options and encoding)
```
### Docker
Alternately, a [Dockerfile](./docker/Dockerfile) is provided to allow you to run cleanvid in Docker. You can build the `oci.guero.org/cleanvid:latest` Docker image with [`build_docker.sh`](./docker/build_docker.sh), then run [`cleanvid-docker.sh`](./docker/cleanvid-docker.sh) inside the directory where your video/subtitle files are located.
## Contributing
If you'd like to help improve cleanvid, pull requests will be welcomed!
## Authors
* **Seth Grover** - *Initial work* - [mmguero](https://github.com/mmguero)
## License
This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
Thanks to:
* the developers of [FFmpeg](https://www.ffmpeg.org/about.html)
* [Mattias Wadman](https://github.com/wader) for his [ffmpeg](https://github.com/wader/static-ffmpeg) image
* [delegator.py](https://github.com/kennethreitz/delegator.py) developer Kenneth Reitz and contributors
* [pysrt](https://github.com/byroot/pysrt) developer Jean Boussier and contributors
* [subliminal](https://github.com/Diaoul/subliminal) developer Antoine Bertin and contributors