monkeyplug-enhanced 2.2.3__tar.gz → 2.2.5__tar.gz

{monkeyplug_enhanced-2.2.3 → monkeyplug_enhanced-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: monkeyplug-enhanced
-Version: 2.2.3
+Version: 2.2.5
 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

{monkeyplug_enhanced-2.2.3 → monkeyplug_enhanced-2.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "monkeyplug-enhanced"
-version = "2.2.3"
+version = "2.2.5"
 authors = [
   { name="Seth Grover", email="mero.mero.guero@gmail.com" },
   { name="Lincoln Brown", email="link@brown.fm" },

{monkeyplug_enhanced-2.2.3 → monkeyplug_enhanced-2.2.5}/src/monkeyplug/monkeyplug.py

@@ -16,6 +16,8 @@ import requests
 import shutil
 import string
 import sys
+import threading
+import time
 import wave
 from tqdm import tqdm
 
@@ -85,6 +87,36 @@ DEFAULT_WHISPER_MODEL_DIR = os.getenv(
 DEFAULT_WHISPER_MODEL_NAME = os.getenv("WHISPER_MODEL_NAME", "small.en")
 DEFAULT_TORCH_THREADS = 0
 
+AI_DETECT_PROMPT_DEFAULT = (
+    "You are a profanity detection assistant for audio content. "
+    "Given a numbered transcript with timestamps, identify all words that are profane, vulgar, or offensive. "
+    "Return each word's index number, the word itself, and its timestamps. "
+    "Consider context — some words are profane in one context but not another."
+)
+
+AI_DETECT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "reasoning": {"type": "string", "description": "Brief explanation of detection decisions"},
+        "profane_words": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "index": {"type": "integer", "description": "Word index in transcript"},
+                    "word": {"type": "string"},
+                    "start": {"type": "number"},
+                    "end": {"type": "number"}
+                },
+                "required": ["index", "word", "start", "end"],
+                "additionalProperties": False
+            }
+        }
+    },
+    "required": ["reasoning", "profane_words"],
+    "additionalProperties": False
+}
+
 ###################################################################################################
 # Determine script_path and script_name in a way that works both as module and direct execution
 try:
@@ -221,6 +253,63 @@ def GetCodecs(local_filename, debug=False):
     return result
 
 
+###################################################################################################
+class _SmoothProgressTicker:
+    """Background thread that smoothly advances a tqdm bar based on elapsed time.
+
+    Used when historical timing data allows estimating step durations.
+    The bar advances linearly within each step's estimated range, clamped
+    so it never overshoots. When the step completes, stop() snaps to actual.
+    """
+
+    def __init__(self, bar):
+        self._bar = bar
+        self._cumulative = 0.0  # Position where current step begins
+        self._step_estimate = 0.0  # Estimated seconds for current step
+        self._step_start = 0.0  # time.time() when step started
+        self._stop_event = threading.Event()
+        self._thread = None
+
+    def start(self, cumulative, step_estimated_seconds):
+        """Begin ticking for a new step."""
+        self.stop()  # Stop any previous tick
+        self._cumulative = cumulative
+        self._step_estimate = step_estimated_seconds
+        self._step_start = time.time()
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._tick, daemon=True)
+        self._thread.start()
+
+    def _tick(self):
+        while not self._stop_event.is_set():
+            try:
+                elapsed = time.time() - self._step_start
+                position = self._cumulative + min(elapsed, self._step_estimate)
+                # Never exceed the bar's total
+                if self._bar.total is not None:
+                    position = min(position, self._bar.total)
+                self._bar.n = position
+                self._bar.refresh()
+            except (TypeError, ValueError, AttributeError):
+                break  # Bar was closed externally
+            self._stop_event.wait(0.25)
+
+    def stop(self):
+        """Stop the ticker and return actual elapsed seconds for this step."""
+        self._stop_event.set()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=1.0)
+        self._thread = None
+        if self._step_start > 0:
+            return time.time() - self._step_start
+        return 0.0
+
+    def adjust_total(self, delta):
+        """Adjust the bar's total by delta (e.g., remove an unused step estimate)."""
+        if self._bar.total is not None:
+            self._bar.total = max(self._bar.total + delta, self._bar.n)
+
+
 #################################################################################
 class Plugger(object):
     debug = False
