Feature Request: Expose Scene and Performance Macro APIs

[kmorrill]

Summary

Scene and Performance data exists in the Kit struct but is stored as private byte arrays (perf_ctl, scene_ctl). There's no public API to read, parse, or modify scenes and performance macros programmatically.

Current State

What exists:

• Kit struct contains raw byte arrays:
  • pub(crate) perf_ctl: [u8; 192] - Performance macro data (48 bytes × 4)
  • pub(crate) scene_ctl: [u8; 192] - Scene data (48 bytes × 4)
  • pub(crate) current_scene_id: u8 - Active scene (0-11)
• Data is queried and stored when fetching kits
• MIDI CC support exists for triggering (CC 35-47 for performance, CC 92 for scene selection)

What's missing:

• Public API to access scene/performance data
• Parsing of raw byte arrays into structured data
• Modification/creation of scenes and performance macros
• Serialization/deserialization

Use Cases

Users want to programmatically:

• Read current scene/performance macro assignments
• Create/modify scenes (parameter snapshots for instant sound changes)
• Create/modify performance macros (dynamic pressure-sensitive parameter modulation)
• Copy scenes/macros between kits
• Export/import scenes for sharing
• Generate scenes algorithmically
• Build CLI tools that manipulate performance controls

Device Behavior

Scenes (12 per kit)

• Fixed parameter snapshots - instant ON/OFF parameter locks
• Each scene can lock multiple parameters across any of the 13 tracks
• Only one scene active at a time
• Assigned to pads 1-12
• Triggered via MIDI CC 92 (value 0-11)

Performance Macros (12 per kit)

• Dynamic parameter modulation - pressure-sensitive pad control
• Each macro can modulate multiple parameters across any tracks
• Modulation is relative and additive (unlike scenes which are absolute)
• Multiple macros can be active simultaneously
• Assigned to pads 1-12
• Triggered via MIDI CC 35-47

Technical Details

Based on the Analog Rytm MKII manual (sections 10.3-10.4):

Scenes:

• 12 scenes per kit
• Each scene contains parameter locks from any track
• Parameters: Any from SYNTH/SAMPLE/FILTER/AMP/LFO pages + FX track
• Storage: 192 bytes total (48 bytes × 4 groups)

Performance Macros:

• 12 macros per kit
• Each macro contains modulation assignments
• Dynamic pressure-sensitive control (0-127 pressure affects modulation depth)
• Storage: 192 bytes total (48 bytes × 4 groups)

Estimated structure:

pub struct Scene {
    id: u8,  // 0-11
    parameter_locks: Vec<SceneParameterLock>,
}

pub struct SceneParameterLock {
    track_index: u8,  // 0-12 (12 = FX)
    parameter: ParameterType,
    value: u8,  // Fixed value
}

pub struct PerformanceMacro {
    id: u8,  // 0-11
    modulations: Vec<PerformanceModulation>,
}

pub struct PerformanceModulation {
    track_index: u8,  // 0-12 (12 = FX)
    parameter: ParameterType,
    depth: i8,  // Modulation amount (can be negative)
}

Implementation Tasks

• Reverse engineer scene byte format
• Reverse engineer performance macro byte format
• Create Scene and PerformanceMacro data structures
• Implement parsing from raw bytes
• Implement serialization to raw bytes
• Add public accessors to Kit struct:
  • pub fn scenes(&self) -> &[Scene]
  • pub fn scenes_mut(&mut self) -> &mut [Scene]
  • pub fn performance_macros(&self) -> &[PerformanceMacro]
  • pub fn performance_macros_mut(&mut self) -> &mut [PerformanceMacro]
  • pub fn current_scene_id(&self) -> u8
  • pub fn set_current_scene_id(&mut self, id: u8)
• Add tests for scene/performance query and modification
• Document scene and performance mode functionality
• Consider MIDI CC helper functions for triggering

References

• Device manual sections "10.3 SCENE MODE" and "10.4 PERFORMANCE MODE" (pages 28-30)
• MIDI CC mapping: CC 35-47 (performance macros), CC 92 (active scene)
• Current Kit struct in src/object/kit.rs (lines with perf_ctl, scene_ctl)

Priority

Medium - Scenes and performance macros are key performance features, but can be programmed manually on device as a workaround. Would significantly enhance live performance tools and kit management utilities.

Additional Notes

Both scenes and performance macros are per-kit settings (not global), so they're already being queried/stored when kits are fetched. The data just needs to be parsed and exposed.

Unlike songs (issue #2), the data structures for scenes/performance are already present in the library - they just need to be decoded and made accessible.

---

Filed from a vibe-coding session where we wanted to programmatically inspect and modify performance controls. Happy to help test once implemented!