SETLIST - song switcher for the Organelle
=========================================
by gur_shulman - v1.0

Turn the Organelle into a live rig. Make named setlists out of any patch you
have - also patches in sub-folders, and every kind of patch (Pd, Python,
SuperCollider...): everything works the same with all of them.

Every song is its own copy of a patch with its own settings: pick a patch,
edit it the way the song needs, SAVE it as a song - like the program memory
of a synth. Songs never touch the patches in your Patches folder, and
changing a patch never touches your songs. Every song has its own VOLUME,
so the whole set sits at one level.

Switch songs from Setlist, with MIDI Program Change, or from the Organelle
menu. Out of the box Setlist adds nothing to the footswitch or AUX, so it
never gets in the way of what your patches do with them.

CONTROLS (inside Setlist)
  ENCODER      turn = move, press = choose
               on a song: press = PLAY, hold = the song's menu
  KNOB 1       fast scroll (letters in the name editor, level in VOLUME)
  KNOB 2       cursor in the name editor
  AUX          nothing by default (SETTINGS > AUX = BACK if you like it)
  FOOTSWITCH   nothing by default (SETTINGS > FOOTSWITCH)
  MIDI PC      Program Change 1 = song 1, 2 = song 2 ...

MAKE A SETLIST
  1  + NEW SETLIST, give it a name (turn = letter, press = next letter,
     choose OK at the end - or CANCEL)
  2  + ADD SONG, choose a patch (folders open with a press, < UP goes back)
  3  EDIT, THEN SAVE: the patch opens - set it up for this song
     (or ADD AS IT IS to add it the way it is)
  4  when it's ready, leave the patch the way you always do (the way that
     normally takes you to the Organelle menu). You land straight on
     Setlist's SAVE screen:
       SAVE             give the song a name - done
       KEEP EDITING     back to the patch
       DISCARD CHANGES  throw the edit away
       SETLIST HOME     decide later: it waits as "* UNSAVED CHANGES" on
                        the Setlist main page
       ORGANELLE MENU   the same, and go to the Organelle menu
     Nothing you edit gets lost: it is saved every few seconds while you
     work, even if the Organelle is switched off.
     (Patches that use the encoder for themselves: press the encoder to
     open the Organelle menu and choose "~ SETLIST".)

A SONG'S MENU (hold the encoder on a song)
  PLAY
  EDIT           edit the song again, then SAVE (replaces it) or
                 SAVE AS NEW SONG (e.g. the same patch for another part)
  VOLUME         the song's level, -30 ... +12 dB (0 dB = as the patch is)
  RENAME
  MOVE           turn to move it, press to drop it
  DUPLICATE
  CHANGE PATCH   another patch for this song (keeps name and volume)
  DELETE

OPTIONS (in a setlist)
  FOOTSWITCH    PATCH (default) = the footswitch does what each patch does
                NEXT = the footswitch goes to the next song, in every
                       song of this setlist
  AFTER LAST    (with NEXT) SETLIST = back to Setlist after the last song,
                SONG 1 = start the set again
  LIVE CHANGES  RESET (default) = a song always starts the way it was
                        saved: what you change while playing is forgotten
                        when you change song
                KEEP  = what you change while playing is saved in the song
                        by itself (auto save)
  ALL VOLUMES   every song's level on one page - press one to change it
  GO LIVE       make this setlist the live one without playing a song
  RENAME / DUPLICATE / DELETE SETLIST

SETTINGS (Setlist main page)
  OPEN ON          LIVE = Setlist opens on the live setlist, on the song
                   you played last / ALL = on the list of setlists
  PLAY WITH        1 PRESS / 2 PRESS (press again to play - safer on a
                   dark stage)
  ADD SONGS        AT END of the setlist / AFTER the selected song
  KNOB 1           SCROLLS the lists / OFF
  FOOTSWITCH       inside Setlist: OFF (default) / PLAY = plays the
                   selected song / NEXT = plays the song after the one you
                   played last, so tap - play - tap ...
  AUX              inside Setlist: OFF (default) / BACK = AUX goes back,
                   AUX + press = Organelle menu
  PROGRAM CHANGE   ON / OFF
  PC CHANNEL       ALL / 1 ... 16
  RESTORE FAVOURITES  (only shown when Setlist changed them, see below)

PLAYING LIVE
  "LIVE" in the title shows which setlist is live. Playing a song makes its
  setlist live.
  - Program Change n = song n of the live setlist, from inside any song or
    from Setlist
  - press the encoder in a song: the Organelle menu shows the songs of the
    setlist in order - turn and press to switch. The last entry,
    "~ SETLIST", takes you back to Setlist
  - footswitch = next song (OPTIONS > FOOTSWITCH = NEXT)
  When you leave Setlist for the Organelle menu, the menu shows your
  patches as always.

TIP: EFFECTS
  Using the Organelle mostly as an effect, with songs where you just want
  your instrument to go straight through? Add my PASSTHRU patch as a song.

VOLUME - GOOD TO KNOW
  The Organelle volume knob keeps working on top of every song's VOLUME.
  Some patches play straight to the output and skip the volume knob - in
  the song copies Setlist sends them through the normal output, so the knob
  and the song VOLUME work for them too.

FAVOURITES
  Setlist leaves your Favourites alone. Only a setlist with FOOTSWITCH =
  NEXT uses them while it is live (the Organelle steps through Favourites
  with the footswitch); your own list is kept in
  Setlists/.favourites_backup.txt and comes back by itself when that
  setlist is no longer live (or with SETTINGS > RESTORE FAVOURITES).

GOOD TO KNOW
  - Songs live in a Setlists folder next to your Patches folder. Every song
    is a full copy of its patch, so sample patches take their full size per
    song. Setlist checks the free space first.
  - With LIVE CHANGES = RESET, small files a patch writes while you play
    (settings, knob positions, also recordings under 2 MB) are put back the
    way they were saved when you leave the song.
  - A small helper (setlist_helper.py) runs in the background while a
    setlist is live (Program Change in every song, VOLUME, RESET / KEEP).
  - Setlists are plain folders: back them up or rename them on a computer.
  - The splash shows only the first time Setlist opens after you switch the
    Organelle on.

REQUIREMENTS
  Organelle OS 5 or newer (songs load by their folder). Runs as a Python
  patch (main.py), no sound of its own.

LICENSE
  WTFPL - Do What The F*ck You Want To Public License.