@@ -284,20 +373,30 @@ class Plugger(object):
         force=False,
         dbug=False,
         instrumentalFileSpec=None,
+        showWords="clean",
+        detectMode="list",
+        groqApiKey=None,
+        aiDetectModel="openai/gpt-oss-20b",
+        aiDetectPrompt=AI_DETECT_PROMPT_DEFAULT,
     ):
-        self.padSecPre = padMsecPre / 1000.0
-        self.padSecPost = padMsecPost / 1000.0
+        self.debug = dbug
+        self.outputJson = outputJson
+        self.inputTranscript = inputTranscript
+        self.saveTranscript = saveTranscript
+        self.forceDespiteTag = force
         self.beep = beep
         self.beepHertz = beepHertz
         self.beepMixNormalize = beepMixNormalize
         self.beepAudioWeight = beepAudioWeight
         self.beepSineWeight = beepSineWeight
         self.beepDropTransition = beepDropTransition
-        self.forceDespiteTag = force
-        self.debug = dbug
-        self.outputJson = outputJson
-        self.inputTranscript = inputTranscript
-        self.saveTranscript = saveTranscript
+        self.padSecPre = padMsecPre / 1000.0
+        self.padSecPost = padMsecPost / 1000.0
+        self.showWords = showWords
+        self.detectMode = detectMode
+        self.groqApiKey = groqApiKey
+        self.aiDetectModel = aiDetectModel
+        self.aiDetectPrompt = aiDetectPrompt
 
         # determine input file name, or download and save file
         if (iFileSpec is not None) and os.path.isfile(iFileSpec):
@@ -670,12 +769,42 @@ class Plugger(object):
 
     ######## CreateCleanMuteList #################################################
     def CreateCleanMuteList(self):
-        # Try to load existing transcript first, otherwise perform speech recognition
+        smooth = hasattr(self, '_smooth_ticker') and self._smooth_ticker is not None
+        cumulative = getattr(self, '_smooth_cumulative', 0.0)
+        will_transcribe = getattr(self, '_will_transcribe', False)
+
+        # Start ticker for transcribe step (if applicable)
+        if smooth and will_transcribe:
+            est = getattr(self, '_smooth_transcribe_est', 0)
+            if hasattr(self, '_progress') and self._progress:
+                self._progress.set_description("Transcribing")
+            self._smooth_ticker.start(cumulative, est)
+
+        transcribe_start = time.time() if will_transcribe else 0
         if not self.LoadTranscriptFromFile():
             self.RecognizeSpeech()
 
+        if will_transcribe:
+            actual_transcribe = time.time() - transcribe_start
+            if smooth:
+                self._smooth_ticker.stop()
+                cumulative += actual_transcribe
+                self._smooth_cumulative = cumulative
+            if hasattr(self, '_step_timings') and self._step_timings is not None:
+                self._step_timings['transcribe'] = (actual_transcribe, getattr(self, '_timing_file_duration', 0))
+
         self.naughtyWordList = [word for word in self.wordList if word["scrub"] is True]
 
+        # AI-based profanity detection (replaces or supplements list)
+        if self.detectMode in ("ai", "both"):
+            if self.detectMode == "ai":
+                # Reset list-based scrub flags — AI decides everything
+                for word in self.wordList:
+                    word["scrub"] = False
+            self._ai_detect_profanity()
+            # Rebuild naughtyWordList with AI results
+            self.naughtyWordList = [word for word in self.wordList if word["scrub"] is True]
+
         # Handle auto-generation mode
         if hasattr(self, 'autoGenerateMode') and self.autoGenerateMode and len(self.naughtyWordList) > 0:
             # Create merged profanity segments
@@ -684,30 +813,58 @@ class Plugger(object):
             # Extract, separate, and get instrumental file
             if self.instrumentalSegments:
                 try:
-                    # Update progress bar to show extraction starting
+                    # Update progress bar for extraction step
                     if hasattr(self, '_progress') and self._progress and not self.debug:
-                        self._progress.update(1)
-                        self._progress.total = 3
-                        self._progress.set_description("Extracting instrumental")
+                        if smooth:
+                            extract_est = getattr(self, '_smooth_extract_est', 0)
+                            self._progress.set_description("Extracting instrumental")
+                            self._smooth_ticker.start(cumulative, extract_est)
+                        else:
+                            self._progress.update(1)
+                            self._progress.total = 3
+                            self._progress.set_description("Extracting instrumental")
 
