DreamMax — quickstart
===========================

Needs: Ableton Live 12 Suite (Max for Live), Windows x64 or macOS
Apple Silicon/Intel with a matching demon~ external, plus either a
Daydream API key or a running direct DEMON backend.

INSTALL
-------
>> THE #1 MISTAKE: moving "DreamMax.amxd" out on its own. The .amxd is
   NOT self-contained - it loads its bridge + external from the sibling files
   sitting next to it in this DreamMax folder. Move the .amxd alone (or copy
   only it into your User Library) and Live loads a device that can't find its
   engine: no sound, dead buttons. ALWAYS move the WHOLE "DreamMax" folder,
   never the .amxd by itself.

Easiest - just drag and drop: drop "DreamMax.amxd" straight from this
folder onto a track in Live and it runs (leave the rest of the folder in place).

To keep it in Live's browser permanently, copy the whole DreamMax FOLDER
(not just the .amxd - the siblings must come with it) into Ableton's User
Library:
  - macOS:   ~/Music/Ableton/User Library/DreamMax
  - Windows: %USERPROFILE%\Documents\Ableton\User Library\DreamMax
(If you moved your User Library, use that location instead - in Live it's
Preferences > Library > "Installation Folder for Packs" / browser "Add Folder".)
Then open Places > User Library > DreamMax and drag "DreamMax.amxd" onto
a track.

1. For the normal cloud flow, leave SERVER blank and press SIGN IN - it opens
   your browser to sign in (no API key to paste; the device picks it up
   automatically). For direct local testing, start the backend (from the
   DEMON repo root) and enter ws://127.0.0.1:1318 in SERVER:

     .venv/Scripts/python.exe -u -m demos.realtime_motion_graph_web.server --host 0.0.0.0 --port 1318

2. Drag "DreamMax.amxd" from THIS folder onto the track you are working on.
   (Keep the folder together - the device loads demon-bridge.js and
   demon~.mxe64 on Windows or demon~.mxo on macOS from beside itself.)

3. DreamMax is the whole system in one audio effect, and YOUR TRACK is
   the source:
    1. Press play in Live so the track is sounding.
    2. Press CONNECT. From the next barline DEMON grabs
        "CvBar" bars of the track at Live's tempo, makes it the
        canvas, and starts regenerating it.
     3. Turn the knobs / type a prompt. The Mix knob crossfades
        between your dry track and DEMON's output.
     4. Keep working on your clip. Feed=Auto (the default) replaces
        each canvas bar with whatever you played over it, so edits
        are heard one loop later - nothing to arm. Stop the
        transport and the canvas holds; stop the clip (transport
        running) and DEMON goes quiet bar by bar.
   The canvas strip shows the waveform, bar grid and playhead; drag
   across bars on it to loop just those bars (click once to release).
   The print button re-grabs the whole track whenever you want a
   fresh source. Feed=Stream pushes audio in continuously at a tape
   head; Feed=Splice replaces a chunk on demand (bars + arm button).

WORKFLOW - Full Mix vs Solo Instrument
--------------------------------------
The WORKFLOW menu (top-left) picks the model:
  - Full Mix: the full ACE-Step surface (the tabbed knob pages).
  - Solo Instrument: Stable Audio 3, a focused prompt-driven solo
    stem (Strength / Shift / Seed / Steps / Key + the prompt).
Switching models needs a fresh session, so changing WORKFLOW while
connected reconnects automatically. For a direct Solo (SA3) backend,
start the server with SA3 weights:
   ...server --host 127.0.0.1 --port 1318 --checkpoint sa3-medium --accel eager --skip-preflight
Only ONE DEMON device should connect to a local (single-session)
server at a time. If the backend is remote/direct, set the SERVER
field first (e.g. ws://<pod-ip>:1318); leave it blank for the cloud queue.
