Mapping System Update - Complete Guide

Mapping System Update - Complete Guide

Overview

The Rekordbox voice control system has been updated with comprehensive command mappings from the full Rekordbox keyboard shortcut catalog. This update includes 450 commands covering all major DJ operations across both decks.

---

What Was Updated

1. Command Mappings (commands.yaml)

Before:
- ~60 commands manually curated
- Basic transport, loop, and hotcue operations
- Limited coverage of Rekordbox features

After:
- 450 commands from full Rekordbox mapping
- 227 Deck 1 commands (30xx command IDs)
- 223 Deck 2 commands (31xx command IDs)
- Complete coverage of:
- Transport (play, pause, cue, slip reverse)
- Loops (1/2, 1, 2, 4, 8 beat loops + manual loop controls)
- Hot Cues (A, B, C, D + clear operations)
- Sync & Tempo (beat sync, master tempo, pitch bend, tempo adjust)
- Effects (FX slots, parameters)
- Mixer (crossfader, EQ, filters)
- Library (load tracks, search, playlists)
- Sampler (12 slots, playback, pause, sequences)
- Grid & Beat (memory cues, beatgrid editing)
- Layout (zoom, panels, views)
- Recording (start/stop/pause)

2. Gemini System Instructions

Updated Files:
- `gemini_listener.py` - Original Gemini Live listener
- `gemini_listener_enhanced.py` - Enhanced listener with Tier 1 optimizations

New Instruction Features:
- Organized by category (Transport, Loop, Hot Cue, Sync/Tempo, etc.)
- Comprehensive examples for each category
- Clear deck specification (left/right)
- Voice-friendly command phrasing
- Batch command support (enhanced version only)
- Confirmation/cancellation keywords

3. Conversion Tools

New Script: `Mapping/convert_json_to_yaml.py`

This script automatically converts Rekordbox JSON mappings to YAML format with:
- Automatic category inference
- Action type detection
- Deck assignment (left/right/context)
- Voice synonym generation
- Safety constraint inference
- Metadata preservation

---

Command Categories & Examples

Transport Commands (Category: `transport`)

Loop Commands (Category: `loop`)

Hot Cue Commands (Category: `hotcue`)

Sync & Tempo Commands (Category: `sync_tempo`)

Sampler Commands (Category: `sampler`)

Library Commands (Category: `library`)

Recording Commands (Category: `recorder`)

---

Safety Constraints

All commands have safety metadata to prevent accidents:

### Destructive Commands
Commands that delete or clear data:
- `destructive: true`
- `confirm_if_playing: true`
- `cooldown_ms: 2000`

Examples:
- Clear hot cue operations
- Delete memory cue operations

### Requires Idle
Commands that should only run when deck is stopped:
- `requires_idle: true`
- `confirm_if_playing: true`
- `cooldown_ms: 2500`

Examples:
- Load track operations
- Instant doubles

### Critical Operations
Recording and other critical operations:
- `destructive: true`
- `confirm_if_playing: true`
- `cooldown_ms: 3000`

---

Voice Command Patterns

Deck Specification

Left Deck (Deck 1):
- "play left"
- "play left deck"
- "play deck 1"
- "play deck one"

Right Deck (Deck 2):
- "play right"
- "play right deck"
- "play deck 2"
- "play deck two"

Command Variations

Hot Cue Example:

Set Hot Cue A on Left Deck:
✓ "set hot cue a left deck"
✓ "set cue a left deck"
✓ "set hot cue a deck 1"
✓ "set hot cue a deck one"

Loop Example:

4 Beat Loop:
✓ "4 beat loop"
✓ "loop 4 beats"
✓ "four beat loop"

Tempo Example:

Increase Tempo:
✓ "speed up track"
✓ "faster"
✓ "tempo up"
✓ "increase tempo"

---

Enhanced Features (gemini_listener_enhanced.py)

Batch Commands

Execute multiple commands in a single utterance:

"play left and sync right"
→ Executes: play left, then sync right

"loop four beats then activate effects"
→ Executes: loop four beats, then activate effects

"sync left and loop right and play left"
→ Executes: sync left, loop right, play left

Command Confirmation

Critical commands require verbal confirmation:

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

User: "confirm"
System: ✓ Confirmed: executing "stop left"

Intelligent Deck Selection

System infers deck from recent command history:

User: "sync left"
User: "loop left"
User: "play left"
User: "play"  ← System infers "play left"

---

File Changes Summary

Backed Up

Mapping/commands.yaml → Mapping/commands.yaml.backup

Created

Mapping/convert_json_to_yaml.py       - JSON to YAML converter
Mapping/commands_full.yaml            - Full 450 command catalog
MAPPING_UPDATE_GUIDE.md               - This guide

Updated

