ableton-mcp-ai/docs/SAME_PACK_SELECTION.md

Same-Pack Strict Selection Implementation

Overview

This implementation enforces strict same-pack selection for atmos_fx and vocal_shot roles to ensure these samples are well-integrated into the same sonic universe as the main musical elements (drums, bass, music).

Problem Statement

Previously, these roles could be selected from different packs than the main elements, leading to:

• Poor sonic coherence within tracks
• Jarring transitions between sound sources
• A lack of unified "pack character" in productions

Solution

1. Strict Same-Pack Bonus System

Added _calculate_same_pack_strict_bonus() method in sample_selector.py that applies different score multipliers based on folder relationships:

Relationship	Multiplier	Type	Description
Exact folder match	2.0x	same_pack	Sample in same folder as main pack
Subfolder of main pack	1.8x	same_pack	Sample in subfolder of main pack folder
Sibling folder	1.5x	same_parent	Sample in sibling folder (same parent)
Same pack root	1.3x	same_parent	Different structure but same pack name
Different pack	0.4x	fallback	Completely different pack lineage

2. Integration with Sample Scoring

Modified _calculate_sample_score() to:

• Detect when selecting for atmos_fx or vocal_shot roles
• Build list of main pack folders from palette data (drums, bass, music anchors)
• Apply strict bonus/penalty with high weight (0.25)
• Log selection type with clear markers

3. Fallback Mechanism

When same-pack samples aren't available:

• Heavy penalty (0.4x) is applied but selection can still proceed
• Logs clearly mark "FALLBACK" selections
• System continues to function even with limited library diversity

4. Logging

Three log levels for monitoring:

• INFO - "SAME_PACK": Selected from main pack (bonus applied)
• INFO - "SAME_PARENT": Selected from related folder (moderate bonus)
• WARNING - "FALLBACK": Cross-pack selection (penalty applied)

Files Modified

1. AbletonMCP_AI/AbletonMCP_AI/MCP_Server/sample_selector.py
   • Added _calculate_same_pack_strict_bonus() method
   • Modified _calculate_sample_score() to apply strict same-pack logic
   • Uses existing palette data from _palette_data attribute

How Same-Pack Selection Works

1. Pack Context Establishment:

   • PackBrain in pack_brain.py establishes the current pack context
   • Main pack folders (drums, bass, music) are identified and stored in palette
   • Palette data is passed to SampleSelector via set_palette_data()

2. Sample Evaluation:

   • When scoring samples for atmos_fx or vocal_shot roles
   • System checks folder relationships against main pack folders
   • Applies appropriate bonuses or penalties

3. Selection:

   • Weighted random selection still applies
   • Same-pack samples have significantly higher probability
   • Cross-pack selections are penalized but possible if no alternatives exist

Validation Steps

1. Compile Check

python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\sample_selector.py"

2. Unit Test

python "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\test_same_pack_selection.py"

Expected output:

[PASS] Test 1: Exact folder match gives bonus 2.0x
[PASS] Test 2: Subfolder match gives bonus 1.8x
[PASS] Test 3: Sibling folder gives bonus 1.5x
[PASS] Test 4: Different pack gets penalty 0.4x
[PASS] Test 5: Multiple main pack references work correctly

[OK] All same-pack bonus tests passed!
[SUCCESS] Same-pack strict selection feature is working correctly!

3. Real Generation Test

1. Generate a track with the system
2. Check logs for same-pack selection markers
3. Inspect the generation manifest for sample paths:
   • atmos_fx and vocal_shot should come from folders related to main pack
   • Look for log entries starting with "SAME_PACK", "SAME_PARENT", or "FALLBACK"

4. Log Inspection

During generation, look for:

SAME_PACK [ATMOS_FX]: Selected from main pack - sample.wav (score: 2.0)
SAME_PARENT [VOCAL_SHOT]: Selected from related folder - vocal.wav (score: 1.5, sibling folder to main pack)
FALLBACK [ATMOS_FX]: Cross-pack selection - atmos.wav (penalty: 0.4, different pack lineage)

Configuration

No manual configuration required. The feature automatically:

• Activates for atmos_fx and vocal_shot roles only
• Uses existing palette data from PackBrain
• Logs all selections for monitoring

Backward Compatibility

• Fully backward compatible
• Existing tracks without these roles are unaffected
• No changes to other roles or selection logic
• Palette system remains unchanged

Benefits

1. Coherence: Samples from same pack share sonic characteristics
2. Predictability: Consistent behavior across generations
3. Fallback Safety: System continues to work even with limited libraries
4. Transparency: Clear logging shows which samples were selected from where

Future Enhancements

Potential improvements:

• Add user-configurable strictness level
• Expand to additional roles (e.g., fx, perc_loop)
• Add same-pack tracking to diversity memory to avoid repetition within pack