Skip to main content

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

Project description

monkeyplug

Latest Version VOSK Docker Images Whisper Docker Images

monkeyplug is a little script to censor 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. Either Whisper (GitHub) or 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 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:

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:

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

monkeyplug-2.1.3.tar.gz (17.5 kB view details)

Uploaded Source

Built Distribution

monkeyplug-2.1.3-py3-none-any.whl (15.5 kB view details)

Uploaded Python 3

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

Hashes for monkeyplug-2.1.3.tar.gz
Algorithm Hash digest
SHA256 e3ff6ed2f37953c5ff12a369d7169d70e9e46198cf8b4ec449c238f13d2f683d
MD5 928a1896a38465c3f0dee44e6399421a
BLAKE2b-256 59af580d16ab4363a1ea2948b31a2e3fc2a49f15b9b1b60e21d8dcc4c687051a

See more details on using hashes here.

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

Hashes for monkeyplug-2.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 7be411da1424ae69880c7036c4cd3e48b2b4ec1ba841e8e8f17aa1b099154c85
MD5 bd7c15bc23cb6f97b7ae7a82361f7ef2
BLAKE2b-256 d579649cd8b9d63f0cf22f2b4e2d489f68d8e56d670c5226719bb261d0a8145e

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page