Mapping/commands.yaml                                    - Now contains 450 commands
dj_agent/voice_control/core/gemini_listener.py          - Updated system instruction
dj_agent/voice_control/core/gemini_listener_enhanced.py - Updated system instruction

---

Testing the Updated System

1. Test Basic Commands

Start the enhanced system:

./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh

Try these commands:
- "play left"
- "loop four beats"
- "set hot cue a left deck"
- "sync right"

2. Test New Commands

Try commands that weren't available before:
- "slip reverse left"
- "next track right"
- "playback slot 1"
- "expand beat intervals"
- "shift beatgrid to center"

3. Test Batch Commands (Enhanced Only)

"play left and sync right"
"loop four beats then activate effects"
"set hot cue a and play"

4. Test Category Coverage

Transport:
- "play left"
- "cue right deck"
- "next track left"

Loops:
- "1 beat loop"
- "halve loop"
- "exit loop"

Hot Cues:
- "set hot cue b right deck"
- "clear hot cue a left deck"

Tempo:
- "beat sync"
- "faster"
- "master tempo"

Sampler:
- "playback slot 1"
- "pause slot 2"

Library:
- "load left deck"
- "search collection"

---

Rollback Instructions

If you need to revert to the previous mapping:

cd [home]/Desktop/Computational\ Choreography/computational-studio/studio/Mapping

# Restore original commands.yaml
cp commands.yaml.backup commands.yaml

echo "✅ Reverted to original commands.yaml"

Then restart the voice control system.

---

Troubleshooting

Issue: Commands not recognized

Symptom: Voice commands that should work are not being matched

Solutions:
1. Check that Rekordbox is running in Performance mode
2. Verify commands.yaml was updated: `wc -l Mapping/commands.yaml` should show ~13000+ lines
3. Check that deck specification is clear: say "left" or "right" explicitly
4. Try the exact phrases from the examples above

Issue: Wrong command executed

Symptom: System executes different command than intended

Solutions:
1. Use more specific phrasing (e.g., "set hot cue a left deck" instead of "set cue a")
2. Include deck specification ("left" or "right")
3. Speak clearly and wait for command completion indicator
4. Check embedding similarity scores in console output

Issue: Batch commands not working

Symptom: Batch commands execute as single command

Solutions:
1. Make sure you're using the ENHANCED system: `START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh`
2. Use recognized separators: "and", "then", "plus", "also"
3. Check console for "📦 Batch: X commands detected" message
4. If disabled, re-enable with: `./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh` (no --no-batch flag)

Issue: Too many confirmations

Symptom: System asks for confirmation too often

Solutions:
1. For practice sessions, disable confirmations:

   ./START_REKORDBOX_VOICE_GEMINI_ENHANCED.sh --no-confirmation

2. Or edit `CRITICAL_COMMANDS` in `gemini_listener_enhanced.py` to remove specific commands

---

Performance Metrics

Coverage Improvement

Category Coverage

---

Next Steps

1. Test thoroughly with your DJ workflow
2. Add custom synonyms if you use different phrasing
3. Report issues if any commands don't work as expected
4. Customize safety settings in commands.yaml for your preferences
5. Try batch commands to speed up multi-step operations

---

Technical Details

Command ID Format

• 30xx: Deck 1 commands (left deck)
• 31xx: Deck 2 commands (right deck)
• b0xx: Layout/global commands
• b1xx: Library/navigation commands
• f0xx: Sampler commands
• d0xx: Recorder commands
• 70xx: Library search commands
• 50xx: Playlist commands

Metadata Schema

Each command includes:

- id: "3006"                    # Rekordbox command ID
  canonical: "Play/Pause"       # Official description
  synonyms:                     # Voice-friendly alternatives
    - "play left deck"
    - "play left"
    - "start left deck"
    - "pause left deck"
  category: "transport"         # Functional category
  deck: "left"                  # left, right, or context
  action_type: "play_pause"     # Specific action type
  shortcut: "Z"                 # Keyboard shortcut
  safety:                       # Safety constraints
    destructive: false
    requires_idle: false
    confirm_if_playing: false
    cooldown_ms: 600

Embedding-Based Retrieval

The system uses semantic embeddings to match voice commands:
1. User speaks: "play the left deck"
2. Gemini extracts: "play left"
3. System embeds: [768-dim vector]
4. Cosine similarity search finds best match: command 3006
5. Constraints verify it's safe to execute
6. Bridge sends keyboard shortcut: "Z"

---

Support

For issues or enhancement requests:
1. Check this guide's troubleshooting section
2. Review TIER1_ENHANCEMENTS_GUIDE.md for enhanced features
3. See GEMINI_ARCHITECTURE_ESSAY.md for technical details
4. Check console output for error messages and guidance

---

Enjoy the expanded command coverage! The system now supports virtually all Rekordbox DJ operations via voice control.