Radionelle - internet radio station for the Organelle
=====================================================
by gur_shulman - v1.0

Internet radio as an instrument: one tuning dial like an old radio, your
24 favourite stations on the keys, thousands more from around the world,
and a radio you can play with - DJ filter, pitch, warm / FM / old radio
tones, bass / treble, reverb and a loop recorder.

NEEDS
  An Organelle M or S2 on WiFi. Nothing to install (it uses Python and
  mpg123, which come with the Organelle). MP3 streams only - almost every
  station has one.

FINDING AND KEEPING STATIONS (no manual needed)
  Page 1 is the radio: one dial, the same VOLUME / FILTER / PITCH for every
  station. Page 2 SOURCE chooses what the dial holds:
    LOCAL   the stations of your country, spread over the dial like FM
            frequencies (88 - 108). The country is found by itself
            (SETUP > HOME = AUTO), or choose it
    WORLD   up to 100 stations from radio-browser.info - COUNTRY, GENRE
            and SORT (on the same page) open up as soon as WORLD is chosen
  Turn knob 1: the needle moves, the name shows at once, and the station
  plays when the knob rests. A station saved to a key plays from anywhere,
  LOCAL or WORLD.
  Keys 1-24 are your presets, on every page. They start empty: TAP an empty
  key and the station playing is saved there (SAVED TO PRESET 5). TAP a
  saved key = play it. HOLD any key for 1 s = save the station playing
  there instead.

CONTROLS
  ENCODER      turn = page, press = Organelle menu
  KEYS 1-24    tap = play that preset (an empty one: save the station
               playing there), hold 1 s = save the station playing there
               (MIDI notes 60-83 too)
  AUX          LOOP: hold = record what's on air (up to 30 s), let go = it
               loops, press again = back to the radio (MIDI CC25 too)
  AUX + press  reset every setting

PAGES (4 knobs each; the boxes at the top show where you are)
  RADIO     TUNE | VOLUME | FILTER | PITCH
  SOURCE    SOURCE | COUNTRY | GENRE | SORT
  SOUND     TONE | BASS | TREBLE | REVERB
  CONTROL   AUX | KNOBS | OUTPUT | SLEEP
  SETUP     HOME | LANG | STATIC | START

  TUNE      the dial (LOCAL or WORLD stations, as SOURCE says)
  SOURCE    LOCAL / WORLD
  VOLUME    OFF ... +4 dB
  FILTER    one-knob DJ filter: left = low pass, right = high pass,
            middle = OFF
  PITCH     -12 ... +12 semitones
  COUNTRY   ANY or one of 49 countries; GENRE ANY or one of 27; SORT
            POPULAR / TOP VOTED / RANDOM
  TONE      CLEAN / WARM / FM / OLD (an old tube radio)
  BASS, TREBLE  +/- 12 dB
  REVERB    a warm room
  AUX       LOOP / ON/OFF (the radio off and on again) / OFF
  HOME      the country of the LOCAL dial: AUTO (found by itself) or one
            of 49 countries
  LANG      only WORLD stations in one language (ANY, HEBREW, ENGLISH ...)
  KNOBS     JUMP (the value follows the knob) / CATCH (turn past the
            value to take over) / RELATIVE (moves from where it is)
  STATIC    the tuning noise between stations, OFF = silent tuning
  SLEEP     OFF / 15 / 30 / 60 / 90 MIN: fades out and turns off
  OUTPUT    STEREO / MONO
  START     LAST STATION (plays what you heard last time) / SILENT

THE SCREEN
  Page 1 is the radio: the dial with a needle, the station name,
  the song under it and the artist, and at the bottom - always in the
  same place - LOCAL or WORLD and where you are (97.4, 23/100, P5 =
  preset 5), next to a level meter (or REC / LOOP, or the SLEEP minutes
  left). Long song names scroll. Some stations don't send song names -
  then only the station name shows. Turn another knob and its value pops up. Messages: TUNING..., NO SIGNAL, NO
  INTERNET, STATION NOT SUPPORTED (not MP3), PRESET 5 IS EMPTY.
  LED: red = recording, blue = loop, purple = radio off, yellow = tuning.

STATIONS FILE
  stations.txt: your 24 presets, one per line (NAME | URL), in key order.
  Saving with a key writes it for you; you can also edit it in the
  Organelle web editor. The first time you load Radionelle it plays the
  first LOCAL station, and all 24 presets are empty. Radionelle finds its
  stations through radio-browser.info, a free community directory.

SETTINGS
  Saved by themselves (radionelle_settings.txt). AUX + press = defaults.

TECHNICAL
  run.sh starts radionelle_helper.py and Pd. The helper connects to the
  station, reads song titles, decodes with mpg123 and hands the audio to
  Pd through memory (/dev/shm), gap-free; it also draws page 1 and gets
  the WORLD lists. Names and titles in any language (Hebrew, Russian,
  Greek ... drawn by Radionelle itself). Log: /tmp/radionelle.log.
  Pure Data vanilla, no externals.

VERSION HISTORY
  v1.0    First release.

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