+                    extract_start = time.time()
                     self.instrumentalFileSpec = self._create_combined_profanity_file()
 
-                    # Update progress after extraction completes
-                    if hasattr(self, '_progress') and self._progress and not self.debug:
+                    actual_extract = time.time() - extract_start
+                    if smooth:
+                        self._smooth_ticker.stop()
+                        cumulative += actual_extract
+                        self._smooth_cumulative = cumulative
+                    if hasattr(self, '_step_timings') and self._step_timings is not None:
+                        self._step_timings['extract'] = (actual_extract, getattr(self, '_timing_file_duration', 0))
+
+                    # Update progress after extraction completes (step-based mode)
+                    if not smooth and hasattr(self, '_progress') and self._progress and not self.debug:
                         self._progress.update(1)
+
                     if self.instrumentalFileSpec:
                         self.instrumentalMode = True
                         self._build_instrumental_filters()
                         return []  # Return empty list for muteTimeList
                 except Exception as e:
                     # Fallback to mute if generation fails
+                    if smooth:
+                        self._smooth_ticker.stop()
                     if self.debug:
                         mmguero.eprint(f"Generation failed: {e}, falling back to mute mode")
                     self.instrumentalMode = False
                     return self._create_mute_beep_list()
             else:
+                # No instrumental segments — remove extract estimate from smooth bar
+                if smooth and hasattr(self, '_progress') and self._progress:
+                    extract_est = getattr(self, '_smooth_extract_est', 0)
+                    self._smooth_ticker.adjust_total(-extract_est)
                 return []
 
+        else:
+            # No profanity found in auto mode — remove extract estimate if applicable
+            if smooth and hasattr(self, 'autoGenerateMode') and self.autoGenerateMode:
+                extract_est = getattr(self, '_smooth_extract_est', 0)
+                if extract_est > 0 and hasattr(self, '_progress') and self._progress:
+                    self._smooth_ticker.adjust_total(-extract_est)
+
         # Handle traditional instrumental file mode or mute/beep mode
         if self.instrumentalMode:
             return self._create_instrumental_splice_list()
@@ -800,6 +957,140 @@ class Plugger(object):
 
         return self.muteTimeList
 
