monkeyplug is a little script to censor profanity in audio files.
Project description
monkeyplug
monkeyplug is a little script to censor profanity in audio files (intended for podcasts, but YMMV) in a few simple steps:
- The user provides a local audio file (or a URL pointing to an audio file which is downloaded)
- Either Whisper (GitHub) or the Vosk-API is used to recognize speech in the audio file
- Each recognized word is checked against a list of profanity or other words you'd like muted
ffmpeg
is used to create a cleaned audio file, muting or "bleeping" the objectional words
You can then use your favorite media player to play the cleaned audio file.
If provided a video file for input, monkeyplug will attempt to process the audio stream from the file and remultiplex it, copying the original video stream.
monkeyplug 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
Installation
Using pip
, to install the latest release from PyPI:
python3 -m pip install -U monkeyplug
Or to install directly from GitHub:
python3 -m pip install -U 'git+https://github.com/mmguero/monkeyplug'
Prerequisites
monkeyplug requires:
- FFmpeg
- Python 3
- mutagen
- a speech recognition library, either of:
- Whisper
- vosk-api with a VOSK compatible model
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 monkeyplug, except for vosk
or openai-whisper
; as monkeyplug can work with both speech recognition engines, there is not a hard installation requirement for either until runtime.
usage
usage: monkeyplug.py <arguments>
monkeyplug.py
options:
-v [true|false], --verbose [true|false]
Verbose/debug output
-m <string>, --mode <string>
Speech recognition engine (whisper|vosk) (default: whisper)
-i <string>, --input <string>
Input file (or URL)
-o <string>, --output <string>
Output file
--output-json <string>
Output file to store transcript JSON
-w <profanity file>, --swears <profanity file>
text file containing profanity (default: "swears.txt")
-a APARAMS, --audio-params APARAMS
Audio parameters for ffmpeg (default depends on output audio codec)
-c <int>, --channels <int>
Audio output channels (default: 2)
-f <string>, --format <string>
Output file format (default: inferred from extension of --output, or "MATCH")
--pad-milliseconds <int>
Milliseconds to pad on either side of muted segments (default: 0)
--pad-milliseconds-pre <int>
Milliseconds to pad before muted segments (default: 0)
--pad-milliseconds-post <int>
Milliseconds to pad after muted segments (default: 0)
-b [true|false], --beep [true|false]
Beep instead of silence
-h <int>, --beep-hertz <int>
Beep frequency hertz (default: 1000)
--beep-mix-normalize [true|false]
Normalize mix of audio and beeps (default: False)
--beep-audio-weight <int>
Mix weight for non-beeped audio (default: 1)
--beep-sine-weight <int>
Mix weight for beep (default: 1)
--beep-dropout-transition <int>
Dropout transition for beep (default: 0)
--force [true|false] Process file despite existence of embedded tag
VOSK Options:
--vosk-model-dir <string>
VOSK model directory (default: ~/.cache/vosk)
--vosk-read-frames-chunk <int>
WAV frame chunk (default: 8000)
Whisper Options:
--whisper-model-dir <string>
Whisper model directory (~/.cache/whisper)
--whisper-model-name <string>
Whisper model name (small.en)
Docker
Alternately, a Dockerfile is provided to allow you to run monkeyplug in Docker. You can pull one of the following images:
- VOSK
- oci.guero.top/monkeyplug:vosk-small
- oci.guero.top/monkeyplug:vosk-large
- Whisper
- oci.guero.top/monkeyplug:whisper-tiny.en
- oci.guero.top/monkeyplug:whisper-tiny
- oci.guero.top/monkeyplug:whisper-base.en
- oci.guero.top/monkeyplug:whisper-base
- oci.guero.top/monkeyplug:whisper-small.en
- oci.guero.top/monkeyplug:whisper-small
- oci.guero.top/monkeyplug:whisper-medium.en
- oci.guero.top/monkeyplug:whisper-medium
- oci.guero.top/monkeyplug:whisper-large-v1
- oci.guero.top/monkeyplug:whisper-large-v2
- oci.guero.top/monkeyplug:whisper-large-v3
- oci.guero.top/monkeyplug:whisper-large
then run monkeyplug-docker.sh
inside the directory where your audio files are located.
Contributing
If you'd like to help improve monkeyplug, pull requests will be welcomed!
Authors
- Seth Grover - Initial work - mmguero
License
This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file monkeyplug-2.1.3.tar.gz
.
File metadata
- Download URL: monkeyplug-2.1.3.tar.gz
- Upload date:
- Size: 17.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.0 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | e3ff6ed2f37953c5ff12a369d7169d70e9e46198cf8b4ec449c238f13d2f683d |
|
MD5 | 928a1896a38465c3f0dee44e6399421a |
|
BLAKE2b-256 | 59af580d16ab4363a1ea2948b31a2e3fc2a49f15b9b1b60e21d8dcc4c687051a |
Provenance
File details
Details for the file monkeyplug-2.1.3-py3-none-any.whl
.
File metadata
- Download URL: monkeyplug-2.1.3-py3-none-any.whl
- Upload date:
- Size: 15.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.0 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7be411da1424ae69880c7036c4cd3e48b2b4ec1ba841e8e8f17aa1b099154c85 |
|
MD5 | bd7c15bc23cb6f97b7ae7a82361f7ef2 |
|
BLAKE2b-256 | d579649cd8b9d63f0cf22f2b4e2d489f68d8e56d670c5226719bb261d0a8145e |