livepilot 1.9.23 → 1.10.0

package/mcp_server/atlas/enrichments/__init__.py

@@ -0,0 +1,111 @@
+"""
+Enrichment loader — reads YAML files from subdirectories and merges them
+into scanned device entries.
+
+Directory layout::
+
+    enrichments/
+        instruments/
+            analog.yaml
+            wavetable.yaml
+        audio_effects/
+            compressor.yaml
+            eq_eight.yaml
+        _templates/       # skipped (leading underscore)
+            ...
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+
+def load_enrichments(enrichments_dir: str | Path) -> dict[str, dict[str, Any]]:
+    """Walk *enrichments_dir* and load every YAML file into a dict.
+
+    Files whose name starts with ``_`` are skipped (convention for templates
+    or drafts).  Each file must be named ``<device_id>.yaml`` and contain a
+    mapping of enrichment fields.
+
+    Returns
+    -------
+    dict[str, dict]
+        ``{device_id: enrichment_data}``
+    """
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        # PyYAML not installed — return empty gracefully
+        return {}
+
+    enrichments_path = Path(enrichments_dir)
+    result: dict[str, dict[str, Any]] = {}
+
+    if not enrichments_path.is_dir():
+        return result
+
+    for root, _dirs, files in os.walk(enrichments_path):
+        # Skip directories whose name starts with _
+        root_name = os.path.basename(root)
+        if root_name.startswith("_"):
+            continue
+        for fname in sorted(files):
+            if fname.startswith("_"):
+                continue
+            if not fname.endswith((".yaml", ".yml")):
+                continue
+            device_id = fname.rsplit(".", 1)[0]
+            filepath = os.path.join(root, fname)
+            with open(filepath, "r", encoding="utf-8") as fh:
+                data = yaml.safe_load(fh)
+            if isinstance(data, dict):
+                result[device_id] = data
+
+    return result
+
+
+# Fields that enrichment data can overwrite on a device entry
+_ENRICHMENT_FIELDS = frozenset({
+    "sonic_description",
+    "synthesis_type",
+    "effect_type",
+    "character_tags",
+    "use_cases",
+    "genre_affinity",
+    "complexity",
+    "self_contained",
+    "mcp_controllable",
+    "key_parameters",
+    "pairs_well_with",
+    "starter_recipes",
+    "gotchas",
+    "health_flags",
+    "introduced_in",
+    "signal_type",
+})
+
+
+def merge_enrichments(
+    devices: list[dict[str, Any]],
+    enrichments: dict[str, dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Merge enrichment data into device entries **in place** and return the list.
+
+    Only fields in ``_ENRICHMENT_FIELDS`` are written.  Sets ``enriched=True``
+    on every device that receives at least one enrichment field.
+    """
+    for device in devices:
+        device_id = device.get("id", "")
+        if device_id not in enrichments:
+            continue
+        enrich = enrichments[device_id]
+        touched = False
+        for field in _ENRICHMENT_FIELDS:
+            if field in enrich:
+                device[field] = enrich[field]
+                touched = True
+        if touched:
+            device["enriched"] = True
+    return devices

package/mcp_server/atlas/enrichments/audio_effects/auto_filter.yaml

