MuMRT (MIDI playback vs. Csound playback)

This release consists of a reorganization of all the playback funcionality available in the Library. The changes presented here were actually done in small increments, over the past 4 years, since the introdution of realtime playback in 2019. However as we ended up skipping a version along the way, the curent release number jumped from v1.0.5 to v1.0.7. Release 1.0.6 was never released! ;-)

Here are th important changes in v1.0.7

1) LINUX SUPPORT:

A few months after the start of our realtime functionality, we added Linux support through RtMidi over ALSA. The idea was to port all MIDI code to RtMidi as well, so that we only had to do a few changes in compilation in order to reach all three major platforms. Howeve,r it turned out that on the Mac OS side RtMidi was calling exactly the same stuff we used to implement directly to CoreMIDI. So, for the sake of efficiency we kept the Mac OS code and used a few macros to isolate the platforms on critical code. So, to make a long story short, we now have realtime playback on both Linux and Mac. Windows is out for now (although I suspect that someone with Windows coding experience could probably get it to work in no time).
Note: Linux code is probably still pretty somewhat buggy as we haven't been able to do a lot of testing (any volunteers?).

2) CSOUND vs MIDI:

We now have basically two sets of methods to use for playback:

- CSOUND Output

The first one is the old Csound implementation, for which you can make instrument selections and play using the usual methods (listed bellow). It is important to note that this funcionality will block synchronally untill playback is over. Futhermore, the timbre choices are limited to four very simple Csound instruments that are defined inside MuMaterial as a placeholder/default orchestra. in order to explore more interesting sounds it is necessary to use (or borrow) Csound code to make a custom orquestra file, which can than be loaded to any material. If instead playingback from your code, you prefer to save the output for playing later, it is possible to generate Csound files from any material in two formats: .sco and .csd.

• MuNote::SetInstr() - sets instrument number for individual notes
• MuMaterial::LoadOrchestra() - loads a Csound orquesra file into the material
• MuMaterial::SetInstrument() - sets instrument numbers all notes in a given voice
• MuMaterial::PlaybackWithCsound()) - makes a system call to Csound
• MuMaterial::Score() - generates Csound score file with the note contents of the material
• MuMaterial::Csd() - generates Csound .csd file with material's notes and the orchestra defined within it

- MIDI Output

The second option is to use the MIDI realtime classes which allow for playing and recording MIDI at any point in the code, without blocking. In order to use this part of the Library for playback, you need to assign a MIDI channel number to each voice you wish to playback and then send MIDI instrument selection messages (Program Changes) through each channel to prepare the synthesizer for producing sounds, before calling Play(). This approach assumes you have a General MIDI (GM) compatible synthesizer running at the time your code executes. The preparation for using MIDI playback is done in more than one class, as described bellow:

• MuMaterial::SetChannel() - assigns a MIDI channel number to a given voice
• MuPlayer::Send ProgramChanges() - requests instrument selection in GM format thrugh a given channel
• MuPlayer::SendEvents() - sends other required MIDI messages to MIDI destination
• MPlayer::Play() - schedules material for playback

Note: here all instrument choices within the material are ignored. We simply decide on which channel we want to play and ask the synth to use a sound we want in that channel (piano, violine, flute, etc.). Then, when you call Play() all notes within the material are qeued for playback with MidiOn/MidiOff messages, which now nothing about timbre.

3) DOCUMENTATION

Starting with this release, the Reference Documentation for MuMRT will start to be made available here, at the Library's source code repository. The MuMDocs repo will be used only for manuals, tutorials, examples, etc. This way it will be easier for someone to grab all the important information, in an easy, digested format (HTML), along with the code. The Reference continues to be generated as HTML and UNIX man pages, using doxygen on comments from the source code itself.

MuMDocs repository will probably undergo some serious overhauling (whenever I have some time available for this), or it may be closed for good, in which case, all documentation will migrate to added files here at the Library releases. Time will tell. The important thing is that from now on, MuMRT users will have up-to-date reference documentation along with every major release, all in one convenient place.

Carlos Eduardo Mello
Feb 8 2023

MuMRT (realtime MIDI playback and input)

This release introduces MuM's realtime facilities for MIDI playback and input. This new functionality is defined in two new classes: MuPlayer and MuRecorder. It also includes some reorganizing of files and adds support methods in the primary classes for the realtime code.

Platform Issues

As MIDI i/o involves platform dependent code, it became necessary to include it in here. Current implementation of MuPlayer and MuRecorder will be compatible only with CoreMIDI (Mac OS X). There are plans for a Linux version soon (Windows compatibility is not part of the roadmap at this point). However, if compilation leaves out header and implementation files for both realtime classes, the rest of the library is still platform agnostic and can be compiled against old projects.

Changes

The list bellow shows the most significant changes:

MuPlayer - this class handles realtime playback. It uses a scheduling thread to run playback continuously and and temporary working threads to fill-up MIDI event queues and perform other pre-roll actions before data can be sent to MIDI system. User code can use MuM classes to generate musical materials and playback these materials at any time by calling Play(). See MuM-Docs for details.

MuRecorder - this class implements the library's MIDI input module. An MuRecorder object can be instantiated at the beginning of a MuMRT-based app. After initialized (Init()) it can continuously record MIDI note messages (no other events allowed) from any MIDI source in the system, and store it in its internal buffers. A call to GetData() retrieves all MIDI data accumulated in the buffers since the last call. See MuM-Docs for details.

MuMaterial - the primary class in MuM, MuMaterial can now load a MIDI buffer, as collected by MuRecorder, and populate itself with notes extracted from the buffer (LoadMIDIBuffer()). See MuM-Docs for details

MuUtil - Besides its other utility routines (Sort(), etc.), MuUtil now also defines all time related utilities, initially part of MuPlayer.

MuMIDI.h - this new header file contains all the MIDI definitions, structs and constants used in the library. Items like MuMIDIMessage, previously defined in MuNote, were transferred here to keep things cleaner. The file also includes MuMIDIBuffer.

MuM Library

This is what might be called a first alfa release of the MuM Library. It is the result of testing, revising and modifying the library with the feedback from students of "TTC - Algorithmic Composition" classes, during the first semester of 2016, at the University of Brasília. There are probably still quite a few bugs, but the code is fairly functional. Also there will likely be several improvements in the near future, as we work on implementing MIDI output and internal generation of other musical elements, such as chord, scales, etc. The corresponding Reference Manual for this release is available at the MuMDocs Project (look for Release v1.0.4)