agentvibes 3.5.8 → 3.5.10-alpha.0

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260212
+20260214

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

@@ -77,7 +77,7 @@ elif [[ -f "$GLOBAL_MUTE_FILE" ]]; then
   exit 0
 fi
 
-TEXT="$1"
+TEXT="${1:-}"
 VOICE_OVERRIDE="${2:-}"  # Optional: voice name or ID
 
 # Security: Validate inputs

package/README.md

@@ -11,7 +11,7 @@
 [![Publish](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml/badge.svg)](https://github.com/paulpreibisch/AgentVibes/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v3.5.8
+**Author**: Paul Preibisch ([@997Fire](https://x.com/997Fire)) | **Version**: v3.5.10-alpha.0
 
 ---
 
@@ -97,7 +97,7 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 - [📱 Android/Termux](#-quick-setup-android--termux-claude-code-on-your-phone) - Run Claude Code on your phone
 - [📋 Prerequisites](#-prerequisites) - What you actually need (Node.js + optional tools)
 - [✨ What is AgentVibes?](#-what-is-agentvibes) - Overview & key features
-- [📰 Latest Release](#-latest-release) - v3.5.8 Security & UX + v3.5.5 Native Windows Support
+- [📰 Latest Release](#-latest-release) - v3.5.10-alpha.0 (Alpha) with Soprano Detection Fixes + v3.5.5 Native Windows Support
 - [🪟 Windows Setup Guide for Claude Desktop](mcp-server/WINDOWS_SETUP.md) - Complete Windows installation with WSL & Python
 
 ### AgentVibes MCP (Natural Language Control)
@@ -134,6 +134,7 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 - [🗑️ Uninstalling](#️-uninstalling) - Remove AgentVibes cleanly
 - [❓ FAQ](#-frequently-asked-questions-faq) - **NEW!** Common questions answered (git-lfs, MCP tokens, installation)
 - [🍎 macOS Testing](docs/macos-testing.md) - Automated testing on macOS with GitHub Actions
+- [🤗 Hugging Face Voice Models](docs/hugging-face-models.md) - Technical details on AI voice models
 - [🙏 Credits](#-credits) - Acknowledgments
 - [🤝 Contributing](#-contributing) - Show support
 
@@ -141,11 +142,18 @@ All 50+ Piper voices AgentVibes provides are sourced from Hugging Face's open-so
 
 ## 📰 Latest Release
 
-**[v3.5.8 - Security & Provider Validation](https://github.com/paulpreibisch/AgentVibes/releases/tag/v3.5.8)** 🛡️
+**[v3.5.10-alpha.0 - Soprano Detection Fixes & Features](https://github.com/paulpreibisch/AgentVibes/releases/tag/master)** (Alpha) 🛡️
 
-Critical security update: Fixed command injection vulnerabilities, HOME directory injection prevention, and path traversal protection. Soprano TTS installed via pipx now correctly detected. Enhanced provider detection messaging and debug logging.
+Critical fixes and new features:
+- Fixed Soprano TTS detection when installed via pipx
+- Fixed command injection vulnerabilities in provider validation
+- Eliminated code duplication between Soprano and Piper validators
+- Added custom music tracks support with preview functionality
+- Added personality emoji mapping for better visual recognition
+- Added pretext configuration for custom agent introductions
+- HOME directory injection prevention and path traversal protection maintained
 
-**Foundation Release:** [v3.5.5 - Native Windows Support](https://github.com/paulpreibisch/AgentVibes/releases/tag/v3.5.5) brings Windows support (Soprano, Piper, SAPI), background music (16 genre tracks), reverb/audio effects, and verbosity control. [See release notes](RELEASE_NOTES.md) for complete v3.5.5-3.5.8 history.
+**Foundation Release:** [v3.5.5 - Native Windows Support](https://github.com/paulpreibisch/AgentVibes/releases/tag/v3.5.9) brings Windows support (Soprano, Piper, SAPI), background music (16 genre tracks), reverb/audio effects, and verbosity control. [See release notes](RELEASE_NOTES.md) for complete v3.5.5-3.5.9 history.
 
 💡 **Tip:** If `npx agentvibes` shows an older version or missing commands, clear your npm cache: `npm cache clean --force && npx agentvibes@latest --help`
 
@@ -1467,6 +1475,9 @@ Both do the exact same thing - MCP is more convenient, slash commands are more t
 
 **Powered by:**
 - [Piper TTS](https://github.com/rhasspy/piper) - Free neural voices
+- [Soprano TTS](https://github.com/suno-ai/bark) - Ultra-fast neural TTS
+- **Windows SAPI** - Native Windows text-to-speech
+- **macOS Say** - Native macOS text-to-speech
 - [Claude Code](https://claude.com/claude-code) - AI coding assistant
 - Licensed under Apache 2.0
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "3.5.8",
+  "version": "3.5.10-alpha.0",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [
@@ -83,6 +83,8 @@
     "test:verbose": "AGENTVIBES_TEST_MODE=true bats -t test/unit/*.bats"
   },
   "dependencies": {
+    "@inquirer/search": "^3.1.3",
+    "agentvibes": "^3.5.9",
     "boxen": "^7.0.0",
     "chalk": "^5.0.0",
     "commander": "^10.0.0",

package/src/installer.js

@@ -48,6 +48,7 @@ import fsSync from 'node:fs';
 import { execSync, execFileSync, spawn } from 'node:child_process';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
+import search from '@inquirer/search';
 import figlet from 'figlet';
 import { detectBMAD } from './bmad-detector.js';
 import boxen from 'boxen';
@@ -77,6 +78,31 @@ const packageJson = JSON.parse(
 );
 const VERSION = packageJson.version;
 
+// Personality emoji mapping for quick visual recognition
+const personalityEmojis = {
+  'angry': '😠',
+  'annoying': '😤',
+  'crass': '🤬',
+  'dramatic': '🎭',
+  'dry-humor': '😐',
+  'flirty': '😘',
+  'funny': '😂',
+  'grandpa': '👴',
+  'millennial': '🙄',
+  'moody': '😒',
+  'none': '😊',
+  'normal': '😊',
+  'pirate': '🏴‍☠️',
+  'poetic': '📜',
+  'professional': '👔',
+  'rapper': '🎤',
+  'robot': '🤖',
+  'sarcastic': '😏',
+  'sassy': '💁',
+  'surfer-dude': '🏄',
+  'zen': '🧘'
+};
+
 // Validate Node.js executable is available (CLAUDE.md - early validation)
 if (!process.execPath) {
   console.error('❌ Error: Node.js executable path not found');
@@ -519,6 +545,159 @@ async function handleSystemDependenciesPage() {
   console.log(depsBoxen);
 }
 
+/**
+ * Validate and copy custom music track to .claude/audio/tracks directory
+ * @param {string} userFilePath - Path provided by user
+ * @param {string} tracksDir - Target directory for audio tracks
+ * @returns {Promise<string|null>} Filename if successful, null if cancelled
+ */
+async function handleCustomMusicTrack(userFilePath, tracksDir) {
+  try {
+    // Validate file exists and resolve path securely
+    const resolvedPath = path.resolve(userFilePath.trim());
+
+    if (!fsSync.existsSync(resolvedPath)) {
+      console.error(chalk.red('✗ File not found. Please check the path.'));
+      return null;
+    }
+
+    // Validate file extension (whitelist approach per CLAUDE.md)
+    const ext = path.extname(resolvedPath).toLowerCase();
+    const supportedFormats = ['.mp3', '.wav', '.ogg', '.m4a'];
+    if (!supportedFormats.includes(ext)) {
+      console.error(chalk.red('✗ Unsupported format. Use: .mp3, .wav, .ogg, or .m4a'));
+      return null;
+    }
+
+    // Verify file is within expected directory (prevent path traversal)
+    if (!resolvedPath.startsWith(path.resolve(process.env.HOME || process.env.USERPROFILE))) {
+      console.error(chalk.red('✗ File must be in your home directory or subdirectories.'));
+      return null;
+    }
+
+    // Get original filename and sanitize it
+    let originalFilename = path.basename(resolvedPath);
+    const sanitizedFilename = originalFilename.replace(/[^a-zA-Z0-9._-]/g, '_');
+
+    // Create tracks directory if needed
+    await fs.mkdir(tracksDir, { recursive: true });
+
+    // Copy file to tracks directory
+    const destPath = path.join(tracksDir, sanitizedFilename);
+    await fs.copyFile(resolvedPath, destPath);
+
+    return sanitizedFilename;
+  } catch (err) {
+    console.error(chalk.red(`✗ Error: ${err.message}`));
+    return null;
+  }
+}
+
+/**
+ * Load custom tracks from global registry
+ * @returns {Promise<Array>} Array of custom track objects {name, filename}
+ */
+async function loadCustomTracks() {
+  try {
+    const registryPath = path.join(process.env.HOME || process.env.USERPROFILE, '.agentvibes', 'custom-tracks.json');
+    if (fsSync.existsSync(registryPath)) {
+      const content = await fs.readFile(registryPath, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (err) {
+    // Silently fail - registry may not exist yet
+  }
+  return [];
+}
+
+/**
+ * Save custom tracks to global registry
+ * @param {Array} tracks - Array of custom track objects
+ */
+async function saveCustomTracks(tracks) {
+  try {
+    const registryDir = path.join(process.env.HOME || process.env.USERPROFILE, '.agentvibes');
+    await fs.mkdir(registryDir, { recursive: true });
+    const registryPath = path.join(registryDir, 'custom-tracks.json');
+    await fs.writeFile(registryPath, JSON.stringify(tracks, null, 2));
+  } catch (err) {
+    // Silently fail - non-critical
+  }
+}
+
+/**
+ * Preview audio track using available audio player
+ * @param {string} trackName - Name of the track file to preview
+ * @param {string} tracksDir - Directory containing audio tracks
+ * @returns {Promise<boolean>} True if preview was attempted, false if no audio tools available
+ */
+async function previewAudioTrack(trackName, tracksDir) {
+  const trackPath = path.join(tracksDir, trackName);
+
+  // Verify track exists
+  if (!fsSync.existsSync(trackPath)) {
+    console.log(chalk.yellow('⚠️  Track file not found'));
+    return false;
+  }
+
+  // Try available audio players in order of preference
+  const audioPlayers = ['ffplay', 'play', 'mpv'];
+  let playerAvailable = false;
+
+  for (const player of audioPlayers) {
+    try {
+      execSync(`which ${player}`, { stdio: 'ignore' });
+      playerAvailable = true;
+
+      console.log(chalk.cyan('▶  Playing preview (10 seconds)...'));
+
+      // Build appropriate command for each player
+      let playerArgs = [];
+      if (player === 'ffplay') {
+        playerArgs = ['-nodisp', '-autoexit', '-t', '10', '-volume', '30', trackPath];
+      } else if (player === 'play') {
+        playerArgs = [trackPath, 'trim', '0', '10'];
+      } else if (player === 'mpv') {
+        playerArgs = ['--no-video', '--duration=10', '--volume=30', trackPath];
+      }
+
+      // Spawn player process with safety timeout
+      const audioProcess = spawn(player, playerArgs, {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 12000 // 12 second timeout for safety
+      });
+
+      // Handle process completion
+      return new Promise((resolve) => {
+        const timeoutHandle = setTimeout(() => {
+          if (audioProcess && !audioProcess.killed) {
+            audioProcess.kill('SIGTERM');
+          }
+          resolve(true);
+        }, 11000); // 11 second timeout
+
+        audioProcess.on('close', () => {
+          clearTimeout(timeoutHandle);
+          resolve(true);
+        });
+
+        audioProcess.on('error', () => {
+          clearTimeout(timeoutHandle);
+          resolve(true);
+        });
+      });
+    } catch (err) {
+      // This player not available, try next
+      continue;
+    }
+  }
+
+  if (!playerAvailable) {
+    console.log(chalk.yellow('⚠️  Audio preview requires ffplay, sox (play), or mpv'));
+  }
+  return false;
+}
+
 /**
  * Collect all configuration answers through paginated question flow
  * @param {Object} options - Installation options (yes, pageOffset, totalPages)
@@ -530,6 +709,7 @@ async function collectConfiguration(options = {}) {
     piperPath: null,
     sshHost: null,
     defaultVoice: null,
+    pretext: '',
     personality: 'none',
     reverb: 'light',
     backgroundMusic: {
@@ -862,93 +1042,103 @@ async function collectConfiguration(options = {}) {
         value: '__back__'
       });
 
-      const { provider } = await inquirer.prompt([{
-        type: 'list',
-        name: 'provider',
-        message: chalk.yellow('Select TTS provider:'),
-        choices: providerChoices,
-        default: config.provider || (isNativeWindows() ? 'windows-piper' : (isMacOS ? 'macos' : 'piper'))
-      }]);
-
-      // Check if user wants to go back
-      if (provider === '__back__') {
-        return null;
-      }
-
-      // Validate provider installation before accepting selection
-      console.log(chalk.gray(`\n   Checking for ${getProviderDisplayName(provider)}...`));
-      const validation = await validateProvider(provider);
-
-      if (!validation.installed) {
-        const displayName = getProviderDisplayName(provider);
-        console.log(chalk.yellow(`\n⚠️  ${validation.message}`));
-
-        const { action } = await inquirer.prompt([{
+      // Provider selection loop - allows user to try different providers without going back
+      let providerSelected = false;
+      while (!providerSelected) {
+        const { provider } = await inquirer.prompt([{
           type: 'list',
-          name: 'action',
-          message: 'What would you like to do?',
-          choices: [
-            { name: chalk.green('Install now (recommended)'), value: 'install' },
-            { name: 'Choose a different provider', value: 'back' },
-            { name: 'I\'ll install it myself later', value: 'skip' }
-          ]
+          name: 'provider',
+          message: chalk.yellow('Select TTS provider:'),
+          choices: providerChoices,
+          default: config.provider || (isNativeWindows() ? 'windows-piper' : (isMacOS ? 'macos' : 'piper'))
         }]);
 
-        if (action === 'install') {
-          console.log(chalk.cyan(`\n📦 Installing ${displayName}...\n`));
-
-          // Use smart installation with fallbacks
-          const installResult = await attemptProviderInstallation(provider);
-
-          if (installResult.success && installResult.verified) {
-            // Installation succeeded AND verified
-            console.log(chalk.green(`\n✓ ${displayName} installed and verified!\n`));
-            console.log(chalk.gray(`   Method: ${installResult.command}`));
-            console.log(chalk.green(`   Status: Ready to use\n`));
-          } else if (installResult.success) {
-            // Installation command ran but verification failed
-            console.log(chalk.yellow(`\n⚠️  Installation command completed, but verification failed\n`));
-            console.log(chalk.gray(`   The installation may have been blocked by system protection (PEP 668).\n`));
-            console.log(chalk.cyan(`   Try one of these solutions:\n`));
-            console.log(chalk.gray(`   1. Use pipx (avoids system protection):\n      pipx install soprano-tts\n`));
-            console.log(chalk.gray(`   2. Create a virtual environment:\n      python3 -m venv ~/my-env\n      ~/my-env/bin/pip install soprano-tts\n`));
-
-            // Pause before returning to provider selection
-            await inquirer.prompt([{
-              type: 'confirm',
-              name: 'continue',
-              message: 'Press Enter to go back to provider selection',
-              default: true
-            }]);
-
-            return null; // Go back to provider selection
-          } else {
-            console.log(chalk.red(`\n❌ ${installResult.message}\n`));
+        // Check if user wants to go back to previous page
+        if (provider === '__back__') {
+          return null;
+        }
 
-            // Pause before returning to provider selection
-            await inquirer.prompt([{
-              type: 'confirm',
-              name: 'continue',
-              message: 'Press Enter to go back to provider selection',
-              default: true
-            }]);
+        // Validate provider installation before accepting selection
+        console.log(chalk.gray(`\n   Checking for ${getProviderDisplayName(provider)}...`));
+        const validation = await validateProvider(provider);
+
+        if (!validation.installed) {
+          const displayName = getProviderDisplayName(provider);
+          console.log(chalk.yellow(`\n⚠️  ${validation.message}`));
+
+          const { action } = await inquirer.prompt([{
+            type: 'list',
+            name: 'action',
+            message: 'What would you like to do?',
+            choices: [
+              { name: chalk.green('Install now (recommended)'), value: 'install' },
+              { name: 'Choose a different provider', value: 'back' },
+              { name: 'I\'ll install it myself later', value: 'skip' }
+            ]
+          }]);
 
-            return null; // Go back to provider selection
+          if (action === 'install') {
+            console.log(chalk.cyan(`\n📦 Installing ${displayName}...\n`));
+
+            // Use smart installation with fallbacks
+            const installResult = await attemptProviderInstallation(provider);
+
+            if (installResult.success && installResult.verified) {
+              // Installation succeeded AND verified
+              console.log(chalk.green(`\n✓ ${displayName} installed and verified!\n`));
+              console.log(chalk.gray(`   Method: ${installResult.command}`));
+              console.log(chalk.green(`   Status: Ready to use\n`));
+              config.provider = provider;
+              providerSelected = true; // Exit provider selection loop
+            } else if (installResult.success) {
+              // Installation command ran but verification failed
+              console.log(chalk.yellow(`\n⚠️  Installation command completed, but verification failed\n`));
+              console.log(chalk.gray(`   The installation may have been blocked by system protection (PEP 668).\n`));
+              console.log(chalk.cyan(`   Try one of these solutions:\n`));
+              console.log(chalk.gray(`   1. Use pipx (avoids system protection):\n      pipx install soprano-tts\n`));
+              console.log(chalk.gray(`   2. Create a virtual environment:\n      python3 -m venv ~/my-env\n      ~/my-env/bin/pip install soprano-tts\n`));
+
+              // Pause before returning to provider selection
+              await inquirer.prompt([{
+                type: 'confirm',
+                name: 'continue',
+                message: 'Press Enter to try a different provider',
+                default: true
+              }]);
+
+              // Loop back to provider selection
+              continue;
+            } else {
+              console.log(chalk.red(`\n❌ ${installResult.message}\n`));
+
+              // Pause before returning to provider selection
+              await inquirer.prompt([{
+                type: 'confirm',
+                name: 'continue',
+                message: 'Press Enter to try a different provider',
+                default: true
+              }]);
+
+              // Loop back to provider selection
+              continue;
+            }
+          } else if (action === 'back') {
+            // Loop back to provider selection to choose a different one
+            continue;
+          } else if (action === 'skip') {
+            console.log(chalk.yellow(`\n⚠️  No problem! You can set it up anytime with:\n   ${getProviderInstallCommand(provider)}\n`));
+            config.provider = provider;
+            providerSelected = true; // Exit provider selection loop
           }
-        } else if (action === 'back') {
-          // Go back to provider selection
-          return null;
-        } else if (action === 'skip') {
-          console.log(chalk.yellow(`\n⚠️  No problem! You can set it up anytime with:\n   ${getProviderInstallCommand(provider)}\n`));
+        } else {
+          // Provider detected and ready to use
+          const displayName = getProviderDisplayName(provider);
+          console.log(chalk.green(`\n✓ ${displayName} Detected and selected!\n`));
+          config.provider = provider;
+          providerSelected = true; // Exit provider selection loop
         }
-      } else {
-        // Provider detected and ready to use
-        const displayName = getProviderDisplayName(provider);
-        console.log(chalk.green(`\n✓ ${displayName} Detected and selected!\n`));
       }
 
-      config.provider = provider;
-
       // Handle special receiver mode for Termux
       if (config.provider === 'piper-receiver') {
         config.provider = 'piper';
@@ -1304,7 +1494,37 @@ async function collectConfiguration(options = {}) {
       }
 
     } else if (currentPage === 3) {
-      // Page 4: Personality Selection
+      // Page 4: Pretext and Personality Selection
+      console.log(boxen(
+        chalk.white('Customize your Agent\'s introduction!\n\n') +
+        chalk.gray('Add optional intro text that prefixes all TTS messages.\n') +
+        chalk.gray('Examples: "FireBot: ", "Agent: ", "🤖 Assistant: "\n\n') +
+        chalk.gray('You can change this anytime with: ') + chalk.cyan('/agent-vibes:set-pretext <text>'),
+        {
+          padding: 1,
+          margin: { top: 0, bottom: 0, left: 0, right: 0 },
+          borderStyle: 'round',
+          borderColor: 'gray',
+          width: 80
+        }
+      ));
+
+      // Pretext input
+      const { pretext } = await inquirer.prompt([{
+        type: 'input',
+        name: 'pretext',
+        message: chalk.yellow('Enter intro text (optional, press Enter to skip):'),
+        default: config.pretext || ''
+      }]);
+
+      config.pretext = pretext.trim();
+      if (config.pretext) {
+        console.log(chalk.green(`✓ Intro text set: "${config.pretext}"\n`));
+      } else {
+        console.log(chalk.gray('→ No intro text (messages will speak normally)\n'));
+      }
+
+      // Page 5: Personality Selection
       console.log(boxen(
         chalk.white('Give your Agent a personality!\n\n') +
         chalk.gray('Personalities add character and style to TTS responses.\n') +
@@ -1349,16 +1569,18 @@ async function collectConfiguration(options = {}) {
         personalities.sort((a, b) => a.name.localeCompare(b.name));
 
         // Add "none" as first option (default)
+        const noneEmoji = personalityEmojis['none'] || '✨';
         personalityChoices.push(
-          { name: chalk.green('none') + chalk.gray(' (Professional, no personality) - Recommended'), value: 'none' },
+          { name: noneEmoji + ' ' + chalk.green('none') + chalk.gray(' (Professional, no personality) - Recommended'), value: 'none' },
           new inquirer.Separator(chalk.gray('─'.repeat(60)))
         );
 
         // Add all other personalities
         for (const p of personalities) {
           if (p.name !== 'normal') { // Skip 'normal' as it's similar to 'none'
+            const emoji = personalityEmojis[p.name] || '✨';
             personalityChoices.push({
-              name: chalk.cyan(p.name) + chalk.gray(` - ${p.description}`),
+              name: emoji + ' ' + chalk.cyan(p.name) + chalk.gray(` - ${p.description}`),
               value: p.name
             });
           }
@@ -1377,14 +1599,23 @@ async function collectConfiguration(options = {}) {
         ];
       }
 
-      const { selectedPersonality } = await inquirer.prompt([{
-        type: 'list',
-        name: 'selectedPersonality',
-        message: chalk.yellow('Select your default personality:'),
-        choices: personalityChoices,
-        default: 'none',
+      // Use search prompt for keyboard navigation (type to filter)
+      const selectedPersonality = await search({
+        message: chalk.yellow('Select your default personality (type to search):'),
+        source: async (input) => {
+          // Filter personalityChoices based on input
+          if (!input) {
+            return personalityChoices;
+          }
+          return personalityChoices.filter(choice => {
+            // Check if choice is a Separator, if so skip it
+            if (!choice.value) return false;
+            return choice.value.toLowerCase().includes(input.toLowerCase()) ||
+                   (choice.name && choice.name.toLowerCase().includes(input.toLowerCase()));
+          });
+        },
         pageSize: 15
-      }]);
+      });
 
       if (selectedPersonality === '__back__') {
         currentPage--; // Go back to voice selection
@@ -1504,6 +1735,13 @@ async function collectConfiguration(options = {}) {
         console.log('');
         console.log(chalk.gray('🎼 Choose your default background music genre (you can change this anytime).'));
 
+        // Load custom tracks from registry
+        const customTracks = await loadCustomTracks();
+        const customTrackChoices = customTracks.map(track => ({
+          name: `📁 ${track.name}`,
+          value: track.filename
+        }));
+
         const trackChoices = [
           { name: '🎻 Soft Flamenco (Spanish guitar)', value: 'agentvibes_soft_flamenco_loop.mp3' },
           { name: '🎺 Bachata (Latin - Romantic guitar & bongos)', value: 'agent_vibes_bachata_v1_loop.mp3' },
@@ -1523,20 +1761,85 @@ async function collectConfiguration(options = {}) {
           { name: '🥁 Tabla Dream Pop (Indian percussion)', value: 'agent_vibes_tabla_dream_pop_v1_loop.mp3' }
         ];
 
+        // Add custom tracks separator and options if any exist
+        if (customTrackChoices.length > 0) {
+          trackChoices.push(
+            new inquirer.Separator(chalk.gray('─'.repeat(50))),
+            ...customTrackChoices
+          );
+        }
+
+        // Add custom track option
+        trackChoices.push(
+          new inquirer.Separator(chalk.gray('─'.repeat(50))),
+          { name: '➕ Add Custom Track...', value: '__custom__' }
+        );
+
         const { selectedTrack } = await inquirer.prompt([{
           type: 'list',
           name: 'selectedTrack',
           message: chalk.yellow('Choose default background music track:'),
           choices: trackChoices,
           default: config.backgroundMusic.track || 'agentvibes_soft_flamenco_loop.mp3',
-          pageSize: 16
+          pageSize: 18
+        }]);
+
+        // Handle custom track selection
+        if (selectedTrack === '__custom__') {
+          const tracksDir = path.join(__dirname, '..', '.claude', 'audio', 'tracks');
+          const { customTrackPath } = await inquirer.prompt([{
+            type: 'input',
+            name: 'customTrackPath',
+            message: chalk.yellow('Enter the full path to your audio file:'),
+            validate: (input) => {
+              const resolvedPath = path.resolve(input.trim());
+              if (!fsSync.existsSync(resolvedPath)) return 'File not found';
+              const ext = path.extname(resolvedPath).toLowerCase();
+              if (!['.mp3', '.wav', '.ogg', '.m4a'].includes(ext))
+                return 'Unsupported format (use .mp3, .wav, .ogg, or .m4a)';
+              return true;
+            }
+          }]);
+
+          const copiedFilename = await handleCustomMusicTrack(customTrackPath, tracksDir);
+          if (copiedFilename) {
+            config.backgroundMusic.track = copiedFilename;
+            console.log(chalk.green(`✓ Custom track added: ${copiedFilename}`));
+
+            // Update registry with new custom track
+            const trackName = path.basename(customTrackPath, path.extname(customTrackPath));
+            const allCustomTracks = await loadCustomTracks();
+            if (!allCustomTracks.some(t => t.filename === copiedFilename)) {
+              allCustomTracks.push({ name: trackName, filename: copiedFilename });
+              await saveCustomTracks(allCustomTracks);
+            }
+          } else {
+            // Fall back to default if custom track fails
+            config.backgroundMusic.track = 'agentvibes_soft_flamenco_loop.mp3';
+            console.log(chalk.yellow('⚠️  Using default track'));
+          }
+        } else {
+          config.backgroundMusic.track = selectedTrack;
+        }
+
+        // Offer preview of selected track
+        const tracksDir = path.join(__dirname, '..', '.claude', 'audio', 'tracks');
+        const { previewTrack } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'previewTrack',
+          message: chalk.cyan('Preview this track before continuing?'),
+          default: false
         }]);
 
-        config.backgroundMusic.track = selectedTrack;
+        if (previewTrack) {
+          console.log('');
+          await previewAudioTrack(config.backgroundMusic.track, tracksDir);
+          console.log('');
+        }
       }
 
       // Auto-advance to next page after audio settings
-      console.log(chalk.green('\n✓ Audio settings configured\n'));
+      console.log(chalk.green('✓ Audio settings configured\n'));
       currentPage++;
       continue;
 
@@ -2499,30 +2802,6 @@ async function copyPersonalityFiles(targetDir, spinner) {
     content += chalk.gray('Personalities change how Claude speaks - adding humor, emotion, or style.\n');
     content += chalk.gray('Change with: ') + chalk.yellow('/agent-vibes:personality <name>') + chalk.gray(' or say "change personality to sassy"\n\n');
 
-    // Map personalities to emojis
-    const personalityEmojis = {
-      'angry': '😠',
-      'annoying': '😤',
-      'crass': '🤬',
-      'dramatic': '🎭',
-      'dry-humor': '😐',
-      'flirty': '😘',
-      'funny': '😂',
-      'grandpa': '👴',
-      'millennial': '🙄',
-      'moody': '😒',
-      'normal': '😊',
-      'pirate': '🏴‍☠️',
-      'poetic': '📜',
-      'professional': '👔',
-      'rapper': '🎤',
-      'robot': '🤖',
-      'sarcastic': '😏',
-      'sassy': '💁',
-      'surfer-dude': '🏄',
-      'zen': '🧘'
-    };
-
     // Display personalities in two columns
     const personalities = installedPersonalities.map(file => {
       const name = file.replace('.md', '');
@@ -4377,6 +4656,14 @@ Troubleshooting:
       await fs.writeFile(personalityFile, userConfig.personality);
     }
 
+    // Apply pretext configuration from userConfig
+    if (userConfig.pretext && userConfig.pretext.trim()) {
+      const pretextFile = path.join(claudeDir, 'config', 'tts-pretext.txt');
+      const configDir = path.join(claudeDir, 'config');
+      await fs.mkdir(configDir, { recursive: true });
+      await fs.writeFile(pretextFile, userConfig.pretext.trim());
+    }
+
     // Initialize piperVoicesBoxen outside the conditional for proper scoping
     let piperVoicesBoxen = null;
 

package/src/utils/provider-validator.js

@@ -9,10 +9,50 @@ import path from 'node:path'; // For safe path operations and traversal preventi
 import fs from 'node:fs'; // For checking file/directory existence
 import os from 'node:os'; // For os.homedir() to prevent HOME injection attacks
 
+/**
+ * Helper: Check if command exists in PATH
+ * @param {string} command - Command name to check
+ * @returns {boolean} True if command exists in PATH
+ */
+function commandExistsInPath(command) {
+  try {
+    execSync(`which "${command}" 2>/dev/null`, {
+      encoding: 'utf8',
+      shell: true,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Helper: Check if file/directory exists and is within home directory
+ * @param {string} targetPath - Full path to check
+ * @returns {boolean} True if path exists and is safe
+ */
+function isSafePathExists(targetPath) {
+  try {
+    const homeDir = os.homedir();
+    const resolvedPath = path.resolve(targetPath);
+    const resolvedHome = path.resolve(homeDir);
+
+    // Validate path is within home directory (prevent path traversal)
+    if (!resolvedPath.startsWith(resolvedHome)) {
+      return false;
+    }
+
+    return fs.existsSync(targetPath);
+  } catch (error) {
+    return false;
+  }
+}
+
 /**
  * Validate a TTS provider's installation status
  * @param {string} providerName - Provider name (soprano, piper, macos, windows-sapi, etc.)
- * @returns {Promise<{installed: boolean, message: string, pythonVersion?: string, error?: string}>}
+ * @returns {Promise<{installed: boolean, message: string, checkedLocations?: string[], error?: string}>}
  */
 export async function validateProvider(providerName) {
   switch (providerName) {
@@ -39,57 +79,54 @@ export async function validateProvider(providerName) {
 }
 
 /**
- * Validate Soprano TTS installation
- * Checks multiple Python versions since Soprano might be in non-default Python
- * @returns {Promise<{installed: boolean, message: string, pythonVersion?: string, checkedCount?: number}>}
+ * Helper: Check if pipx provider is installed (Soprano, Piper)
+ * @param {string} providerName - Provider name (soprano or piper)
+ * @param {string} packageName - Package name (soprano-tts or piper-tts)
+ * @returns {Promise<{installed: boolean, message: string, checkedLocations: string[]}>}
  */
-export async function validateSopranoInstallation() {
+async function validatePipxProvider(providerName, packageName) {
   const checkedLocations = [];
+  const binName = providerName === 'soprano' ? 'soprano' : 'piper';
+  const venvName = providerName === 'soprano' ? 'soprano-tts' : 'piper-tts';
 
-  // Check for pipx installation first (common for CLI tools)
-  // Use os.homedir() (not env var) to prevent HOME injection attacks
-  try {
-    const homeDir = os.homedir();
-    const sopranoVenvPath = path.join(homeDir, '.local', 'share', 'pipx', 'venvs', 'soprano-tts');
+  // Check for binary in PATH first (most reliable for pipx installations)
+  if (commandExistsInPath(binName)) {
+    return { installed: true, message: `${providerName} TTS detected (binary in PATH)`, checkedLocations: ['PATH'] };
+  }
+  checkedLocations.push('PATH');
 
-    // Validate path is within home directory (prevent path traversal)
-    const resolvedPath = path.resolve(sopranoVenvPath);
-    const resolvedHome = path.resolve(homeDir);
-    if (!resolvedPath.startsWith(resolvedHome)) {
-      throw new Error('Path traversal detected');
-    }
+  // Check for pipx bin directory directly
+  const homeDir = os.homedir();
+  const binPath = path.join(homeDir, '.local', 'bin', binName);
+  if (isSafePathExists(binPath)) {
+    return { installed: true, message: `${providerName} TTS detected (via pipx bin)`, checkedLocations: ['~/.local/bin'] };
+  }
+  checkedLocations.push('~/.local/bin');
 
-    if (fs.existsSync(sopranoVenvPath)) {
-      checkedLocations.push('pipx'); // Always track what was checked
-      return { installed: true, message: 'Soprano TTS detected (via pipx)', checkedLocations };
-    }
-  } catch (error) {
-    // If home directory check fails, fall through to Python checks
-    if (error.code !== 'ENOENT') {
-      console.error('[DEBUG] Pipx check error:', error.message);
-    }
+  // Check for pipx venv installation directory
+  const venvPath = path.join(homeDir, '.local', 'share', 'pipx', 'venvs', venvName);
+  if (isSafePathExists(venvPath)) {
+    return { installed: true, message: `${providerName} TTS detected (via pipx venv)`, checkedLocations: ['pipx venv'] };
   }
-  checkedLocations.push('pipx');
+  checkedLocations.push('pipx venv');
 
-  // Comprehensive Python version detection
+  // Check Python package installations (comprehensive version detection)
   const pythonCommands = ['python3', 'python', 'python3.12', 'python3.11', 'python3.10', 'python3.9', 'python3.8'];
 
   for (const pythonCmd of pythonCommands) {
     try {
-      // Use array form to prevent command injection (security: CLAUDE.md)
-      const result = execSync(pythonCmd, ['-m', 'pip', 'show', 'soprano-tts'], {
+      // Use spawnSync with array args (security: correct API usage per CLAUDE.md)
+      const result = spawnSync(pythonCmd, ['-m', 'pip', 'show', packageName], {
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'pipe'],
         timeout: 10000
       });
 
-      if (result && result.trim()) {
-        checkedLocations.push(pythonCmd); // Track which Python found it
+      if (result.status === 0 && result.stdout && result.stdout.trim()) {
         return {
           installed: true,
-          message: `Soprano TTS detected via ${pythonCmd}`,
-          pythonVersion: pythonCmd,
-          checkedCount: checkedLocations.length + pythonCommands.indexOf(pythonCmd)
+          message: `${providerName} TTS detected (Python package via ${pythonCmd})`,
+          checkedLocations: [...checkedLocations, pythonCmd]
         };
       }
     } catch (error) {
@@ -97,81 +134,32 @@ export async function validateSopranoInstallation() {
     }
   }
 
-  // Build list of Python versions checked
   checkedLocations.push(...pythonCommands);
 
   return {
     installed: false,
-    message: `Soprano TTS is not installed on your system (checked: ${checkedLocations.join(', ')})`,
-    error: 'SOPRANO_NOT_FOUND',
-    checkedCount: checkedLocations.length
+    message: `${providerName} TTS is not installed on your system (checked: ${checkedLocations.join(', ')})`,
+    error: `${providerName.toUpperCase()}_NOT_FOUND`,
+    checkedLocations
   };
 }
 
+/**
+ * Validate Soprano TTS installation
+ * Checks multiple locations: PATH, pipx bin, pipx venv, Python packages
+ * @returns {Promise<{installed: boolean, message: string, checkedLocations?: string[], error?: string}>}
+ */
+export async function validateSopranoInstallation() {
+  return await validatePipxProvider('soprano', 'soprano-tts');
+}
+
 /**
  * Validate Piper TTS installation
- * Checks if Piper is available via pipx or direct installation
- * Suppresses all error output for clean UX
- * @returns {Promise<{installed: boolean, message: string}>}
+ * Checks multiple locations: PATH, pipx bin, pipx venv, Python packages
+ * @returns {Promise<{installed: boolean, message: string, checkedLocations?: string[], error?: string}>}
  */
 export async function validatePiperInstallation() {
-  const checkedLocations = [];
-
-  // Check for piper binary with error suppression
-  try {
-    execSync('which piper 2>/dev/null', {
-      encoding: 'utf8',
-      shell: true,
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    return { installed: true, message: 'Piper TTS detected (binary in PATH)' };
-  } catch (error) {
-    checkedLocations.push('PATH (piper binary)');
-  }
-
-  // Check for pipx installation (use venv directory check - more reliable than pipx list)
-  try {
-    const homeDir = os.homedir(); // Use os.homedir() not env var (security: prevent HOME injection)
-    const piperVenvPath = path.join(homeDir, '.local', 'share', 'pipx', 'venvs', 'piper-tts');
-
-    // Validate path is within home directory (prevent path traversal)
-    const resolvedPath = path.resolve(piperVenvPath);
-    const resolvedHome = path.resolve(homeDir);
-    if (!resolvedPath.startsWith(resolvedHome)) {
-      throw new Error('Path traversal detected');
-    }
-
-    if (fs.existsSync(piperVenvPath)) {
-      checkedLocations.push('pipx'); // Always track
-      return { installed: true, message: 'Piper TTS detected (via pipx)', checkedLocations };
-    }
-  } catch (error) {
-    if (error.code !== 'ENOENT') {
-      console.error('[DEBUG] Pipx check error:', error.message);
-    }
-  }
-  checkedLocations.push('pipx');
-
-  // Check if Python + piper-tts package installed using array form (security: prevent injection)
-  try {
-    const result = execSync('python3', ['-m', 'pip', 'show', 'piper-tts'], {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 10000
-    });
-    if (result && result.trim()) {
-      checkedLocations.push('python3 pip'); // Track what found it
-      return { installed: true, message: 'Piper TTS detected (Python package)', checkedLocations };
-    }
-  } catch (error) {
-    checkedLocations.push('python3 pip');
-  }
-
-  return {
-    installed: false,
-    message: `Piper TTS is not installed on your system (checked: ${checkedLocations.join(', ')})`,
-    error: 'PIPER_NOT_FOUND'
-  };
+  return await validatePipxProvider('piper', 'piper-tts');
 }
 
 /**
@@ -273,11 +261,17 @@ async function testSopranoRuntime() {
  */
 async function testPiperRuntime() {
   try {
-    execSync('piper', ['--help'], {
+    const result = spawnSync('piper', ['--help'], {
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe'],
       timeout: 5000
     });
+    if (result.error || result.status !== 0) {
+      return {
+        working: false,
+        error: 'Piper command execution failed'
+      };
+    }
     return { working: true };
   } catch (e) {
     return {
@@ -292,11 +286,17 @@ async function testPiperRuntime() {
  */
 async function testMacOSRuntime() {
   try {
-    execSync('say', ['-f', '/dev/null'], {
+    const result = spawnSync('say', ['-f', '/dev/null'], {
       encoding: 'utf8',
       timeout: 5000,
       stdio: ['pipe', 'pipe', 'pipe']
     });
+    if (result.error || result.status !== 0) {
+      return {
+        working: false,
+        error: 'macOS Say command execution failed'
+      };
+    }
     return { working: true };
   } catch (e) {
     return {
@@ -339,52 +339,59 @@ export async function attemptProviderInstallation(providerName) {
     return { success: false, message: `Unknown provider: ${providerName}` };
   }
 
-  // Strategy 1: Try regular pip install (using array form for security - CRITICAL #1 fix)
+  // Strategy 1: Try regular pip install (using spawnSync for correct API usage)
   try {
     // Show installation in progress
     console.log(`   Attempting: pip install ${pkgName}...`);
-    execSync('pip', ['install', pkgName], {
+    const result = spawnSync('pip', ['install', pkgName], {
       stdio: 'inherit',
-      timeout: 60000 // HIGH #1 fix - 60 second timeout
+      timeout: 60000
     });
 
-    // Verify installation actually worked (proves it's installed)
-    const validation = await validateProvider(providerName);
-    if (validation.installed) {
-      return {
-        success: true,
-        message: `Successfully installed via pip`,
-        command: `pip install ${pkgName}`,
-        verified: true
-      };
-    }
+    if (result.error || result.status !== 0) {
+      // Strategy 1 failed - continue to Strategy 2
+    } else {
+      // Verify installation actually worked (proves it's installed)
+      const validation = await validateProvider(providerName);
+      if (validation.installed) {
+        return {
+          success: true,
+          message: `Successfully installed via pip`,
+          command: `pip install ${pkgName}`,
+          verified: true
+        };
+      }
 
-    return { success: true, message: `Successfully installed via pip`, command: `pip install ${pkgName}` };
+      return { success: true, message: `Successfully installed via pip`, command: `pip install ${pkgName}` };
+    }
   } catch (error) {
     // Strategy 1 failed - continue to Strategy 2
-    // Don't check specific error messages - just try next strategy (MEDIUM #3 fix)
   }
 
   // Strategy 2: Try pipx install (recommended for PEP 668 protection)
   try {
     console.log(`   Attempting: pipx install ${pkgName}...`);
-    execSync('pipx', ['install', pkgName], {
+    const result = spawnSync('pipx', ['install', pkgName], {
       stdio: 'inherit',
-      timeout: 60000 // HIGH #1 fix - 60 second timeout
+      timeout: 60000
     });
 
-    // Verify installation actually worked (proves it's installed)
-    const validation = await validateProvider(providerName);
-    if (validation.installed) {
-      return {
-        success: true,
-        message: `Successfully installed via pipx`,
-        command: `pipx install ${pkgName}`,
-        verified: true
-      };
-    }
+    if (result.error || result.status !== 0) {
+      // Both strategies failed
+    } else {
+      // Verify installation actually worked (proves it's installed)
+      const validation = await validateProvider(providerName);
+      if (validation.installed) {
+        return {
+          success: true,
+          message: `Successfully installed via pipx`,
+          command: `pipx install ${pkgName}`,
+          verified: true
+        };
+      }
 
-    return { success: true, message: `Successfully installed via pipx`, command: `pipx install ${pkgName}` };
+      return { success: true, message: `Successfully installed via pipx`, command: `pipx install ${pkgName}` };
+    }
   } catch (error) {
     // Both strategies failed
   }
@@ -400,14 +407,19 @@ export async function attemptProviderInstallation(providerName) {
  */
 function getPackageInfo(pkgName) {
   try {
-    // Small delay to ensure package is registered in pip
-    // (sometimes pip needs a moment to update its cache)
-    const output = execSync('pip', ['show', pkgName], {
+    // Use spawnSync with array args (security: correct API usage per CLAUDE.md)
+    const result = spawnSync('pip', ['show', pkgName], {
       encoding: 'utf8',
       timeout: 10000,
-      stdio: ['pipe', 'pipe', 'pipe'] // Capture both stdout and stderr
+      stdio: ['pipe', 'pipe', 'pipe']
     });
 
+    if (result.error || result.status !== 0) {
+      return null;
+    }
+
+    const output = result.stdout;
+
     // Parse pip show output
     const info = {};
     const lines = output.split('\n');