+    def _fmt_time(self, seconds):
+        """Format seconds as M:SS.mmm"""
+        mins = int(seconds) // 60
+        secs = seconds - mins * 60
+        return f"{mins}:{secs:06.3f}"
+
+    def _print_words_summary(self):
+        """Print profanity detection summary based on showWords mode."""
+        if self.showWords == "none":
+            return
+
+        if not self.naughtyWordList:
+            mmguero.eprint("No profanity detected")
+            return
+
+        count = len(self.naughtyWordList)
+        if self.showWords == "clean":
+            word = "word" if count == 1 else "words"
+            mmguero.eprint(f"{count} {word} detected")
+        elif self.showWords == "full":
+            mmguero.eprint("Profanity detected:")
+            for w in self.naughtyWordList:
+                start = w.get('start', 0)
+                end = w.get('end', 0)
+                mmguero.eprint(f'  - "{w["word"]}" ({self._fmt_time(start)} - {self._fmt_time(end)})')
+            word = "word" if count == 1 else "words"
+            mmguero.eprint(f"{count} {word} detected")
+
+    def _ai_detect_profanity(self):
+        """Use Groq chat API with structured outputs to detect profanity."""
+        import time as _time
+
+        if not self.groqApiKey:
+            raise ValueError("Groq API key required for AI detection")
+        if not self.wordList:
+            return
+
+        # Build numbered transcript text
+        transcript_lines = []
+        for i, w in enumerate(self.wordList):
+            transcript_lines.append(
+                f"[{i}] ({w.get('start', 0):.2f}-{w.get('end', 0):.2f}) {w.get('word', '')}"
+            )
+        transcript_text = "\n".join(transcript_lines)
+
+        # Get model and prompt (set from config via constructor)
+        model = self.aiDetectModel
+        prompt = self.aiDetectPrompt
+
+        # API call with retry logic
+        max_retries = 3
+        retry_delay = 1
+
+        for attempt in range(max_retries):
+            try:
+                response = requests.post(
+                    "https://api.groq.com/openai/v1/chat/completions",
+                    headers={
+                        "Authorization": f"Bearer {self.groqApiKey}",
+                        "Content-Type": "application/json",
+                    },
+                    json={
+                        "model": model,
+                        "messages": [
+                            {"role": "system", "content": prompt},
+                            {"role": "user", "content": transcript_text},
+                        ],
+                        "response_format": {
+                            "type": "json_schema",
+                            "json_schema": {
+                                "name": "profanity_detection",
+                                "strict": True,
+                                "schema": AI_DETECT_SCHEMA,
+                            }
+                        }
+                    },
+                    timeout=120,
+                )
+
+                if response.status_code == 429:
+                    if attempt < max_retries - 1:
+                        if self.debug:
+                            mmguero.eprint(f"AI detection rate limited, retrying in {retry_delay}s...")
+                        _time.sleep(retry_delay)
+                        retry_delay *= 2
+                        continue
+                    raise Exception("AI detection rate limit exceeded")
+
+                if response.status_code == 401:
+                    raise Exception("Invalid Groq API key for AI detection")
+
+                response.raise_for_status()
+
+                result = response.json()
+                content = result.get("choices", [{}])[0].get("message", {}).get("content", "{}")
+                parsed = json.loads(content)
+
+                profane_words = parsed.get("profane_words", [])
+                for item in profane_words:
+                    idx = item.get("index", -1)
+                    if 0 <= idx < len(self.wordList):
+                        self.wordList[idx]["scrub"] = True
+
+                if self.debug:
+                    mmguero.eprint(f"AI detection raw response: {content}")
+                    reasoning = parsed.get("reasoning", "")
+                    if reasoning:
+                        mmguero.eprint(f"AI reasoning: {reasoning}")
+                    mmguero.eprint(f"AI detection found {len(profane_words)} profane words")
+                    for item in profane_words:
+                        idx = item.get("index", -1)
+                        word = item.get("word", "?")
+                        mmguero.eprint(f"  [{idx}] \"{word}\" ({item.get('start', 0):.2f}-{item.get('end', 0):.2f})")
+
+                return
+
+            except requests.exceptions.Timeout:
+                if attempt < max_retries - 1:
+                    if self.debug:
+                        mmguero.eprint(f"AI detection timed out, retrying ({attempt + 1}/{max_retries})...")
+                    _time.sleep(retry_delay)
+                    retry_delay *= 2
+                else:
+                    raise Exception("AI detection request timed out")
+
+            except requests.exceptions.RequestException as e:
+                if attempt < max_retries - 1:
+                    if self.debug:
+                        mmguero.eprint(f"AI detection request failed: {e}, retrying ({attempt + 1}/{max_retries})...")
+                    _time.sleep(retry_delay)
+                    retry_delay *= 2
+                else:
+                    raise Exception(f"AI detection failed after {max_retries} retries: {e}")
+
     def _build_instrumental_filters(self):
         """Build FFmpeg filter complex for instrumental splicing
 
@@ -912,28 +1203,84 @@ class Plugger(object):
         if (self.forceDespiteTag is True) or (GetMonkeyplugTagged(self.inputFileSpec, debug=self.debug) is False):
             # Initialize progress (only when not in debug mode)
             progress = None
+            smooth_ticker = None
+            step_timings = None
+            timing_log = None
+            file_duration = 0.0
+
             if not self.debug:
-                # Determine first action
-                if not self.inputTranscript:
-                    initial_desc = "Transcribing"
-                else:
-                    initial_desc = "Processing"
-
-                progress = tqdm(
-                    total=1,  # Will be updated based on actual steps
-                    desc=initial_desc,
-                    unit="step",
-                    disable=False,
-                    bar_format='{l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}]',
+                # Load timing log and file duration for progress estimation
+                timing_log = load_timing_log()
+                file_duration = self._get_file_duration(self.inputFileSpec)
+                step_timings = {}
+
+                # Determine which steps will run
+                will_transcribe = not self.inputTranscript
+                will_extract = hasattr(self, 'autoGenerateMode') and self.autoGenerateMode
+                # encode always runs
+
+                # Check if we have estimates for all needed steps
+                est_transcribe = estimate_step_duration(timing_log, 'transcribe', file_duration) if will_transcribe else None
+                est_extract = estimate_step_duration(timing_log, 'extract', file_duration) if will_extract else None
+                est_encode = estimate_step_duration(timing_log, 'encode', file_duration)
+
+                can_smooth = (
+                    file_duration > 0
+                    and est_encode is not None
+                    and (not will_transcribe or est_transcribe is not None)
+                    and (not will_extract or est_extract is not None)
                 )
 
+                if can_smooth:
+                    # Smooth mode: single bar with total in seconds
+                    est_transcribe_val = est_transcribe or 0
+                    est_extract_val = est_extract or 0
+                    total_est = est_transcribe_val + est_extract_val + est_encode
+
+                    initial_desc = "Transcribing" if will_transcribe else "Processing"
+                    progress = tqdm(
+                        total=total_est,
+                        desc=initial_desc,
+                        unit="s",
+                        disable=False,
+                        bar_format='{l_bar}{bar}| {n:.0f}/{total:.0f}s [{elapsed}<{remaining}]',
+                    )
+
+                    smooth_ticker = _SmoothProgressTicker(progress)
+                    # Ticker will be started inside CreateCleanMuteList for each step
+
+                    # Pass context to CreateCleanMuteList
+                    self._smooth_ticker = smooth_ticker
+                    self._smooth_cumulative = 0.0
+                    self._smooth_transcribe_est = est_transcribe_val
+                    self._smooth_extract_est = est_extract_val
+                    self._step_timings = {}
+                    self._timing_log = timing_log
+                    self._timing_file_duration = file_duration
+                    self._will_transcribe = will_transcribe
+                else:
+                    # Fallback: step-based bar (existing behavior)
+                    initial_desc = "Transcribing" if not self.inputTranscript else "Processing"
+                    progress = tqdm(
+                        total=1,
+                        desc=initial_desc,
+                        unit="step",
+                        disable=False,
+                        bar_format='{l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}]',
+                    )
+
+                # Always pass timing context (even in step-based mode, for data collection)
+                self._step_timings = step_timings
+                self._timing_file_duration = file_duration
+                self._will_transcribe = not self.inputTranscript
+
             # Store progress reference for use in CreateCleanMuteList
             self._progress = progress
 
             self.CreateCleanMuteList()
 
-            # Update progress after CreateCleanMuteList
-            if progress:
+            # Update progress after CreateCleanMuteList (step-based mode only)
+            if progress and not smooth_ticker:
                 did_extraction = (
                     hasattr(self, 'autoGenerateMode') and
                     self.autoGenerateMode and
@@ -942,23 +1289,21 @@ class Plugger(object):
                 )
 
                 if not self.inputTranscript and not did_extraction:
-                    # Transcription done inside CreateCleanMuteList, no extraction
                     progress.update(1)
                     progress.total = 2
                     progress.set_description("Encoding")
                 elif not self.inputTranscript and did_extraction:
-                    # Both transcription and extraction handled inside CreateCleanMuteList
-                    # Just set description to encoding
                     progress.set_description("Encoding")
                 elif self.inputTranscript and did_extraction:
-                    # Extraction handled inside CreateCleanMuteList (no transcription update needed)
                     progress.total = 2
                     progress.set_description("Encoding")
                 else:
-                    # No transcription, no extraction - just encoding
                     progress.total = 1
                     progress.set_description("Encoding")
 
+            # Get cumulative position after CreateCleanMuteList (smooth mode)
+            cumulative = getattr(self, '_smooth_cumulative', 0.0) if smooth_ticker else 0
+
             # Handle instrumental mode differently
             if self.instrumentalMode:
                 # Use instrumental splicing
@@ -1030,6 +1375,15 @@ class Plugger(object):
                 ffmpegCmd.extend(self.aParams)
                 ffmpegCmd.append(self.outputFileSpec)
 
+            # Start encode step with timing
+            if progress and smooth_ticker:
+                est_encode = estimate_step_duration(timing_log, 'encode', file_duration) or 0
+                progress.set_description("Encoding")
+                smooth_ticker.start(cumulative, est_encode)
+            elif progress:
+                progress.set_description("Encoding")
+            encode_start = time.time()
+
             ffmpegResult, ffmpegOutput = mmguero.run_process(ffmpegCmd, stdout=True, stderr=True, debug=self.debug)
             if (ffmpegResult != 0) or (not os.path.isfile(self.outputFileSpec)):
                 mmguero.eprint(' '.join(mmguero.flatten(ffmpegCmd)))
@@ -1037,21 +1391,47 @@ class Plugger(object):
                 mmguero.eprint(ffmpegOutput)
                 raise ValueError(f"Could not process {self.inputFileSpec}")
 
+            # Record encode timing and finalize
+            actual_encode = time.time() - encode_start
+            if smooth_ticker:
+                smooth_ticker.stop()
+            if step_timings is not None:
+                step_timings['encode'] = (actual_encode, file_duration)
+
             SetMonkeyplugTag(self.outputFileSpec, debug=self.debug)
 
-            # Complete progress
+            # Complete progress and save timing data
             if progress:
-                progress.update(1)
+                if smooth_ticker:
+                    # Snap bar to total
+                    progress.n = progress.total
+                    progress.refresh()
+                else:
+                    progress.update(1)
                 progress.close()
 
+            # Update timing log with actual measurements (only on success)
+            if timing_log is not None and file_duration > 0:
+                for op, (wall_secs, audio_secs) in step_timings.items():
+                    update_timing_measurement(timing_log, op, wall_secs, audio_secs)
+                save_timing_log(timing_log)
+
         else:
             shutil.copyfile(self.inputFileSpec, self.outputFileSpec)
             if progress:
                 progress.close()
 
-        # Clean up progress reference
+        # Clean up progress references
         if hasattr(self, '_progress'):
             delattr(self, '_progress')
+        for attr in ('_smooth_ticker', '_smooth_cumulative', '_smooth_extract_est',
+                      '_smooth_transcribe_est', '_will_transcribe',
+                      '_step_timings', '_timing_log', '_timing_file_duration'):
+            if hasattr(self, attr):
+                delattr(self, attr)
+
+        # Print profanity detection summary (after progress bar is closed)
+        self._print_words_summary()
 
         return self.outputFileSpec
 
@@ -1093,6 +1473,11 @@ class VoskPlugger(Plugger):
         beepDropTransition=BEEP_DROPOUT_TRANSITION_DEFAULT,
         force=False,
         dbug=False,
+        showWords="clean",
+        detectMode="list",
+        groqApiKey=None,
+        aiDetectModel="openai/gpt-oss-20b",
+        aiDetectPrompt=AI_DETECT_PROMPT_DEFAULT,
     ):
         self.wavReadFramesChunk = wChunk
         self.modelPath = None
@@ -1140,6 +1525,11 @@ class VoskPlugger(Plugger):
             beepDropTransition=beepDropTransition,
             force=force,
             dbug=dbug,
+            showWords=showWords,
+            detectMode=detectMode,
+            groqApiKey=groqApiKey,
+            aiDetectModel=aiDetectModel,
+            aiDetectPrompt=aiDetectPrompt,
         )
 
         self.tmpWavFileSpec = self.inputFileParts[0] + ".wav"
@@ -1276,6 +1666,11 @@ class WhisperPlugger(Plugger):
         beepDropTransition=BEEP_DROPOUT_TRANSITION_DEFAULT,
         force=False,
         dbug=False,
+        showWords="clean",
+        detectMode="list",
+        groqApiKey=None,
+        aiDetectModel="openai/gpt-oss-20b",
+        aiDetectPrompt=AI_DETECT_PROMPT_DEFAULT,
     ):
         self.whisper = None
         self.model = None
@@ -1320,6 +1715,11 @@ class WhisperPlugger(Plugger):
             beepDropTransition=beepDropTransition,
             force=force,
             dbug=dbug,
+            showWords=showWords,
+            detectMode=detectMode,
+            groqApiKey=groqApiKey,
+            aiDetectModel=aiDetectModel,
+            aiDetectPrompt=aiDetectPrompt,
         )
 
         if self.debug:
@@ -1405,6 +1805,11 @@ class GroqPlugger(Plugger):
         verbose_level="",
         auto_generate=False,
         separation_padding=1.0,
+        showWords="clean",
+        detectMode="list",
+        groqApiKey=None,
+        aiDetectModel="openai/gpt-oss-20b",
+        aiDetectPrompt=AI_DETECT_PROMPT_DEFAULT,
     ):
         # Import groq_config - handle both relative and absolute imports
         try:
@@ -1448,6 +1853,11 @@ class GroqPlugger(Plugger):
             force=force,
             dbug=dbug,
             instrumentalFileSpec=instrumentalFileSpec,
+            showWords=showWords,
+            detectMode=detectMode,
+            groqApiKey=groqApiKey,
+            aiDetectModel=aiDetectModel,
+            aiDetectPrompt=aiDetectPrompt,
         )
 
         # Initialize auto-separation mode
@@ -1970,6 +2380,7 @@ def expand_and_detect_vocals(input_pattern, output_pattern, args, skip_detection
 # Config file loading
 MONKEYPLUG_CACHE_DIR = os.path.join(os.path.expanduser('~'), '.cache', 'monkeyplug')
 MONKEYPLUG_CONFIG_PATH = os.path.join(MONKEYPLUG_CACHE_DIR, 'config.json')
+MONKEYPLUG_TIMING_LOG_PATH = os.path.join(MONKEYPLUG_CACHE_DIR, 'timing_log.json')
 
 DEFAULT_CONFIG = {
     "pad_milliseconds": 10,
@@ -1977,6 +2388,10 @@ DEFAULT_CONFIG = {
     "pad_milliseconds_post": 10,
     "separation_padding": 1.0,
     "beep_hertz": BEEP_HERTZ_DEFAULT,
+    "show_words": "clean",
+    "detect_mode": "list",
+    "ai_detect_model": "openai/gpt-oss-20b",
+    "ai_detect_prompt": AI_DETECT_PROMPT_DEFAULT,
 }
 
 
@@ -2029,6 +2444,69 @@ def load_config_settings(debug=False):
     return dict(DEFAULT_CONFIG)
 
 
+###################################################################################################
+# Timing log for progress estimation
+def load_timing_log():
+    """Load historical timing data for progress bar estimation.
+
+    Returns:
+        dict: Timing log with per-operation running averages, or {} if unavailable.
+    """
+    if not os.path.isfile(MONKEYPLUG_TIMING_LOG_PATH):
+        return {}
+    try:
+        with open(MONKEYPLUG_TIMING_LOG_PATH, 'r') as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data
+    except (json.JSONDecodeError, IOError, ValueError):
+        pass
+    return {}
+
+
+def save_timing_log(timing_log):
+    """Save timing log atomically to disk."""
+    try:
+        os.makedirs(os.path.dirname(MONKEYPLUG_TIMING_LOG_PATH), exist_ok=True)
+        tmp_path = MONKEYPLUG_TIMING_LOG_PATH + '.tmp'
+        with open(tmp_path, 'w') as f:
+            json.dump(timing_log, f, indent=2)
+            f.write('\n')
+        os.replace(tmp_path, MONKEYPLUG_TIMING_LOG_PATH)
+    except (IOError, OSError):
+        pass  # Best-effort
+
+
+def estimate_step_duration(timing_log, operation, audio_seconds):
+    """Estimate wall-clock seconds for an operation based on historical data.
+
+    Returns:
+        float or None: Estimated seconds, or None if no data available.
+    """
+    entry = timing_log.get(operation)
+    if not entry or entry.get('run_count', 0) == 0:
+        return None
+    total_audio = entry.get('total_audio_seconds', 0)
+    if total_audio <= 0:
+        return None
+    rate = entry['total_wall_seconds'] / total_audio
+    return rate * audio_seconds
+
+
+def update_timing_measurement(timing_log, operation, wall_seconds, audio_seconds):
+    """Add a new timing measurement to the running averages."""
+    if operation not in timing_log:
+        timing_log[operation] = {
+            'total_audio_seconds': 0.0,
+            'total_wall_seconds': 0.0,
+            'run_count': 0,
+        }
+    entry = timing_log[operation]
+    entry['total_audio_seconds'] += audio_seconds
+    entry['total_wall_seconds'] += wall_seconds
+    entry['run_count'] += 1
+
+
 ###################################################################################################
 # RunMonkeyPlug
 def RunMonkeyPlug():
@@ -2099,6 +2577,22 @@ def RunMonkeyPlug():
     )
     parser.add_argument(
         "-w",
+        "--show-words",
+        dest="showWords",
+        type=str,
+        choices=["full", "clean", "none"],
+        default=config.get("show_words", "clean"),
+        help="Show detected profanity: full (list with timestamps), clean (count only), none (default: clean)",
+    )
+    parser.add_argument(
+        "--detect",
+        dest="detectMode",
+        type=str,
+        choices=["list", "ai", "both"],
+        default=config.get("detect_mode", "list"),
+        help="Profanity detection method: list (static list), ai (Groq LLM), both (default: list)",
+    )
+    parser.add_argument(
         "--swears",
         help=f"text file containing profanity (default: \"{SWEARS_FILENAME_DEFAULT}\")",
         default=os.path.join(script_path, SWEARS_FILENAME_DEFAULT),
@@ -2425,6 +2919,26 @@ def RunMonkeyPlug():
     else:
         sys.tracebacklimit = 0
 
+    # Load Groq API key for AI detection (needed for all modes if --detect ai|both)
+    if args.detectMode in ("ai", "both"):
+        try:
+            from monkeyplug.groq_config import load_groq_api_key
+        except ImportError:
+            from .groq_config import load_groq_api_key
+        if not args.groqApiKey:
+            args.groqApiKey = load_groq_api_key(None, debug=args.debug)
+        if not args.groqApiKey:
+            mmguero.eprint("Groq API key required for --detect ai or --detect both")
+            mmguero.eprint("Provide via --groq-api-key, GROQ_API_KEY env var, ~/.groq/config.json, or ./.groq_key")
+            sys.exit(1)
+    elif args.speechRecMode == SPEECH_REC_MODE_GROQ and not args.groqApiKey:
+        # Load key for Groq STT mode too (existing behavior)
+        try:
+            from monkeyplug.groq_config import load_groq_api_key
+        except ImportError:
+            from .groq_config import load_groq_api_key
+        args.groqApiKey = load_groq_api_key(None, debug=args.debug)
+
     # Set default output pattern if not specified: <input>_clean.<ext>
     if not args.output:
         input_base, input_ext = os.path.splitext(args.input)
@@ -2682,6 +3196,11 @@ def RunMonkeyPlug():
                 verbose_level=args_copy.verbose_level if hasattr(args_copy, 'verbose_level') else "",
                 auto_generate=file_auto_generate,
                 separation_padding=args_copy.separationPadding,
+                showWords=args_copy.showWords,
+                detectMode=args_copy.detectMode,
+                groqApiKey=args_copy.groqApiKey,
+                aiDetectModel=config.get("ai_detect_model", "openai/gpt-oss-20b"),
+                aiDetectPrompt=config.get("ai_detect_prompt", AI_DETECT_PROMPT_DEFAULT),
             )
 
             print(plug.EncodeCleanAudio())
@@ -2888,6 +3407,11 @@ def RunMonkeyPlug():
             beepDropTransition=args.beepDropTransition,
             force=args.forceDespiteTag,
             dbug=args.debug,
+            showWords=args.showWords,
+            detectMode=args.detectMode,
+            groqApiKey=args.groqApiKey,
+            aiDetectModel=config.get("ai_detect_model", "openai/gpt-oss-20b"),
+            aiDetectPrompt=config.get("ai_detect_prompt", AI_DETECT_PROMPT_DEFAULT),
         )
 
     elif args.speechRecMode == SPEECH_REC_MODE_WHISPER:
@@ -2919,6 +3443,11 @@ def RunMonkeyPlug():
             beepDropTransition=args.beepDropTransition,
             force=args.forceDespiteTag,
             dbug=args.debug,
+            showWords=args.showWords,
+            detectMode=args.detectMode,
+            groqApiKey=args.groqApiKey,
+            aiDetectModel=config.get("ai_detect_model", "openai/gpt-oss-20b"),
+            aiDetectPrompt=config.get("ai_detect_prompt", AI_DETECT_PROMPT_DEFAULT),
         )
 
     elif args.speechRecMode == SPEECH_REC_MODE_GROQ:
@@ -2952,6 +3481,11 @@ def RunMonkeyPlug():
             verbose_level=args.verbose_level if hasattr(args, 'verbose_level') else "",
             auto_generate=auto_generate,
             separation_padding=args.separationPadding,
+            showWords=args.showWords,
+            detectMode=args.detectMode,
+            groqApiKey=args.groqApiKey,
+            aiDetectModel=config.get("ai_detect_model", "openai/gpt-oss-20b"),
+            aiDetectPrompt=config.get("ai_detect_prompt", AI_DETECT_PROMPT_DEFAULT),
         )
     else:
         raise ValueError(f"Unsupported speech recognition engine {args.speechRecMode}")