# What this is

The ITL Chorus is a very simple, loosely bundled package for playing MIDI in
real time over a network. Presently, it consists of three different frontends:

- `mkiv.py`: Makes an *i*nter*v*al (`.iv`) file from a MIDI (usually `.mid`)
  file. The interval file is an XML document (easily compressed) consisting of
  the necessary information required to play back *voices* or *streams* such
  that no notes overlap (and duration information is available).
- `client.c`: A bare-minimum C program designed to run on even the most spartan
  Linux systems; it basically implements `beep` over UDP.
- `client.py`: A far-more-functional Python program with advanced options,
  using the pyaudio API.
- `broadcast.py`: Accepts an interval file, assigns clients to streams, and
  plays a piece in real time.

In general, you would use the tooling in precisely this order; generate an
interval file with `mkiv.py` from a good MIDI performance (of your own acquiry
:), either compile and run `./client` *as root* or run python client.py on all
the machines on a LAN that you would like to beep along, and then run
`broadcast.py` with the generated interval file on any machine also on that LAN
(potentially also one of the clients).

# Troubleshooting

In my experience, the most annoying errors come about as the following:

- No PC speaker. Many modern computers/motherboards omit this ancient piece of
  IBM technology entirely. Presumably, emulation is available (especially in
  desktop environments), but this normally requires a kernel-mode driver (as it
  has to respond to the very low-level syscall that actually would beep the
  speaker). ALSA purportedly provides snd_pcsp, but I've not seen it work yet.
  It should be noted that the python client.py script uses *regular* PCM
  speakers to operate, and so can work under these conditions.
- Network issues. `client` doesn't really check for any LAN, happily listening
  on whatever interfaces it can find at the time. Many very basic installations
  of Linux seem to not `dhclient` properly, even if the link is up, so you will
  want to make sure that your ip information is set up how you like it *before*
  running `client`.
- Lack of a compiler. Again, some bare-bones distributions don't ship with a
  compiler by default (I don't even know how you can use Linux like that :).
  Many nonetheless have package managers that will get a compiler and build
  environment for you. (On Debian and derivatives, `build-essential` works.)

Please submit an issue if something else seems off!

# Options

All the scripts here (except the C program) have a plethora of options, most
of which are documented both at the beginning of the source and if you simply
pass `--help` or `-h` to them. Feel free to experiment!

# Hacking

The .iv file format that is used extensively in communicating information is
certainly not any standard that I am aware of, but it seems like a rather
convenient standard for simple authorship. While I have no plans to write an
IV editor at the moment, that may change; in the meantime, whosoever would like
to do so should know the following about the IV files:

- They are in XML--go ahead and open them in your favorite XML browser!
- Their root element is "iv" with no decided namespace yet.
- Under the root, there is a "meta" element with metainformation about the
  compilation process--at present, this includes things like the "bpms" element
  which has a "bpm" for each time period parsed out of the original MIDI.
- Also under the root, and arguably most importantly, is the "streams" element
  that possesses all the "stream" elements that correspond to playable voices.
- Each stream has a "type" attribute which determines what it is ("ns" is a note
  stream--the ones that have playable notes, and "aux" is a stream of non-note
  MIDI events), and an optional "group" attribute which determines what group
  it belongs to (`broadcast.py` uses this for routing).
- All note streams (type="ns") *should* contain non-overlapping notes, in the
  sense that any "note" element in there should have a `time + dur` not greater
  than its next note. Additionally, all notes in such a stream *should* be
  sorted by time. Breaking either of these standards is not an egregious violation,
  and may prove to be interesting, but (at the moment) it will prevent `broadcast.py`
  from working properly. In addition, it should be noted that the clients are
  *designed* to overwrite one incoming note with the next, regardless of whether or
  not this interrupts the duration of the previous one--this is how "live mode" and "silence" work.

# Todo

- Polyphony--have multiple voices on one machine
  - Mixed polyphony: the audio is the result of mixing (saturating addition, etc.)--only doable with PCM
  - LFO polyphony: tones are "rapidly" switched between (how old microcomputers used to accomplish this with one beep speaker)
- Preloading--send events to clients early to avoid jitter problems with the network
  - Would require a network time synchronization to work effectively; makes the broadcaster have less control over nuanced timing
- Other stream types--e.g., PCM streams for raw audio data
  - More clientside implementation work
  - Definitely a higher bandwidth--might interfere with critical timing, and would almost certainly need preloading
- Percussion--implement percussive instruments
  - Requires an analysis of how current DAWs and MIDI editors mark "percussion" tracks--with a program change? GM specifies channel 10...
- Soundfonts--have the ability to significantly affect the instrumentation of the clients
  - Would also be nice to do this from the broadcaster's end without introducing RCE
  - Might require integration of another large libary like fluidsynth--at which point this would just be "networked MIDI" :)
- Code cleanup--make the entire project slightly more modular and palatable