@@ -0,0 +1,162 @@
+id: auto_filter
+name: Auto Filter
+sonic_description: >
+  Versatile resonant filter with built-in envelope follower, LFO, and sidechain input.
+  Creates everything from classic acid sweeps to rhythmic wobbles and auto-wah effects.
+  The morph filter type smoothly blends between low-pass and high-pass for evolving textures.
+effect_type: filter
+character_tags: [dynamic, resonant, expressive, rhythmic, acid]
+use_cases: [filter_sweeps, acid_bass, auto_wah, rhythmic_filter, wobble, sidechain_filter]
+genre_affinity:
+  primary: [techno, house, dubstep, electronic]
+  secondary: [funk, pop, ambient]
+complexity: intermediate
+signal_type: audio
+introduced_in: "1.0"
+
+key_parameters:
+  - name: "Filter Type"
+    description: "Filter topology — LP, HP, BP, Notch, or Morph (blends between types)"
+    range: ["LP 12", "LP 24", "HP 12", "HP 24", "BP 6", "BP 12", "Notch", "Morph"]
+    type: enum
+    sweet_spots:
+      acid: "LP 24"
+      wah: "BP 12"
+      sweep: "Morph"
+
+  - name: "Frequency"
+    description: "Filter cutoff frequency"
+    range: [20.0, 20000.0]
+    unit: Hz
+    type: float
+    sweet_spots:
+      dark: 200.0
+      warm: 800.0
+      bright: 4000.0
+      open: 12000.0
+
+  - name: "Resonance"
+    description: "Filter resonance — adds emphasis at cutoff frequency"
+    range: [0.0, 1.25]
+    type: float
+    sweet_spots:
+      clean: 0.0
+      warm: 0.3
+      squelchy: 0.6
+      screaming: 1.0
+
+  - name: "Env Amount"
+    description: "How much the envelope follower modulates the filter cutoff"
+    range: [-100.0, 100.0]
+    unit: "%"
+    type: float
+    sweet_spots:
+      subtle: 20.0
+      auto_wah: 50.0
+      aggressive: 80.0
+
+  - name: "Env Attack"
+    description: "Envelope follower attack time"
+    range: [0.1, 100.0]
+    unit: ms
+    type: float
+    sweet_spots:
+      fast: 1.0
+      medium: 10.0
+      slow: 50.0
+
+  - name: "Env Release"
+    description: "Envelope follower release time"
+    range: [1.0, 3000.0]
+    unit: ms
+    type: float
+    sweet_spots:
+      fast: 20.0
+      medium: 100.0
+      slow: 500.0
+
+  - name: "LFO Amount"
+    description: "How much the LFO modulates the filter cutoff"
+    range: [0.0, 100.0]
+    unit: "%"
+    type: float
+    sweet_spots:
+      subtle: 10.0
+      moderate: 30.0
+      heavy: 60.0
+      extreme: 100.0
+
+  - name: "LFO Rate"
+    description: "LFO speed — can be free or synced to tempo"
+    range: [0.01, 30.0]
+    unit: Hz
+    type: float
+    sweet_spots:
+      slow_sweep: 0.1
+      moderate: 1.0
+      wobble: 4.0
+      fast: 8.0
+
+  - name: "LFO Shape"
+    description: "LFO waveform shape"
+    range: ["Sine", "Square", "Triangle", "Saw Up", "Saw Down", "Random"]
+    type: enum
+    sweet_spots:
+      smooth: "Sine"
+      choppy: "Square"
+      ramp: "Saw Up"
+
+  - name: "Sidechain"
+    description: "External sidechain input for envelope follower"
+    type: toggle
+    range: [0, 1]
+
+pairs_well_with:
+  - device: "Saturator"
+    reason: "Distortion before filter for classic acid sound"
+  - device: "Delay"
+    reason: "Filtered delays for dub-style effects"
+  - device: "Reverb"
+    reason: "Filter sweep into reverb for dramatic transitions"
+  - device: "Compressor"
+    reason: "Tame dynamics after resonant filter sweeps"
+
+starter_recipes:
+  - name: "Acid Filter Sweep"
+    description: "Classic acid house resonant filter with LFO movement"
+    genre: techno
+    params:
+      "Filter Type": "LP 24"
+      Frequency: 400.0
+      Resonance: 0.7
+      "LFO Amount": 50.0
+      "LFO Rate": 2.0
+      "LFO Shape": "Saw Up"
+
+  - name: "Auto-Wah"
+    description: "Dynamic filter that opens with playing intensity"
+    genre: funk
+    params:
+      "Filter Type": "BP 12"
+      Frequency: 500.0
+      Resonance: 0.5
+      "Env Amount": 60.0
+      "Env Attack": 2.0
+      "Env Release": 80.0
+
+  - name: "Rhythmic Filter"
+    description: "Tempo-synced choppy filter for rhythmic textures"
+    genre: house
+    params:
+      "Filter Type": "LP 24"
+      Frequency: 600.0
+      Resonance: 0.4
+      "LFO Amount": 70.0
+      "LFO Shape": "Square"
+
+gotchas:
+  - "Resonance above 1.0 causes self-oscillation — the filter will ring/whistle on its own"
+  - "LFO Rate can be free-running (Hz) or tempo-synced — check which mode is active"
+  - "Env Amount can be negative — inverts the envelope follower direction (filter closes when input is loud)"
+  - "Morph filter type smoothly blends between LP and HP — great for automated sweeps"
+  - "High resonance + low frequency + loud input can produce very loud output — watch levels"

package/mcp_server/atlas/enrichments/audio_effects/beat_repeat.yaml

