How NiCMidi plays MIDI

If we want to play the contents of a MIDIMultiTrack we must send them to an hardware MIDI port with accurate timing.

As said in previous sections, this can easily be done by the AdvancedSequencer object. This section is a more in-depth examination of how this is done by mean of some library classes.

The MIDITimer class

The MIDITimer is a static class that provides MIDI timing. This is accomplished by starting a background thread that calls a user-defined callback function at a regular rate. The timing is provided by the C++ <std::chrono> classes, so you need to compile the library according to (at least) the C++ 0x11 standard; the default temporal resolution is 10 msecs, but you can change it with the MIDITimer::SetResolution() method.

When playing MIDI, the timer is usually controlled by the MIDIManager class (described later), so it is rarely necessary to use its methods directly. You may find useful its MIDITimer::Wait() method (which waits a certain number of milliseconds) or the MIDITimer::GetSysTimeMs() method (which returns the absolute time in milliseconds from the class instantiation).

The MIDIOutDriver and MIDIInDriver classes

The MIDIOutDriver and MIDIInDriver classes are objects which communicate between the library software and the hardware MIDI ports regardless the underlying OS; NiCMidi uses the RTMidi library of Gary Scavone (see http://www.music.mcgill.ca/~gary/rtmidi/) to have a common interface for all OS. Every port has an Id number and a readable name (given by the OS).

If you want to send (or receive) MIDI messages to (from) a port you must open it with the MIDIOutDriver::OpenPort() or MIDIInDriver::OpenPort() methods. The MIDIOutDriver has a method MIDIOutDriver::OutputMessage() which sends a MIDITimedMessage to the port; the MIDIInDriver is a bit more complicated, because it manages a queue for incoming messages, and you have various methods for inspecting them (see the class documentation for details).

However, when using the high-level objects of the library (such as AdvancedSequencer, MIDISequencer, MIDIRecorder, etc.), all the work (opening and closing ports, sending/receiving messages ...) is done by these classes, so even in this case the user rarely needs to use the methods of this class directly.

The MIDIManager class

The MIDIManager is a static class that handles the temporized communications between the software and the hardware MIDI ports.

• Ports: when the manager is instantiated it enumerates all the hardware ports, then creates a MIDIOutDriver for each out port and a MIDIInDriver for each in port; you can get the ports id, their name and a pointer to their driver via static class methods. Here is an example which enumerates the MIDI ports on your system.

  #include "manager.h"
  #include <iostream>
   
  int main() {
     std::cout << "YOUR MIDI OUT PORTS" << std::endl;
     for(unsigned int i = 0, i < MIDIManager::GetNumMIDIOuts(), i++)
        std:cout << "Port " << i << ": " << MIDIManager::GetMIDIOutName(i) << std::endl;
     std::cout << "YOUR MIDI IN PORTS" << std::endl;
     for(unsigned int i = 0, i < MIDIManager::GetNumMIDIIns(), i++)
        std:cout << "Port " << i << ": " << MIDIManager::GetMIDIInName() << std::endl;
     return 0;
  }

• Timing: The manager takes the control of the (also static) MIDITimer, redirecting its background thread to call the static method MIDIManager::TickProc() at every timer tick.
• Communications with other classes: The MIDIManager handles a queue of MIDITickComponent objects (i.e. objects "which have a callback", see below): it can insert a pointer to such an object in the queue with the MIDIManager::AddMIDITick() method and remove it with MIDIManager::RemoveMIDITick(). The MIDIManager::TickProc() (which is called at every timer tick) calls in turn all the callbacks of the queued objects, giving them the absolute time as parameter. So every MIDITickComponent object can perform its tasks with accurate timing. This is a sketch of MIDIManager calling mechanism:
  

This modular design allows the user to stack many components which all share the same timing (for example a sequencer, a metronome, a recorder ...) and encourages him to develop its own objects.

The MIDITickComponent class

The core of MIDI timed playback is the pure virtual MIDITickComponent class: this is the prototype for all objects that have a callback procedure to be called at every tick of the MIDITimer; the AdvancedSequencer, MIDISequencer, MIDIThru, Metronome and MIDIRecorder classes all inherit from it. Let us analyze its most important methods:

• The constructor MIDITickComponent::MIDITickComponent(tPriority pr, MIDITick func) must be called by your subclass constructor. See its documentation for details on the parameters. It adds the newly created object to the MIDIManager queue with the MIDIManager::AddMIDITick() method to make it effective, so the component is ready to play.
• The destructor MIDITickComponent::~MIDITickComponent() removes the component from the MIDIManager queue in order to prevent the use of an invalid pointer, so you do not need to call MIDIManager::RemoveMIDITick().
• The MIDITickComponent::Start() method enables the callback. Moreover, it initializes the internal parameter MIDITickComponent::sys_time_offset to the start absolute time, so every subsequent call of the callback can perform time calculations. You may want to redefine it in your subclass in order to initialize your component at start (for example, in the derived classes of the library it opens the appropriate MIDI ports).
• The MIDITickComponent::Stop() method disables the callback (again, you can redefine it if you want to perform ending operations).

Due to the difficulty of calling member functions as callbacks in C++ this class actually needs two methods (one static and one member) to implement the callback mechanism:

• The static MIDITickComponent::StaticTickProc(tMsecs sys_time, void* p) is called by the MIDIManager, getting as parameters the absolute system time and the this pointer of the class instance as a void. This does nothing in the base class, and you must redefine it in your subclass. It only should cast the pointer to point to the derived class and then call the (virtual) member callback. For example:

  void MyClass::StaticTickProc(tMsecs sys_time, void* p) {
     MyClass* my_pt = static_cast<MyClass*>(p);
     my_pt->TickProc(sys_time);
  }

• The member MIDITickComponent::TickProc(tMsecs sys_time) is pure virtual in the base class: you must implement it and do all your work here. You can know the number of msecs elapsed from the Start() call with sys_time - sys_time_offset and use it to perform time calculations and send, receive or manipulate MIDI messages with accurate timing.

This is an example of the usage of the Metronome:

#include "metronome.h"
#include "manager.h"
 
int main() {
   Metronome metro;                   // creates the metronome and adds it to the
                                      // MIDIManager queue
   metro.SetTempo(100);               // sets the musical tempo
   metro.Start();
   MIDITimer::Wait(10000);            // waits 10 seconds
   metro.Stop();
}

In the AdvancedSequencer class the Start() method is aliased with Play(), following the ordinary naming conventions in a sequencer.

More detailed examples of the usage of the derived classes are in the following files:

• test_thru.cpp (use of MIDIThru)
• test_metronome.cpp (use of Metronome)
• test_sequencer.cpp (use of MIDISequencer)
• test_component.cpp shows a simple example of subclass.