{"id":21180036,"url":"https://github.com/mmguero/cleanvid","last_synced_at":"2025-04-05T17:09:07.568Z","repository":{"id":36738706,"uuid":"41045302","full_name":"mmguero/cleanvid","owner":"mmguero","description":"cleanvid is a little script to mute profanity in video files","archived":false,"fork":false,"pushed_at":"2024-11-19T03:11:30.000Z","size":446,"stargazers_count":65,"open_issues_count":4,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T16:05:00.654Z","etag":null,"topics":["ffmpeg","objectional-language","obscenity","profanity","profanity-detection","profanity-filter","profanityfilter","python","python3","srt","subtitle","swear-filter","video","video-files"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmguero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-19T16:15:52.000Z","updated_at":"2025-03-25T19:44:59.000Z","dependencies_parsed_at":"2024-06-25T04:39:45.042Z","dependency_job_id":"917621fa-2303-44a5-b7c8-5456cdfe0aa4","html_url":"https://github.com/mmguero/cleanvid","commit_stats":{"total_commits":84,"total_committers":4,"mean_commits":21.0,"dds":"0.33333333333333337","last_synced_commit":"e53b067ed9e6114a2385ca8442f14c4ad79cb462"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmguero%2Fcleanvid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmguero%2Fcleanvid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmguero%2Fcleanvid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmguero%2Fcleanvid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmguero","download_url":"https://codeload.github.com/mmguero/cleanvid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ffmpeg","objectional-language","obscenity","profanity","profanity-detection","profanity-filter","profanityfilter","python","python3","srt","subtitle","swear-filter","video","video-files"],"created_at":"2024-11-20T17:35:44.662Z","updated_at":"2025-04-05T17:09:07.533Z","avatar_url":"https://github.com/mmguero.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cleanvid\n\n[![Latest Version](https://img.shields.io/pypi/v/cleanvid)](https://pypi.python.org/pypi/cleanvid/) [![Docker Image](https://github.com/mmguero/cleanvid/workflows/cleanvid-build-push-ghcr/badge.svg)](https://github.com/mmguero/cleanvid/pkgs/container/cleanvid)\n\n**cleanvid** is a little script to mute profanity in video files in a few simple steps:\n\n1. 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.\n2. [`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 *****.\n3. A new \"clean\" `.srt` file is created. with *only* those phrases containing the censored/replaced objectional language.\n4. [`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.\n\nYou can then use your favorite media player to play the cleaned video file together with the cleaned subtitles.\n\nAs 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).\n\n**cleanvid** is part of a family of projects with similar goals:\n\n* 📼 [cleanvid](https://github.com/mmguero/cleanvid) for video files (using [SRT-formatted](https://en.wikipedia.org/wiki/SubRip#Format) subtitles)\n* 🎤 [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)\n* 📕 [montag](https://github.com/mmguero/montag) for ebooks\n## Installation\n\nUsing `pip`, to install the latest [release from PyPI](https://pypi.org/project/cleanvid/):\n\n```\npython3 -m pip install -U cleanvid\n```\n\nOr to install directly from GitHub:\n\n\n```\npython3 -m pip install -U 'git+https://github.com/mmguero/cleanvid'\n```\n\n## Prerequisites\n\n[cleanvid](./src/cleanvid/cleanvid.py) requires:\n\n* Python 3\n* [FFmpeg](https://www.ffmpeg.org)\n* [babelfish](https://github.com/Diaoul/babelfish)\n* [delegator.py](https://github.com/kennethreitz/delegator.py)\n* [pysrt](https://github.com/byroot/pysrt)\n* [subliminal](https://github.com/Diaoul/subliminal)\n\nTo 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.\n\n## usage\n\n```\nusage: cleanvid [-h] [-s \u003csrt\u003e] -i \u003cinput video\u003e [-o \u003coutput video\u003e] [--plex-auto-skip-json \u003coutput JSON\u003e] [--plex-auto-skip-id \u003ccontent identifier\u003e] [--subs-output \u003coutput srt\u003e]\n                [-w \u003cprofanity file\u003e] [-l \u003clanguage\u003e] [-p \u003cint\u003e] [-e] [-f] [--subs-only] [--offline] [--edl] [--json] [--re-encode-video] [--re-encode-audio] [-b] [-v VPARAMS] [-a APARAMS]\n                [-d] [--audio-stream-index \u003cint\u003e] [--audio-stream-list] [--threads-input \u003cint\u003e] [--threads-encoding \u003cint\u003e] [--threads \u003cint\u003e]\n\noptions:\n  -h, --help            show this help message and exit\n  -s \u003csrt\u003e, --subs \u003csrt\u003e\n                        .srt subtitle file (will attempt auto-download if unspecified and not --offline)\n  -i \u003cinput video\u003e, --input \u003cinput video\u003e\n                        input video file\n  -o \u003coutput video\u003e, --output \u003coutput video\u003e\n                        output video file\n  --plex-auto-skip-json \u003coutput JSON\u003e\n                        custom JSON file for PlexAutoSkip (also implies --subs-only)\n  --plex-auto-skip-id \u003ccontent identifier\u003e\n                        content identifier for PlexAutoSkip (also implies --subs-only)\n  --subs-output \u003coutput srt\u003e\n                        output subtitle file\n  -w \u003cprofanity file\u003e, --swears \u003cprofanity file\u003e\n                        text file containing profanity (with optional mapping)\n  -l \u003clanguage\u003e, --lang \u003clanguage\u003e\n                        language for extracting srt from video file or srt download (default is \"eng\")\n  -p \u003cint\u003e, --pad \u003cint\u003e\n                        pad (seconds) around profanity\n  -e, --embed-subs      embed subtitles in resulting video file\n  -f, --full-subs       include all subtitles in output subtitle file (not just scrubbed)\n  --subs-only           only operate on subtitles (do not alter audio)\n  --offline             don't attempt to download subtitles\n  --edl                 generate MPlayer EDL file with mute actions (also implies --subs-only)\n  --json                generate JSON file with muted subtitles and their contents\n  --re-encode-video     Re-encode video\n  --re-encode-audio     Re-encode audio\n  -b, --burn            Hard-coded subtitles (implies re-encode)\n  -v VPARAMS, --video-params VPARAMS\n                        Video parameters for ffmpeg (only if re-encoding)\n  -a APARAMS, --audio-params APARAMS\n                        Audio parameters for ffmpeg\n  -d, --downmix         Downmix to stereo (if not already stereo)\n  --audio-stream-index \u003cint\u003e\n                        Index of audio stream to process\n  --audio-stream-list   Show list of audio streams (to get index for --audio-stream-index)\n  --threads-input \u003cint\u003e\n                        ffmpeg global options -threads value\n  --threads-encoding \u003cint\u003e\n                        ffmpeg encoding options -threads value\n  --threads \u003cint\u003e       ffmpeg -threads value (for both global options and encoding)\n```\n\n### Docker\n\nAlternately, 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.\n\n## Contributing\n\nIf you'd like to help improve cleanvid, pull requests will be welcomed!\n\n## Authors\n\n* **Seth Grover** - *Initial work* - [mmguero](https://github.com/mmguero)\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nThanks to:\n\n* the developers of [FFmpeg](https://www.ffmpeg.org/about.html)\n* [Mattias Wadman](https://github.com/wader) for his [ffmpeg](https://github.com/wader/static-ffmpeg) image\n* [delegator.py](https://github.com/kennethreitz/delegator.py) developer Kenneth Reitz and contributors\n* [pysrt](https://github.com/byroot/pysrt) developer Jean Boussier and contributors\n* [subliminal](https://github.com/Diaoul/subliminal) developer Antoine Bertin and contributors","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmguero%2Fcleanvid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmguero%2Fcleanvid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmguero%2Fcleanvid/lists"}