@@ -0,0 +1,183 @@
+id: beat_repeat
+name: Beat Repeat
+sonic_description: >
+  Rhythmic audio repeater and glitch machine that captures and stutters incoming audio
+  at controllable intervals. Creates fills, builds, and glitch effects by grabbing a
+  slice of audio and repeating it at various grid divisions with pitch decay and filtering.
+effect_type: delay
+character_tags: [glitchy, rhythmic, stuttered, creative, performable]
+use_cases: [fill_builder, glitch_stutter, dj_style, beat_mangle, transition, live_performance]
+genre_affinity:
+  primary: [electronic, glitch, idm, hip_hop]
+  secondary: [dnb, house, experimental]
+complexity: intermediate
+signal_type: audio
+introduced_in: "5.0"
+
+key_parameters:
+  - name: "Interval"
+    description: "How often Beat Repeat activates — the repetition cycle"
+    range: ["1/32", "1/16", "1/8", "1/4", "1/2", "1 Bar", "2 Bars", "4 Bars"]
+    type: enum
+    sweet_spots:
+      every_beat: "1/4"
+      every_bar: "1 Bar"
+      every_2_bars: "2 Bars"
+
+  - name: "Offset"
+    description: "Shifts the activation point within the Interval"
+    range: [0, 16]
+    type: int
+    sweet_spots:
+      start: 0
+      half: 8
+
+  - name: "Grid"
+    description: "Size of the repeated slice — determines the repeat rhythm"
+    range: ["1/32", "1/16", "1/8", "1/4", "1/2", "1 Bar"]
+    type: enum
+    sweet_spots:
+      fast_stutter: "1/32"
+      sixteenth: "1/16"
+      eighth: "1/8"
+      quarter: "1/4"
+
+  - name: "Variation"
+    description: "Adds rhythmic variation to the grid size over time"
+    range: [0, 100]
+    unit: "%"
+    type: int
+    sweet_spots:
+      locked: 0
+      subtle: 20
+      wild: 60
+
+  - name: "Chance"
+    description: "Probability that Beat Repeat activates each interval"
+    range: [0, 100]
+    unit: "%"
+    type: int
+    sweet_spots:
+      always: 100
+      occasional: 50
+      rare: 20
+
+  - name: "Gate"
+    description: "How long the repeat effect runs before passing through"
+    range: ["1/32", "1/16", "1/8", "1/4", "1/2", "1 Bar", "2 Bars", "4 Bars"]
+    type: enum
+    sweet_spots:
+      short: "1/4"
+      medium: "1 Bar"
+      long: "2 Bars"
+
+  - name: "Pitch"
+    description: "Pitch decay — repeats descend in pitch over time"
+    range: [0, 100]
+    unit: "%"
+    type: int
+    sweet_spots:
+      off: 0
+      subtle: 20
+      heavy: 60
+
+  - name: "Pitch Decay"
+    description: "Rate at which pitch drops during the repeat"
+    range: [0, 100]
+    unit: "%"
+    type: int
+    sweet_spots:
+      slow: 20
+      medium: 50
+      fast: 80
+
+  - name: "Filter Freq"
+    description: "Low-pass filter on the repeated signal"
+    range: [20.0, 20000.0]
+    unit: Hz
+    type: float
+    sweet_spots:
+      dark: 2000.0
+      warm: 5000.0
+      open: 15000.0
+
+  - name: "Volume"
+    description: "Output volume of the repeated signal"
+    range: [-inf, 6.0]
+    unit: dB
+    type: float
+    sweet_spots:
+      unity: 0.0
+      quiet: -6.0
+
+  - name: "Decay"
+    description: "Volume decay of repeats over time"
+    range: [0, 100]
+    unit: "%"
+    type: int
+    sweet_spots:
+      constant: 0
+      gentle: 30
+      rapid: 70
+
+  - name: "Mix Mode"
+    description: "Insert (replaces audio) or Mix (layers with original)"
+    range: ["Insert", "Mix"]
+    type: enum
+    sweet_spots:
+      replace: "Insert"
+      layer: "Mix"
+
+pairs_well_with:
+  - device: "Auto Filter"
+    reason: "Dynamic filter movement on the repeated audio"
+  - device: "Reverb"
+    reason: "Smear the stutters with reverb for dramatic builds"
+  - device: "Redux"
+    reason: "Bitcrush the repeats for extra lo-fi glitch character"
+  - device: "Saturator"
+    reason: "Drive the stuttered audio for aggressive texture"
+
+starter_recipes:
+  - name: "Fill Builder"
+    description: "Rhythmic fill that activates every 2 bars with accelerating stutter"
+    genre: electronic
+    params:
+      Interval: "2 Bars"
+      Grid: "1/8"
+      Variation: 40
+      Chance: 100
+      Gate: "1 Bar"
+      Pitch: 0
+      Decay: 20
+
+  - name: "Glitch Stutter"
+    description: "Random glitch bursts for experimental textures"
+    genre: idm
+    params:
+      Interval: "1/4"
+      Grid: "1/32"
+      Variation: 60
+      Chance: 30
+      Gate: "1/4"
+      Pitch: 30
+      "Pitch Decay": 50
+
+  - name: "DJ-Style Beat Mangle"
+    description: "Performance-ready beat repeat for live manipulation"
+    genre: dj
+    params:
+      Interval: "1 Bar"
+      Grid: "1/16"
+      Variation: 20
+      Chance: 100
+      Gate: "1/2"
+      "Mix Mode": "Insert"
+
+gotchas:
+  - "Insert mode replaces the original audio — Mix mode layers repeats on top"
+  - "Chance at 100% means it always triggers — lower values create unpredictable fills"
+  - "Variation adds randomness to grid size — starts musical but can get chaotic at high values"
+  - "Pitch decay creates a classic turntable-slowdown effect — set Pitch and Pitch Decay together"
+  - "Gate controls duration, not whether it triggers — Chance controls probability"
+  - "Map Grid to a MIDI controller for real-time stutter size changes during performance"

