monkeyplug 1.3.0

monkeyplug is a little script to mute profanity in audio files.

monkeyplug

monkeyplug is a little script to mute profanity in audio files (intended for podcasts, but YMMV) in a few simple steps:

1. The user provides a local audio file (or a URL pointing to an audio file which is downloaded)
2. The Vosk-API is used to recognize speech in the audio file
3. Each recognized word is checked against a list of profanity or other words you'd like muted
4. ffmpeg is used to create a cleaned audio file, muting 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
• 🎤 monkeyplug for audio files
• 📕 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
  • vosk-api

• A Vosk-API compatible model in a subdirectory named model in the same directory as monkeyplug.py, or in a custom directory location indicated with the --model runtime option or the VOSK_MODEL environment variable

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.

usage

usage: monkeyplug.py <arguments>

monkeyplug.py

options:
  -v [true|false], --verbose [true|false]
                        Verbose/debug output
  -i <string>, --input <string>
                        Input file (or URL)
  -o <string>, --output <string>
                        Output file
  --output-json <string>
                        Output file to store JSON generated by VOSK
  -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")
  -f <string>, --format <string>
                        Output file format (default: inferred from extension of --output, or "MATCH")
  -m <string>, --model <string>
                        Vosk model path (default: "model")
  --frames <int>        WAV frame chunk (default: 8000)
  --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)
  --force [true|false]  Process file despite existence of embedded tag

Docker

Alternately, a Dockerfile is provided to allow you to run monkeyplug in Docker. You can pull either the ghcr.io/mmguero/monkeyplug:small or ghcr.io/mmguero/monkeyplug:large Docker images, or build with build_docker.sh, 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.