Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mmguero/monkeyplug

monkeyplug is a little script to mute profanity in audio files
https://github.com/mmguero/monkeyplug

audio audio-files ffmpeg objectional-language obscene-filter obscenity podcasts profanity profanity-detection profanity-filter profanity-filtering profanityfilter python python3 swear-filter vosk

Last synced: about 1 month ago
JSON representation

monkeyplug is a little script to mute profanity in audio files

Host: GitHub
URL: https://github.com/mmguero/monkeyplug
Owner: mmguero
License: bsd-3-clause
Created: 2021-10-28T21:13:56.000Z (about 3 years ago)
Default Branch: main
Last Pushed: 2024-08-30T02:08:05.000Z (4 months ago)
Last Synced: 2024-11-18T22:54:02.290Z (about 1 month ago)
Topics: audio, audio-files, ffmpeg, objectional-language, obscene-filter, obscenity, podcasts, profanity, profanity-detection, profanity-filter, profanity-filtering, profanityfilter, python, python3, swear-filter, vosk
Language: Python
Homepage:
Size: 120 KB
Stars: 27
Watchers: 4
Forks: 1
Open Issues: 6
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # monkeyplug

[![Latest Version](https://img.shields.io/pypi/v/monkeyplug)](https://pypi.python.org/pypi/monkeyplug/) [![VOSK Docker Images](https://github.com/mmguero/monkeyplug/workflows/monkeyplug-build-push-vosk-ghcr/badge.svg)](https://github.com/mmguero/monkeyplug/pkgs/container/monkeyplug) [![Whisper Docker Images](https://github.com/mmguero/monkeyplug/workflows/monkeyplug-build-push-whisper-ghcr/badge.svg)](https://github.com/mmguero/monkeyplug/pkgs/container/monkeyplug)

**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](https://openai.com/research/whisper) ([GitHub](https://github.com/openai/whisper)) or the [Vosk](https://alphacephei.com/vosk/)-[API](https://github.com/alphacep/vosk-api) is used to recognize speech in the audio file

3. Each recognized word is checked against a [list](./src/monkeyplug/swears.txt) of profanity or other words you'd like muted

4. [`ffmpeg`](https://www.ffmpeg.org/) 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](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/monkeyplug/):

```

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](./src/monkeyplug/monkeyplug.py) requires:

* [FFmpeg](https://www.ffmpeg.org)

* Python 3

    - [mutagen](https://github.com/quodlibet/mutagen)

    - a speech recognition library, either of:

        + [Whisper](https://github.com/openai/whisper)

        + [vosk-api](https://github.com/alphacep/vosk-api) with a VOSK [compatible model](https://alphacephei.com/vosk/models)

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 monkeyplug, except for [`vosk`](https://pypi.org/project/vosk/) or [`openai-whisper`](https://pypi.org/project/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 

monkeyplug.py

options:

  -v [true|false], --verbose [true|false]

                        Verbose/debug output

  -m , --mode 

                        Speech recognition engine (whisper|vosk) (default: whisper)

  -i , --input 

                        Input file (or URL)

  -o , --output 

                        Output file

  --output-json 

                        Output file to store transcript JSON

  -w , --swears 

                        text file containing profanity (default: "swears.txt")

  -a APARAMS, --audio-params APARAMS

                        Audio parameters for ffmpeg (default depends on output audio codec)

  -c , --channels 

                        Audio output channels (default: 2)

  -f , --format 

                        Output file format (default: inferred from extension of --output, or "MATCH")

  --pad-milliseconds 

                        Milliseconds to pad on either side of muted segments (default: 0)

  --pad-milliseconds-pre 

                        Milliseconds to pad before muted segments (default: 0)

  --pad-milliseconds-post 

                        Milliseconds to pad after muted segments (default: 0)

  -b [true|false], --beep [true|false]

                        Beep instead of silence

  -h , --beep-hertz 

                        Beep frequency hertz (default: 1000)

  --beep-mix-normalize [true|false]

                        Normalize mix of audio and beeps (default: False)

  --beep-audio-weight 

                        Mix weight for non-beeped audio (default: 1)

  --beep-sine-weight 

                        Mix weight for beep (default: 1)

  --beep-dropout-transition 

                        Dropout transition for beep (default: 0)

  --force [true|false]  Process file despite existence of embedded tag

VOSK Options:

  --vosk-model-dir 

                        VOSK model directory (default: ~/.cache/vosk)

  --vosk-read-frames-chunk 

                        WAV frame chunk (default: 8000)

Whisper Options:

  --whisper-model-dir 

                        Whisper model directory (~/.cache/whisper)

  --whisper-model-name 

                        Whisper model name (small.en)

```

### Docker

Alternately, a [Dockerfile](./docker/Dockerfile) is provided to allow you to run monkeyplug in Docker. You can pull one of the following images:

* [VOSK](https://alphacephei.com/vosk/models)

    - oci.guero.org/monkeyplug:vosk-small

    - oci.guero.org/monkeyplug:vosk-large

* [Whisper](https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages)

    - oci.guero.org/monkeyplug:whisper-tiny.en

    - oci.guero.org/monkeyplug:whisper-tiny

    - oci.guero.org/monkeyplug:whisper-base.en

    - oci.guero.org/monkeyplug:whisper-base

    - oci.guero.org/monkeyplug:whisper-small.en

    - oci.guero.org/monkeyplug:whisper-small

    - oci.guero.org/monkeyplug:whisper-medium.en

    - oci.guero.org/monkeyplug:whisper-medium

    - oci.guero.org/monkeyplug:whisper-large-v1

    - oci.guero.org/monkeyplug:whisper-large-v2

    - oci.guero.org/monkeyplug:whisper-large-v3

    - oci.guero.org/monkeyplug:whisper-large

then run [`monkeyplug-docker.sh`](./docker/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](https://github.com/mmguero)

## License

This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.