agentvibes 5.2.0 → 5.3.0

package/.claude/hooks/piper-multispeaker-registry.sh

@@ -1,171 +1,171 @@
-#!/usr/bin/env bash
-#
-# File: .claude/hooks/piper-multispeaker-registry.sh
-#
-# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
-# Website: https://agentvibes.org
-# Repository: https://github.com/paulpreibisch/AgentVibes
-#
-# Co-created by Paul Preibisch with Claude AI
-# Copyright (c) 2025 Paul Preibisch
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
-# express or implied, including but not limited to the warranties of
-# merchantability, fitness for a particular purpose and noninfringement.
-# In no event shall the authors or copyright holders be liable for any claim,
-# damages or other liability, whether in an action of contract, tort or
-# otherwise, arising from, out of or in connection with the software or the
-# use or other dealings in the software.
-#
-# ---
-#
-# @fileoverview Multi-Speaker Voice Registry - Maps speaker names to ONNX models and speaker IDs
-# @context Enables individual speaker selection from multi-speaker Piper models (e.g., 16Speakers)
-# @architecture Static registry mapping speaker names to model files and numeric speaker IDs
-# @dependencies piper-voice-manager.sh (voice storage), play-tts-piper.sh (TTS with speaker ID)
-# @entrypoints Sourced by voice-manager.sh for multi-speaker voice switching
-# @patterns Registry pattern, speaker ID mapping, model-to-speaker association
-# @related voice-manager.sh, play-tts-piper.sh, 16Speakers.onnx.json (speaker_id_map)
-#
-
-# Bash 3.2 compatible lowercase function (macOS ships with bash 3.2)
-# ${var,,} syntax requires bash 4.0+
-_to_lower() {
-  echo "$1" | tr '[:upper:]' '[:lower:]'
-}
-
-# Registry of multi-speaker models and their speaker names
-# Format: "SpeakerName:model_file:speaker_id:description"
-#
-# 16Speakers Model (12 US + 4 UK voices):
-# Source: LibriVox Public Domain recordings
-# Model: 16Speakers.onnx (77MB)
-#
-MULTISPEAKER_VOICES=(
-  # US English Speakers (0-11)
-  "Cori_Samuel:16Speakers:0:US English Female"
-  "Kara_Shallenberg:16Speakers:1:US English Female"
-  "Kristin_Hughes:16Speakers:2:US English Female"
-  "Maria_Kasper:16Speakers:3:US English Female"
-  "Mike_Pelton:16Speakers:4:US English Male"
-  "Mark_Nelson:16Speakers:5:US English Male"
-  "Michael_Scherer:16Speakers:6:US English Male"
-  "James_K_White:16Speakers:7:US English Male"
-  "Rose_Ibex:16Speakers:8:US English Female"
-  "progressingamerica:16Speakers:9:US English Male"
-  "Steve_C:16Speakers:10:US English Male"
-  "Owlivia:16Speakers:11:US English Female"
-
-  # UK English Speakers (12-15)
-  "Paul_Hampton:16Speakers:12:UK English Male"
-  "Jennifer_Dorr:16Speakers:13:UK English Female"
-  "Emily_Cripps:16Speakers:14:UK English Female"
-  "Martin_Clifton:16Speakers:15:UK English Male"
-)
-
-# @function get_multispeaker_info
-# @intent Get model and speaker ID for a speaker name
-# @why Enables users to select individual speakers from multi-speaker models by name
-# @param $1 {string} speaker_name - Speaker name (e.g., "Cori_Samuel", "Rose_Ibex")
-# @returns Echoes "model:speaker_id" (e.g., "16Speakers:0") to stdout
-# @exitcode 0=speaker found, 1=speaker not found
-# @sideeffects None (read-only lookup)
-# @edgecases Case-insensitive matching
-# @calledby voice-manager.sh switch command
-# @calls None (pure bash array iteration)
-get_multispeaker_info() {
-  local speaker_name="$1"
-  for entry in "${MULTISPEAKER_VOICES[@]}"; do
-    name="${entry%%:*}"
-    rest="${entry#*:}"
-    model="${rest%%:*}"
-    rest="${rest#*:}"
-    speaker_id="${rest%%:*}"
-
-    if [[ "$(_to_lower "$name")" == "$(_to_lower "$speaker_name")" ]]; then
-      echo "$model:$speaker_id"
-      return 0
-    fi
-  done
-  return 1
-}
-
-# @function list_multispeaker_voices
-# @intent Display all available multi-speaker voices with descriptions
-# @why Help users discover individual speakers within multi-speaker models
-# @param None
-# @returns None
-# @exitcode Always 0
-# @sideeffects Writes formatted list to stdout
-# @edgecases None
-# @calledby voice-manager.sh list command, /agent-vibes:list
-# @calls None (pure bash array iteration)
-list_multispeaker_voices() {
-  echo "🎭 Multi-Speaker Voices (16Speakers Model):"
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-  local current_model=""
-  for entry in "${MULTISPEAKER_VOICES[@]}"; do
-    name="${entry%%:*}"
-    rest="${entry#*:}"
-    model="${rest%%:*}"
-    rest="${rest#*:}"
-    speaker_id="${rest%%:*}"
-    description="${rest#*:}"
-
-    # Print section header when model changes
-    if [[ "$model" != "$current_model" ]]; then
-      if [[ -n "$current_model" ]]; then
-        echo ""
-      fi
-      echo "  Model: $model.onnx"
-      current_model="$model"
-    fi
-
-    echo "    • $name (ID: $speaker_id) - $description"
-  done
-
-  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  echo ""
-  echo "Usage: /agent-vibes:switch Cori_Samuel"
-  echo "       /agent-vibes:switch Rose_Ibex"
-}
-
-# @function get_multispeaker_description
-# @intent Get description for a speaker name
-# @why Provide user-friendly info about speaker characteristics
-# @param $1 {string} speaker_name - Speaker name
-# @returns Echoes description (e.g., "US English Female") to stdout
-# @exitcode 0=speaker found, 1=speaker not found
-# @sideeffects None (read-only lookup)
-# @edgecases Case-insensitive matching
-# @calledby voice-manager.sh switch command (for confirmation message)
-# @calls None (pure bash array iteration)
-get_multispeaker_description() {
-  local speaker_name="$1"
-  for entry in "${MULTISPEAKER_VOICES[@]}"; do
-    name="${entry%%:*}"
-    rest="${entry#*:}"
-    rest="${rest#*:}"
-    rest="${rest#*:}"
-    description="${rest}"
-
-    if [[ "$(_to_lower "$name")" == "$(_to_lower "$speaker_name")" ]]; then
-      echo "$description"
-      return 0
-    fi
-  done
-  return 1
-}
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/piper-multispeaker-registry.sh
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DISCLAIMER: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+# In no event shall the authors or copyright holders be liable for any claim,
+# damages or other liability, whether in an action of contract, tort or
+# otherwise, arising from, out of or in connection with the software or the
+# use or other dealings in the software.
+#
+# ---
+#
+# @fileoverview Multi-Speaker Voice Registry - Maps speaker names to ONNX models and speaker IDs
+# @context Enables individual speaker selection from multi-speaker Piper models (e.g., 16Speakers)
+# @architecture Static registry mapping speaker names to model files and numeric speaker IDs
+# @dependencies piper-voice-manager.sh (voice storage), play-tts-piper.sh (TTS with speaker ID)
+# @entrypoints Sourced by voice-manager.sh for multi-speaker voice switching
+# @patterns Registry pattern, speaker ID mapping, model-to-speaker association
+# @related voice-manager.sh, play-tts-piper.sh, 16Speakers.onnx.json (speaker_id_map)
+#
+
+# Bash 3.2 compatible lowercase function (macOS ships with bash 3.2)
+# ${var,,} syntax requires bash 4.0+
+_to_lower() {
+  echo "$1" | tr '[:upper:]' '[:lower:]'
+}
+
+# Registry of multi-speaker models and their speaker names
+# Format: "SpeakerName:model_file:speaker_id:description"
+#
+# 16Speakers Model (12 US + 4 UK voices):
+# Source: LibriVox Public Domain recordings
+# Model: 16Speakers.onnx (77MB)
+#
+MULTISPEAKER_VOICES=(
+  # US English Speakers (0-11)
+  "Cori_Samuel:16Speakers:0:US English Female"
+  "Kara_Shallenberg:16Speakers:1:US English Female"
+  "Kristin_Hughes:16Speakers:2:US English Female"
+  "Maria_Kasper:16Speakers:3:US English Female"
+  "Mike_Pelton:16Speakers:4:US English Male"
+  "Mark_Nelson:16Speakers:5:US English Male"
+  "Michael_Scherer:16Speakers:6:US English Male"
+  "James_K_White:16Speakers:7:US English Male"
+  "Rose_Ibex:16Speakers:8:US English Female"
+  "progressingamerica:16Speakers:9:US English Male"
+  "Steve_C:16Speakers:10:US English Male"
+  "Owlivia:16Speakers:11:US English Female"
+
+  # UK English Speakers (12-15)
+  "Paul_Hampton:16Speakers:12:UK English Male"
+  "Jennifer_Dorr:16Speakers:13:UK English Female"
+  "Emily_Cripps:16Speakers:14:UK English Female"
+  "Martin_Clifton:16Speakers:15:UK English Male"
+)
+
+# @function get_multispeaker_info
+# @intent Get model and speaker ID for a speaker name
+# @why Enables users to select individual speakers from multi-speaker models by name
+# @param $1 {string} speaker_name - Speaker name (e.g., "Cori_Samuel", "Rose_Ibex")
+# @returns Echoes "model:speaker_id" (e.g., "16Speakers:0") to stdout
+# @exitcode 0=speaker found, 1=speaker not found
+# @sideeffects None (read-only lookup)
+# @edgecases Case-insensitive matching
+# @calledby voice-manager.sh switch command
+# @calls None (pure bash array iteration)
+get_multispeaker_info() {
+  local speaker_name="$1"
+  for entry in "${MULTISPEAKER_VOICES[@]}"; do
+    name="${entry%%:*}"
+    rest="${entry#*:}"
+    model="${rest%%:*}"
+    rest="${rest#*:}"
+    speaker_id="${rest%%:*}"
+
+    if [[ "$(_to_lower "$name")" == "$(_to_lower "$speaker_name")" ]]; then
+      echo "$model:$speaker_id"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# @function list_multispeaker_voices
+# @intent Display all available multi-speaker voices with descriptions
+# @why Help users discover individual speakers within multi-speaker models
+# @param None
+# @returns None
+# @exitcode Always 0
+# @sideeffects Writes formatted list to stdout
+# @edgecases None
+# @calledby voice-manager.sh list command, /agent-vibes:list
+# @calls None (pure bash array iteration)
+list_multispeaker_voices() {
+  echo "🎭 Multi-Speaker Voices (16Speakers Model):"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  local current_model=""
+  for entry in "${MULTISPEAKER_VOICES[@]}"; do
+    name="${entry%%:*}"
+    rest="${entry#*:}"
+    model="${rest%%:*}"
+    rest="${rest#*:}"
+    speaker_id="${rest%%:*}"
+    description="${rest#*:}"
+
+    # Print section header when model changes
+    if [[ "$model" != "$current_model" ]]; then
+      if [[ -n "$current_model" ]]; then
+        echo ""
+      fi
+      echo "  Model: $model.onnx"
+      current_model="$model"
+    fi
+
+    echo "    • $name (ID: $speaker_id) - $description"
+  done
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+  echo "Usage: /agent-vibes:switch Cori_Samuel"
+  echo "       /agent-vibes:switch Rose_Ibex"
+}
+
+# @function get_multispeaker_description
+# @intent Get description for a speaker name
+# @why Provide user-friendly info about speaker characteristics
+# @param $1 {string} speaker_name - Speaker name
+# @returns Echoes description (e.g., "US English Female") to stdout
+# @exitcode 0=speaker found, 1=speaker not found
+# @sideeffects None (read-only lookup)
+# @edgecases Case-insensitive matching
+# @calledby voice-manager.sh switch command (for confirmation message)
+# @calls None (pure bash array iteration)
+get_multispeaker_description() {
+  local speaker_name="$1"
+  for entry in "${MULTISPEAKER_VOICES[@]}"; do
+    name="${entry%%:*}"
+    rest="${entry#*:}"
+    rest="${rest#*:}"
+    rest="${rest#*:}"
+    description="${rest}"
+
+    if [[ "$(_to_lower "$name")" == "$(_to_lower "$speaker_name")" ]]; then
+      echo "$description"
+      return 0
+    fi
+  done
+  return 1
+}

package/.claude/hooks/play-tts-enhanced.sh

@@ -1,105 +1,105 @@
-#!/usr/bin/env bash
-#
-# File: .claude/hooks/play-tts-enhanced.sh
-#
-# AgentVibes - Enhanced TTS with Background Music and Effects
-# Generates TTS, applies effects, mixes background, plays ONCE (no echo)
-#
-# Usage: play-tts-enhanced.sh "text to speak" [agent_name] [voice_override]
-#
-# Environment:
-#   AGENTVIBES_PARTY_MODE=true  - Use room ambiance background (_party_mode config)
-#
-
-set -euo pipefail
-export LC_ALL=C
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-TEXT="${1:-}"
-AGENT_NAME="${2:-default}"
-VOICE_OVERRIDE="${3:-}"
-
-if [[ -z "$TEXT" ]]; then
-    echo "Usage: $0 \"text to speak\" [agent_name] [voice_override]" >&2
-    exit 1
-fi
-
-# Determine which config to use
-CONFIG_KEY="$AGENT_NAME"
-if [[ "${AGENTVIBES_PARTY_MODE:-false}" == "true" ]]; then
-    CONFIG_KEY="_party_mode"
-fi
-
-# ---------------------------------------------------------------------------
-# Per-agent profile overrides (from bmad-voice-map.json via bmad-speak.sh)
-# If AGENTVIBES_AGENT_PROFILE is set and the file exists, apply reverb/personality/music
-# overrides by temporarily setting effects-manager config for this agent
-AGENT_PROFILE="${AGENTVIBES_AGENT_PROFILE:-}"
-
-if [[ -n "$AGENT_PROFILE" ]] && [[ -f "$AGENT_PROFILE" ]]; then
-    # Read profile fields using node (reliable JSON parsing)
-    # SECURITY: Pass values via env vars to prevent shell injection
-    _PROFILE_REVERB=$(_APFILE="$AGENT_PROFILE" node -e "try{const p=JSON.parse(require('fs').readFileSync(process.env._APFILE,'utf8'));process.stdout.write(p.reverbPreset||'')}catch{}" 2>/dev/null || true)
-    _PROFILE_MUSIC_TRACK=$(_APFILE="$AGENT_PROFILE" node -e "try{const p=JSON.parse(require('fs').readFileSync(process.env._APFILE,'utf8'));process.stdout.write(p.backgroundMusic?.track||'')}catch{}" 2>/dev/null || true)
-    _PROFILE_MUSIC_VOL=$(_APFILE="$AGENT_PROFILE" node -e "try{const p=JSON.parse(require('fs').readFileSync(process.env._APFILE,'utf8'));process.stdout.write(String(p.backgroundMusic?.volume||''))}catch{}" 2>/dev/null || true)
-
-    # Apply per-agent reverb via effects-manager (scoped to this agent's config key)
-    if [[ -n "$_PROFILE_REVERB" ]] && [[ -f "$SCRIPT_DIR/effects-manager.sh" ]]; then
-        bash "$SCRIPT_DIR/effects-manager.sh" set-reverb "$_PROFILE_REVERB" "$CONFIG_KEY" 2>/dev/null || true
-    fi
-
-    # Override background music track/volume for this invocation via env vars
-    if [[ -n "$_PROFILE_MUSIC_TRACK" ]]; then
-        export AGENTVIBES_BG_TRACK="$_PROFILE_MUSIC_TRACK"
-    fi
-    if [[ -n "$_PROFILE_MUSIC_VOL" ]]; then
-        export AGENTVIBES_BG_VOLUME="$_PROFILE_MUSIC_VOL"
-    fi
-fi
-
-# Step 1: Generate TTS WITHOUT playback
-export AGENTVIBES_NO_PLAYBACK=true
-export AGENTVIBES_WAV_OUTPATH="${XDG_RUNTIME_DIR:-/tmp}/agentvibes-last-wav-$$.txt"
-
-# Cleanup temp outpath file on exit
-trap 'rm -f "$AGENTVIBES_WAV_OUTPATH"' EXIT
-bash "$SCRIPT_DIR/play-tts.sh" "$TEXT" "$VOICE_OVERRIDE"
-
-# Read the generated file path (written by play-tts-piper.sh via AGENTVIBES_WAV_OUTPATH)
-GENERATED_FILE=""
-if [[ -f "$AGENTVIBES_WAV_OUTPATH" ]]; then
-    GENERATED_FILE=$(cat "$AGENTVIBES_WAV_OUTPATH")
-    rm -f "$AGENTVIBES_WAV_OUTPATH"
-fi
-unset AGENTVIBES_WAV_OUTPATH
-
-if [[ -z "$GENERATED_FILE" ]] || [[ ! -f "$GENERATED_FILE" ]]; then
-    echo "Error: Could not find generated audio file" >&2
-    exit 1
-fi
-
-# Step 2: Process with effects and background
-PROCESSED_FILE="${GENERATED_FILE%.wav}-enhanced.wav"
-
-if [[ -f "$SCRIPT_DIR/audio-processor.sh" ]]; then
-    "$SCRIPT_DIR/audio-processor.sh" "$GENERATED_FILE" "$CONFIG_KEY" "$PROCESSED_FILE" 2>/dev/null || {
-        # Fallback to original if processing fails
-        PROCESSED_FILE="$GENERATED_FILE"
-    }
-else
-    PROCESSED_FILE="$GENERATED_FILE"
-fi
-
-# Step 3: Play the processed audio ONCE
-if [[ -f "$PROCESSED_FILE" ]]; then
-    if [[ "$(uname -s)" == "Darwin" ]]; then
-        afplay "$PROCESSED_FILE" >/dev/null 2>&1 &
-    else
-        (mpv "$PROCESSED_FILE" || aplay "$PROCESSED_FILE" || paplay "$PROCESSED_FILE") >/dev/null 2>&1 &
-    fi
-    echo "🎵 Enhanced audio: $PROCESSED_FILE"
-else
-    echo "Error: Processed file not found" >&2
-    exit 1
-fi
+#!/usr/bin/env bash
+#
+# File: .claude/hooks/play-tts-enhanced.sh
+#
+# AgentVibes - Enhanced TTS with Background Music and Effects
+# Generates TTS, applies effects, mixes background, plays ONCE (no echo)
+#
+# Usage: play-tts-enhanced.sh "text to speak" [agent_name] [voice_override]
+#
+# Environment:
+#   AGENTVIBES_PARTY_MODE=true  - Use room ambiance background (_party_mode config)
+#
+
+set -euo pipefail
+export LC_ALL=C
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+TEXT="${1:-}"
+AGENT_NAME="${2:-default}"
+VOICE_OVERRIDE="${3:-}"
+
+if [[ -z "$TEXT" ]]; then
+    echo "Usage: $0 \"text to speak\" [agent_name] [voice_override]" >&2
+    exit 1
+fi
+
+# Determine which config to use
+CONFIG_KEY="$AGENT_NAME"
+if [[ "${AGENTVIBES_PARTY_MODE:-false}" == "true" ]]; then
+    CONFIG_KEY="_party_mode"
+fi
+
+# ---------------------------------------------------------------------------
+# Per-agent profile overrides (from bmad-voice-map.json via bmad-speak.sh)
+# If AGENTVIBES_AGENT_PROFILE is set and the file exists, apply reverb/personality/music
+# overrides by temporarily setting effects-manager config for this agent
+AGENT_PROFILE="${AGENTVIBES_AGENT_PROFILE:-}"
+
+if [[ -n "$AGENT_PROFILE" ]] && [[ -f "$AGENT_PROFILE" ]]; then
+    # Read profile fields using node (reliable JSON parsing)
+    # SECURITY: Pass values via env vars to prevent shell injection
+    _PROFILE_REVERB=$(_APFILE="$AGENT_PROFILE" node -e "try{const p=JSON.parse(require('fs').readFileSync(process.env._APFILE,'utf8'));process.stdout.write(p.reverbPreset||'')}catch{}" 2>/dev/null || true)
+    _PROFILE_MUSIC_TRACK=$(_APFILE="$AGENT_PROFILE" node -e "try{const p=JSON.parse(require('fs').readFileSync(process.env._APFILE,'utf8'));process.stdout.write(p.backgroundMusic?.track||'')}catch{}" 2>/dev/null || true)
+    _PROFILE_MUSIC_VOL=$(_APFILE="$AGENT_PROFILE" node -e "try{const p=JSON.parse(require('fs').readFileSync(process.env._APFILE,'utf8'));process.stdout.write(String(p.backgroundMusic?.volume||''))}catch{}" 2>/dev/null || true)
+
+    # Apply per-agent reverb via effects-manager (scoped to this agent's config key)
+    if [[ -n "$_PROFILE_REVERB" ]] && [[ -f "$SCRIPT_DIR/effects-manager.sh" ]]; then
+        bash "$SCRIPT_DIR/effects-manager.sh" set-reverb "$_PROFILE_REVERB" "$CONFIG_KEY" 2>/dev/null || true
+    fi
+
+    # Override background music track/volume for this invocation via env vars
+    if [[ -n "$_PROFILE_MUSIC_TRACK" ]]; then
+        export AGENTVIBES_BG_TRACK="$_PROFILE_MUSIC_TRACK"
+    fi
+    if [[ -n "$_PROFILE_MUSIC_VOL" ]]; then
+        export AGENTVIBES_BG_VOLUME="$_PROFILE_MUSIC_VOL"
+    fi
+fi
+
+# Step 1: Generate TTS WITHOUT playback
+export AGENTVIBES_NO_PLAYBACK=true
+export AGENTVIBES_WAV_OUTPATH="${XDG_RUNTIME_DIR:-/tmp}/agentvibes-last-wav-$$.txt"
+
+# Cleanup temp outpath file on exit
+trap 'rm -f "$AGENTVIBES_WAV_OUTPATH"' EXIT
+bash "$SCRIPT_DIR/play-tts.sh" "$TEXT" "$VOICE_OVERRIDE"
+
+# Read the generated file path (written by play-tts-piper.sh via AGENTVIBES_WAV_OUTPATH)
+GENERATED_FILE=""
+if [[ -f "$AGENTVIBES_WAV_OUTPATH" ]]; then
+    GENERATED_FILE=$(cat "$AGENTVIBES_WAV_OUTPATH")
+    rm -f "$AGENTVIBES_WAV_OUTPATH"
+fi
+unset AGENTVIBES_WAV_OUTPATH
+
+if [[ -z "$GENERATED_FILE" ]] || [[ ! -f "$GENERATED_FILE" ]]; then
+    echo "Error: Could not find generated audio file" >&2
+    exit 1
+fi
+
+# Step 2: Process with effects and background
+PROCESSED_FILE="${GENERATED_FILE%.wav}-enhanced.wav"
+
+if [[ -f "$SCRIPT_DIR/audio-processor.sh" ]]; then
+    "$SCRIPT_DIR/audio-processor.sh" "$GENERATED_FILE" "$CONFIG_KEY" "$PROCESSED_FILE" 2>/dev/null || {
+        # Fallback to original if processing fails
+        PROCESSED_FILE="$GENERATED_FILE"
+    }
+else
+    PROCESSED_FILE="$GENERATED_FILE"
+fi
+
+# Step 3: Play the processed audio ONCE
+if [[ -f "$PROCESSED_FILE" ]]; then
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+        afplay "$PROCESSED_FILE" >/dev/null 2>&1 &
+    else
+        (mpv "$PROCESSED_FILE" || aplay "$PROCESSED_FILE" || paplay "$PROCESSED_FILE") >/dev/null 2>&1 &
+    fi
+    echo "🎵 Enhanced audio: $PROCESSED_FILE"
+else
+    echo "Error: Processed file not found" >&2
+    exit 1
+fi