package/mcp_server/atlas/enrichments/audio_effects/channel_eq.yaml

@@ -0,0 +1,126 @@
+id: channel_eq
+name: Channel EQ
+sonic_description: >
+  Streamlined channel strip EQ with fixed low, sweepable mid, and fixed high bands plus
+  a built-in spectrum analyzer. Designed for fast tonal shaping with minimal controls,
+  perfect for quick adjustments when EQ Eight feels like overkill.
+effect_type: eq
+character_tags: [simple, quick, clean, channel_strip]
+use_cases: [quick_tonal_shaping, channel_strip, vocal_brightening, bass_warmth]
+genre_affinity:
+  primary: [all]
+  secondary: []
+complexity: beginner
+signal_type: audio
+introduced_in: "10.0"
+
+key_parameters:
+  - name: "Low Gain"
+    description: "Low shelf gain for bass control"
+    range: [-15.0, 15.0]
+    unit: dB
+    type: float
+    sweet_spots:
+      warmth: 2.0
+      thin_out: -3.0
+      bass_boost: 4.0
+
+  - name: "Mid Gain"
+    description: "Mid bell gain for body/presence control"
+    range: [-15.0, 15.0]
+    unit: dB
+    type: float
+    sweet_spots:
+      presence: 2.0
+      scoop: -3.0
+      body: 3.0
+
+  - name: "Mid Freq"
+    description: "Sweepable mid frequency — target the problem or sweet spot"
+    range: [120.0, 7500.0]
+    unit: Hz
+    type: float
+    sweet_spots:
+      mud: 350.0
+      body: 800.0
+      presence: 3000.0
+      clarity: 5000.0
+
+  - name: "High Gain"
+    description: "High shelf gain for brightness control"
+    range: [-15.0, 15.0]
+    unit: dB
+    type: float
+    sweet_spots:
+      air: 2.0
+      darken: -3.0
+      bright: 4.0
+
+  - name: "HP On"
+    description: "Enable the built-in high-pass filter"
+    type: toggle
+    range: [0, 1]
+
+  - name: "HP Freq"
+    description: "High-pass filter cutoff frequency"
+    range: [20.0, 500.0]
+    unit: Hz
+    type: float
+    sweet_spots:
+      rumble: 30.0
+      vocal: 80.0
+      thin: 200.0
+
+  - name: "Output"
+    description: "Output gain for level matching"
+    range: [-15.0, 15.0]
+    unit: dB
+    type: float
+    sweet_spots:
+      unity: 0.0
+
+pairs_well_with:
+  - device: "Compressor"
+    reason: "Quick EQ shaping before dynamics processing"
+  - device: "Utility"
+    reason: "Channel EQ for tone, Utility for level and width"
+  - device: "Saturator"
+    reason: "Tone shaping before saturation for controlled harmonic content"
+
+starter_recipes:
+  - name: "Quick Vocal Brightening"
+    description: "Add air and presence to a vocal with one device"
+    genre: all
+    params:
+      "Low Gain": -1.0
+      "Mid Gain": 1.5
+      "Mid Freq": 3000.0
+      "High Gain": 2.5
+      "HP On": 1
+      "HP Freq": 80.0
+
+  - name: "Bass Warmth"
+    description: "Warm up a bass track with low boost and mud cut"
+    genre: all
+    params:
+      "Low Gain": 3.0
+      "Mid Gain": -2.0
+      "Mid Freq": 400.0
+      "High Gain": 0.0
+
+  - name: "General Cleanup"
+    description: "High-pass and slight presence boost for most sources"
+    genre: all
+    params:
+      "HP On": 1
+      "HP Freq": 40.0
+      "Low Gain": 0.0
+      "Mid Gain": 1.0
+      "Mid Freq": 2500.0
+      "High Gain": 1.0
+
+gotchas:
+  - "Only one mid band with fixed Q — for surgical work, use EQ Eight instead"
+  - "The built-in spectrum analyzer is useful for visual feedback but adds slight CPU overhead"
+  - "High-pass filter has a fixed slope — less control than EQ Eight's HP options"
+  - "Good enough for 80% of EQ tasks — save EQ Eight for complex multi-band needs"