monkeyplug-enhanced 2.2.4__tar.gz → 2.3.0__tar.gz

{monkeyplug_enhanced-2.2.4 → monkeyplug_enhanced-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: monkeyplug-enhanced
-Version: 2.2.4
+Version: 2.3.0
 Summary: Enhanced fork of monkeyplug — censors profanity in audio files using speech recognition with Groq API, AI instrumental generation, and batch processing.
 Project-URL: Homepage, https://github.com/ljbred08/monkeyplug
 Project-URL: Issues, https://github.com/ljbred08/monkeyplug/issues
@@ -11,14 +11,18 @@ Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
-Requires-Python: >=3.6
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: duckduckgo-search>=6.0.0
 Requires-Dist: groq>=0.1.0
 Requires-Dist: mmguero==2.0.3
 Requires-Dist: mutagen==1.47.0
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: requests==2.32.5
+Requires-Dist: shazamio>=0.8.0
 Requires-Dist: sherpa-onnx>=1.10.0
 Requires-Dist: soundfile>=0.12.0
+Requires-Dist: spotify-scraper>=0.1.0
 Requires-Dist: tqdm>=4.65.0
 Description-Content-Type: text/markdown
 
@@ -34,9 +38,12 @@ The CLI command is still `monkeyplug` — only the package name changed to avoid
 
 - **Groq API** integration (fast, default mode)
 - **AI instrumental generation** via sherpa-onnx source separation
+- **AI profanity detection** via Groq LLM with structured outputs
 - **Wildcard/batch processing** with automatic vocal detection
+- **Progress bar** for non-verbose mode
 - **Transcript save/reuse** for faster reprocessing
 - **Config file** support with sensible defaults
+- **Automatic metadata tagging** via ShazamIO (title, artist, genre, cover art)
 
 ## How It Works
 
@@ -62,7 +69,7 @@ pip install 'git+https://github.com/ljbred08/monkeyplug'
 ### Prerequisites
 
 - **FFmpeg** — install via your OS package manager or from [ffmpeg.org](https://www.ffmpeg.org/download.html)
-- **Python 3.6+**
+- **Python 3.10+**
 - **Groq API key** (for default mode) — see [Groq API Setup](#groq-api-setup)
 - Optional: [Whisper](https://github.com/openai/whisper) or [Vosk](https://github.com/alphacep/vosk-api) for offline recognition
 
@@ -94,6 +101,7 @@ echo 'gsk_...' > .groq_key
 
 ```bash
 # Basic usage — mutes profanity using Groq API and built-in word list
+# Shows progress bar automatically in non-verbose mode
 monkeyplug -i song.mp3 -o song_clean.mp3
 
 # Verbose output to see what's happening
@@ -229,14 +237,130 @@ monkeyplug -i song.mp3 -o song_clean_strict.mp3 --input-transcript song_clean_tr
 
 ```bash
 # Use a custom text file (one word per line, or word|replacement)
-monkeyplug -i podcast.mp3 -o podcast_clean.mp3 -w custom_swears.txt
+monkeyplug -i podcast.mp3 -o podcast_clean.mp3 --swears custom_swears.txt
 
 # Use a custom JSON file (array of strings)
-monkeyplug -i podcast.mp3 -o podcast_clean.mp3 -w custom_swears.json
+monkeyplug -i podcast.mp3 -o podcast_clean.mp3 --swears custom_swears.json
 
 # Custom words are merged with the built-in profanity list
 ```
 
+## Automatic Metadata Tagging
+
+monkeyplug automatically fetches song metadata from Shazam and embeds it into the output file:
+
+- **Title, Artist, Genre** - Text tags embedded in the audio file
+- **Cover Art** - Album artwork downloaded and embedded (MP3 only)
+
+```bash
+# Metadata is enabled by default
+monkeyplug -i song.mp3 -o song_clean.mp3
+
+# Disable metadata fetching
+monkeyplug -i song.mp3 -o song_clean.mp3 --disable-metadata
+```
+
+**What happens:**
+1. The input file is analyzed by Shazam to identify the song
+2. Metadata (title, artist, genre, cover art URL) is retrieved
+3. Cover art is downloaded and embedded as ID3/APIC frames
+4. Text tags are added to the output file
+
+**Notes:**
+- Requires internet connection for Shazam recognition
+- Cover art embedding is supported for MP3 files
+- If recognition fails, the file is still processed (no error)
+- Metadata can be viewed in any music player or with `ffprobe`
+
+## Show Profanity Output
+
+Control what's printed about detected profanity in normal (non-verbose) mode:
+
+```bash
+# Show count only (default)
+monkeyplug -i song.mp3 -o song_clean.mp3 -w clean
+
+# Show full list with timestamps
+monkeyplug -i song.mp3 -o song_clean.mp3 -w full
+
+# Silent mode (no profanity output)
+monkeyplug -i song.mp3 -o song_clean.mp3 -w none
+```
+
+## AI Profanity Detection
+
+Use Groq's LLM for context-aware profanity detection instead of (or in addition to) the static word list:
+
+```bash
+# AI-only detection (replaces static list)
+monkeyplug -i song.mp3 -o song_clean.mp3 --detect ai
+
+# Both list + AI (word flagged if either catches it)
+monkeyplug -i song.mp3 -o song_clean.mp3 --detect both
+
+# Default: static list only
+monkeyplug -i song.mp3 -o song_clean.mp3 --detect list
+```
+
+Requires a Groq API key (same setup as Groq STT mode). Works with all speech recognition modes (Groq, Whisper, Vosk).
+
+Configurable via `~/.cache/monkeyplug/config.json`:
+```json
+{
+  "detect_mode": "list",
+  "ai_detect_model": "openai/gpt-oss-20b",
+  "ai_detect_prompt": "You are a profanity detection assistant..."
+}
+```
+
+## Album Metadata Unification
+
+Unify album names, cover art, and assign track numbers across a folder of songs using AI:
+
+```bash
+# Basic AI unification
+monkeyplug --unify-album
+
+# With Spotify integration (recommended for best results)
+monkeyplug --unify-album --use-spotify
+
+# With direct Spotify URL (skip search)
+monkeyplug --unify-album --use-spotify "https://open.spotify.com/album/1kCHru7uhxBUdzkm4gzRQc"
+
+# Combine with normal processing
+monkeyplug -i "album/*.mp3" -o "album/*_clean.mp3" --unify-album
+
+# Full workflow with Spotify and smart renaming
+monkeyplug -i "album/*.mp3" -o "album/*_clean.mp3" --unify-album --use-spotify --auto-rename
+```
+
+The AI analyzes all songs together to determine the correct album name and track order. With `--use-spotify`, it fetches official cover art and track listings from Spotify for accurate results.
+
+**Two modes:**
+
+1. **Combined with processing**: Runs after normal audio processing completes
+2. **Standalone**: Processes existing files without audio processing (requires Groq API key)
+
+**Spotify Integration (--use-spotify):**
+- Provide a direct Spotify URL to skip the search step
+- Or let it search automatically for the album
+- Downloads official cover art (640x640)
+- Gets official track listing for accurate ordering
+- Applies consistent cover art to all tracks
+
+**Configurable via `~/.cache/monkeyplug/config.json`:**
+```json
+{
+  "unify_album_model": "openai/gpt-oss-120b",
+  "unify_album_prompt": "You are a music metadata expert..."
+}
+```
+
+**Requirements:**
+- Groq API key (same setup as other AI features)
+- Files must have existing metadata (title, album)
+- MP3 files get full support (album + track number + cover art via ID3 tags)
+
 ## Config File
 
 monkeyplug looks for a JSON config file in this order (first found wins):
@@ -252,7 +376,11 @@ If neither exists, a default config is auto-created at `~/.cache/monkeyplug/conf
   "pad_milliseconds_pre": 10,
   "pad_milliseconds_post": 10,
   "separation_padding": 1.0,
-  "beep_hertz": 1000
+  "beep_hertz": 1000,
+  "show_words": "clean",
+  "detect_mode": "list",
+  "ai_detect_model": "openai/gpt-oss-20b",
+  "ai_detect_prompt": "You are a profanity detection assistant..."
 }
 ```
 
@@ -295,7 +423,9 @@ Censorship Modes:
   --instrumental-auto-candidates <int>  Top candidates for AUTO matching (default: 5)
 
 Profanity:
-  -w, --swears <file>               Custom profanity list (text or JSON)
+  --swears <file>                   Custom profanity list (text or JSON)
+  --detect <list|ai|both>           Profanity detection method (default: list)
+  -w, --show-words <clean|full|none>  Show detected profanity (default: clean)
   --pad-milliseconds <int>          Padding around profanity (default: 10)
   --pad-milliseconds-pre <int>      Padding before profanity (default: 10)
   --pad-milliseconds-post <int>     Padding after profanity (default: 10)
@@ -327,6 +457,8 @@ Audio Output:
 
 Other:
   --force                           Process file even if already tagged
+  --disable-metadata                Disable automatic metadata fetching via ShazamIO
+  --unify-album                     Unify album metadata across all files in the folder using AI
   --clean-cache                     Delete all cached data (models, config) and exit
 
 Groq Options:

{monkeyplug_enhanced-2.2.4 → monkeyplug_enhanced-2.3.0}/README.md

@@ -10,9 +10,12 @@ The CLI command is still `monkeyplug` — only the package name changed to avoid
 
 - **Groq API** integration (fast, default mode)
 - **AI instrumental generation** via sherpa-onnx source separation
+- **AI profanity detection** via Groq LLM with structured outputs
 - **Wildcard/batch processing** with automatic vocal detection
+- **Progress bar** for non-verbose mode
 - **Transcript save/reuse** for faster reprocessing
 - **Config file** support with sensible defaults
+- **Automatic metadata tagging** via ShazamIO (title, artist, genre, cover art)
 
 ## How It Works
 
@@ -38,7 +41,7 @@ pip install 'git+https://github.com/ljbred08/monkeyplug'
 ### Prerequisites
 
 - **FFmpeg** — install via your OS package manager or from [ffmpeg.org](https://www.ffmpeg.org/download.html)
-- **Python 3.6+**
+- **Python 3.10+**
 - **Groq API key** (for default mode) — see [Groq API Setup](#groq-api-setup)
 - Optional: [Whisper](https://github.com/openai/whisper) or [Vosk](https://github.com/alphacep/vosk-api) for offline recognition
 
@@ -70,6 +73,7 @@ echo 'gsk_...' > .groq_key
 
 ```bash
 # Basic usage — mutes profanity using Groq API and built-in word list
+# Shows progress bar automatically in non-verbose mode
 monkeyplug -i song.mp3 -o song_clean.mp3
 
 # Verbose output to see what's happening
@@ -205,14 +209,130 @@ monkeyplug -i song.mp3 -o song_clean_strict.mp3 --input-transcript song_clean_tr
 
 ```bash
 # Use a custom text file (one word per line, or word|replacement)
-monkeyplug -i podcast.mp3 -o podcast_clean.mp3 -w custom_swears.txt
+monkeyplug -i podcast.mp3 -o podcast_clean.mp3 --swears custom_swears.txt
 
 # Use a custom JSON file (array of strings)
-monkeyplug -i podcast.mp3 -o podcast_clean.mp3 -w custom_swears.json
+monkeyplug -i podcast.mp3 -o podcast_clean.mp3 --swears custom_swears.json
 
 # Custom words are merged with the built-in profanity list
 ```
 
+## Automatic Metadata Tagging
+
+monkeyplug automatically fetches song metadata from Shazam and embeds it into the output file:
+
+- **Title, Artist, Genre** - Text tags embedded in the audio file
+- **Cover Art** - Album artwork downloaded and embedded (MP3 only)
+
+```bash
+# Metadata is enabled by default
+monkeyplug -i song.mp3 -o song_clean.mp3
+
+# Disable metadata fetching
+monkeyplug -i song.mp3 -o song_clean.mp3 --disable-metadata
+```
+
+**What happens:**
+1. The input file is analyzed by Shazam to identify the song
+2. Metadata (title, artist, genre, cover art URL) is retrieved
+3. Cover art is downloaded and embedded as ID3/APIC frames
+4. Text tags are added to the output file
+
+**Notes:**
+- Requires internet connection for Shazam recognition
+- Cover art embedding is supported for MP3 files
+- If recognition fails, the file is still processed (no error)
+- Metadata can be viewed in any music player or with `ffprobe`
+
+## Show Profanity Output
+
+Control what's printed about detected profanity in normal (non-verbose) mode:
+
+```bash
+# Show count only (default)
+monkeyplug -i song.mp3 -o song_clean.mp3 -w clean
+
+# Show full list with timestamps
+monkeyplug -i song.mp3 -o song_clean.mp3 -w full
+
+# Silent mode (no profanity output)
+monkeyplug -i song.mp3 -o song_clean.mp3 -w none
+```
+
+## AI Profanity Detection
+
+Use Groq's LLM for context-aware profanity detection instead of (or in addition to) the static word list:
+
+```bash
+# AI-only detection (replaces static list)
+monkeyplug -i song.mp3 -o song_clean.mp3 --detect ai
+
+# Both list + AI (word flagged if either catches it)
+monkeyplug -i song.mp3 -o song_clean.mp3 --detect both
+
+# Default: static list only
+monkeyplug -i song.mp3 -o song_clean.mp3 --detect list
+```
+
+Requires a Groq API key (same setup as Groq STT mode). Works with all speech recognition modes (Groq, Whisper, Vosk).
+
+Configurable via `~/.cache/monkeyplug/config.json`:
+```json
+{
+  "detect_mode": "list",
+  "ai_detect_model": "openai/gpt-oss-20b",
+  "ai_detect_prompt": "You are a profanity detection assistant..."
+}
+```
+
+## Album Metadata Unification
+
+Unify album names, cover art, and assign track numbers across a folder of songs using AI:
+
+```bash
+# Basic AI unification
+monkeyplug --unify-album
+
+# With Spotify integration (recommended for best results)
+monkeyplug --unify-album --use-spotify
+
+# With direct Spotify URL (skip search)
+monkeyplug --unify-album --use-spotify "https://open.spotify.com/album/1kCHru7uhxBUdzkm4gzRQc"
+
+# Combine with normal processing
+monkeyplug -i "album/*.mp3" -o "album/*_clean.mp3" --unify-album
+
+# Full workflow with Spotify and smart renaming
+monkeyplug -i "album/*.mp3" -o "album/*_clean.mp3" --unify-album --use-spotify --auto-rename
+```
+
+The AI analyzes all songs together to determine the correct album name and track order. With `--use-spotify`, it fetches official cover art and track listings from Spotify for accurate results.
+
+**Two modes:**
+
+1. **Combined with processing**: Runs after normal audio processing completes
+2. **Standalone**: Processes existing files without audio processing (requires Groq API key)
+
+**Spotify Integration (--use-spotify):**
+- Provide a direct Spotify URL to skip the search step
+- Or let it search automatically for the album
+- Downloads official cover art (640x640)
+- Gets official track listing for accurate ordering
+- Applies consistent cover art to all tracks
+
+**Configurable via `~/.cache/monkeyplug/config.json`:**
+```json
+{
+  "unify_album_model": "openai/gpt-oss-120b",
+  "unify_album_prompt": "You are a music metadata expert..."
+}
+```
+
+**Requirements:**
+- Groq API key (same setup as other AI features)
+- Files must have existing metadata (title, album)
+- MP3 files get full support (album + track number + cover art via ID3 tags)
+
 ## Config File
 
 monkeyplug looks for a JSON config file in this order (first found wins):
@@ -228,7 +348,11 @@ If neither exists, a default config is auto-created at `~/.cache/monkeyplug/conf
   "pad_milliseconds_pre": 10,
   "pad_milliseconds_post": 10,
   "separation_padding": 1.0,
-  "beep_hertz": 1000
+  "beep_hertz": 1000,
+  "show_words": "clean",
+  "detect_mode": "list",
+  "ai_detect_model": "openai/gpt-oss-20b",
+  "ai_detect_prompt": "You are a profanity detection assistant..."
 }
 ```
 
@@ -271,7 +395,9 @@ Censorship Modes:
   --instrumental-auto-candidates <int>  Top candidates for AUTO matching (default: 5)
 
 Profanity:
-  -w, --swears <file>               Custom profanity list (text or JSON)
+  --swears <file>                   Custom profanity list (text or JSON)
+  --detect <list|ai|both>           Profanity detection method (default: list)
+  -w, --show-words <clean|full|none>  Show detected profanity (default: clean)
   --pad-milliseconds <int>          Padding around profanity (default: 10)
   --pad-milliseconds-pre <int>      Padding before profanity (default: 10)
   --pad-milliseconds-post <int>     Padding after profanity (default: 10)
@@ -303,6 +429,8 @@ Audio Output:
 
 Other:
   --force                           Process file even if already tagged
+  --disable-metadata                Disable automatic metadata fetching via ShazamIO
+  --unify-album                     Unify album metadata across all files in the folder using AI
   --clean-cache                     Delete all cached data (models, config) and exit
 
 Groq Options:

{monkeyplug_enhanced-2.2.4 → monkeyplug_enhanced-2.3.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "monkeyplug-enhanced"
-version = "2.2.4"
+version = "2.3.0"
 authors = [
   { name="Seth Grover", email="mero.mero.guero@gmail.com" },
   { name="Lincoln Brown", email="link@brown.fm" },
 ]
 description = "Enhanced fork of monkeyplug — censors profanity in audio files using speech recognition with Groq API, AI instrumental generation, and batch processing."
 readme = "README.md"
-requires-python = ">=3.6"
+requires-python = ">=3.10"
 classifiers = [
     "License :: OSI Approved :: BSD License",
     "Operating System :: OS Independent",
@@ -27,6 +27,10 @@ dependencies = [
     "numpy>=1.24.0",
     "soundfile>=0.12.0",
     "tqdm>=4.65.0",
+    "shazamio>=0.8.0",
+    "aiohttp>=3.9.0",
+    "duckduckgo-search>=6.0.0",
+    "spotify-scraper>=0.1.0",
 ]
 
 [project.urls]