Tier 1 Enhancements - User Guide

COMPLETE_PATTERNS = [
    r'^play\s+(left|right)$',    # "play left"
    r'^stop\s+(left|right)$',     # "stop right"
    r'^sync\s+(left|right)$',     # "sync left"
    r'^loop\s+(left|right)$',     # "loop right"
]

# Enabled by default
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh

# Disable if you want fixed timeouts
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-adaptive

❌ Failed to open audio
💡 Troubleshooting:
   1. Check microphone is connected
   2. Grant microphone permission:
      System Preferences → Security & Privacy → Microphone
   3. Make sure no other app is using the microphone
   4. Try selecting a different input device

❌ Failed to connect
💡 Troubleshooting:
   1. Check your internet connection
   2. Verify GEMINI_API_KEY in .env file
   3. Check API quota at https://ai.google.dev/
   4. Try again in a few moments

⚠️ No command match found
💡 Try: 'play left', 'sync right', 'loop four beats left'

❌ Gemini error
💡 Troubleshooting:
   1. Speech may have been unclear - try speaking more clearly
   2. Background noise may be interfering
   3. Try moving closer to microphone

def _get_error_guidance(self, error_type: str) -> str:
    guidance = {
        "audio_open_failed": "Check microphone permissions...",
        "connection_failed": "Check internet connection...",
        # ...
    }
    return guidance.get(error_type, "See documentation")

📝 Gemini: "stop left"
   ⚠️  CRITICAL COMMAND DETECTED
   🛡️  Say 'confirm' to execute or 'cancel' to abort
   ⏱  You have 5s to respond

📝 Gemini: "confirm"
   ✓ Confirmed: executing "stop left"
   🔎 Match: execute 3006 (Z) - approved
   ✓ Pressed Rekordbox shortcut: Z

📝 Gemini: "cancel"
   ✗ Cancelled: "stop left" not executed

(5 seconds pass)
   ⏱  Confirmation timeout - command cancelled

CRITICAL_COMMANDS = {
    'stop left', 'stop right',
    'clear hot cue', 'delete hot cue',
    'reset effects', 'reset mixer',
    # Add your own critical commands
}

# Enabled by default (recommended for live performance)
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh

# Disable if you want immediate execution (practice only!)
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-confirmation

📝 "sync left"      → Updates left deck
📝 "loop left"      → Updates left deck
📝 "play left"      → Updates left deck
📝 "play"           → System infers left deck
   🧠 Smart default: "play" → "play left"
   🔎 Match: execute 3006 (Z) - approved

📝 "sync right"     → Updates right deck
📝 "play"           → System infers right deck
   🧠 Smart default: "play" → "play right"
   🔎 Match: execute 3106 (N) - approved

📝 "sync left"
📝 "loop right"
📝 "play left"
📝 "sync right"
📝 "play"           → System uses most recent (right)
   🧠 Smart default: "play" → "play right"

class CommandContext:
    command_history: List[Tuple[float, str, str]]  # (time, cmd, deck)

    def get_preferred_deck(self) -> Optional[str]:
        # Analyze last 5 commands
        # If strong bias (2:1 ratio), use that deck
        # Otherwise use most recent

def _apply_intelligent_defaults(self, text: str) -> str:
    # Already has deck? No inference needed
    if 'left' in text or 'right' in text:
        return text

    # Needs deck? Infer from context
    preferred = self.context.get_preferred_deck()
    if preferred:
        return f"{text} {preferred}"

# Enabled by default (recommended)
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh

# Disable if you prefer explicit deck names
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-smart-defaults

📝 Gemini: "play left and sync right"
   📦 Batch: 2 commands detected
   [1/2] play left
   🔎 Match: execute 3006 (Z) - approved
   ✓ Pressed Rekordbox shortcut: Z

   [2/2] sync right
   🔎 Match: execute 3106 (S) - approved
   ✓ Pressed Rekordbox shortcut: S

📝 Gemini: "loop four beats then activate effects then play"
   📦 Batch: 3 commands detected
   [1/3] loop four beats
   [2/3] activate effects
   [3/3] play

📝 Gemini: "sync left and loop right and play left"
   📦 Batch: 3 commands detected
   [1/3] sync left
   [2/3] loop right
   [3/3] play left

def _split_batch_command(self, text: str) -> List[str]:
    for sep in ['and', 'then', 'plus', 'also']:
        if f' {sep} ' in text:
            parts = re.split(rf'\s+{sep}\s+', text)
            return [p.strip() for p in parts if p.strip()]
    return [text]  # Single command

📝 Gemini: "loop left and stop right"
   📦 Batch: 2 commands detected
   [1/2] loop left
   ✓ Executed

   [2/2] stop right
   ⚠️  CRITICAL COMMAND DETECTED
   🛡️  Say 'confirm' to execute or 'cancel' to abort

📝 "sync left"          (Sets context to left)
📝 "play and loop"      (Batch command)
   🧠 Smart default: "play" → "play left"
   🧠 Smart default: "loop" → "loop left"
   📦 Batch: 2 commands detected
   [1/2] play left
   [2/2] loop left

# Enabled by default
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh

# Disable if you prefer single commands only
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-batch

./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh

# Practice mode (no confirmations)
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-confirmation

# Conservative mode (no smart defaults)
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-smart-defaults

# Simple commands only (no batching)
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-batch

# Fixed latency (no adaptive buffering)
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-adaptive

# Practice mode: fast, no safety features
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh \
    --no-confirmation \
    --no-adaptive

# Production mode: all safety, moderate speed
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh \
    # (all defaults enabled)

📊 Enhanced Stats:
   Recognition errors: 2
   Adaptive speedups: 47          ← Times fast buffering was used
   Confirmations required: 3      ← Times safety kicked in
   Batch commands: 8              ← Number of batch executions

# Edit gemini_listener_enhanced.py
COMPLETE_PATTERNS = [
    r'^your\s+custom\s+pattern$',
]

./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-confirmation

# Edit gemini_listener_enhanced.py
CRITICAL_COMMANDS = {
    # Comment out commands you don't want confirmed
    # 'stop left', 'stop right',
}

# Old launcher
./START_REKORDBOX_VOICE_GEMINI.sh

# New launcher (enhanced)
./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh

GeminiVoiceListener (fixed 800ms buffer)
    └─→ on_text_callback(text)

EnhancedGeminiVoiceListener
    ├─→ Adaptive buffering (50-800ms)
    ├─→ Command context tracking
    ├─→ Confirmation state machine
    ├─→ Batch command parser
    ├─→ Error guidance system
    └─→ on_text_callback(enhanced_text)