Sync: Complete project state with all MEGA SPRINT V1-V3 features and Codex stubs
This commit is contained in:
renato97
141
docs/SAME_PACK_SELECTION.md
Normal file
141
docs/SAME_PACK_SELECTION.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# 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
|
||||
```powershell
|
||||
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
|
||||
```powershell
|
||||
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
|
||||
Reference in New Issue
Block a user