Add tulip.save_synth_state() to persist synth setup across boots

Reads back every AMY synth (0..31) via amy_get_synth_commands and appends
the state as amy.send_raw() commands to the bottom of the given file
(default: your boot.py). Each command is prefixed with i<synth> so replay
targets the right synth. Re-saving replaces the previously saved block
instead of stacking copies. Not available on web builds, where the C
binding is compiled out.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bwhitman

docs/tulip_api.md

@@ -468,6 +468,13 @@ s.note_on(60, 1.0)
 
 Use `syn.release()` to free up the resources for a synth.
 
+Once you have your synths set up the way you like, you can save their state so it comes back on the next boot. `tulip.save_synth_state()` reads the current configuration of every AMY synth and appends the commands that restore it to the bottom of your `boot.py` (or any file you give it). Re-saving replaces the previously saved state.
+
+```python
+tulip.save_synth_state()  # adds current synth state to your boot.py
+tulip.save_synth_state('my_setup.py')  # or save it to some other file to execfile() later
+```
+
 
 ### Low level AMY control
 

tulip/shared/py/tulip.py

@@ -41,6 +41,48 @@ def add_to_bootpy(s, only_first_create=False):
         w.write(bootpy)
         w.close()
 
+# Save the current state of every AMY synth (0..31) as amy.send_raw() commands
+# at the bottom of a file that runs at boot (default: your boot.py), so your
+# synth setup comes back on the next boot. Re-saving replaces the previously
+# saved block instead of adding another copy.
+_SYNTH_STATE_BEGIN = "# -- synth state saved by tulip.save_synth_state() --"
+_SYNTH_STATE_END = "# -- end saved synth state --"
+
+def save_synth_state(fn=None):
+    if "WEB" in board():
+        print("save_synth_state is not available on web builds")
+        return
+    if fn is None:
+        fn = root_dir() + 'user/boot.py'
+    raws = []
+    for synth in range(32):
+        for command in amy_get_synth_commands(synth):
+            if command:
+                raws.append('i%d%s' % (synth, command))
+    try:
+        source = open(fn, 'r').read()
+    except OSError:
+        source = ""  # file doesn't exist yet
+    # Drop any previously saved block so re-saving doesn't stack copies.
+    begin = source.find(_SYNTH_STATE_BEGIN)
+    if begin != -1:
+        end = source.find(_SYNTH_STATE_END, begin)
+        tail = source[end + len(_SYNTH_STATE_END):] if end != -1 else ""
+        source = source[:begin].rstrip('\n') + '\n' + tail.lstrip('\n')
+    if not raws:
+        print("No synths are set up, nothing to save.")
+        return
+    block = [_SYNTH_STATE_BEGIN, "import amy"]
+    block += ["amy.send_raw(%r)" % r for r in raws]
+    block.append(_SYNTH_STATE_END)
+    source = source.rstrip('\n')
+    if source:
+        source += '\n\n'
+    w = open(fn, 'w')
+    w.write(source + '\n'.join(block) + '\n')
+    w.close()
+    print("Saved %d synth commands to %s" % (len(raws), fn))
+
 # Wrapper around AMY tempo to store it
 amy_bpm = 108
 def seq_bpm(bpm=None):