1/*! 2\page midi2 The new Midi Kit (libmidi2.so) 3 4The Midi Kit is the API that implements support for generating, processing, and 5playing music in MIDI format. <A HREF="http://www.midi.org/">MIDI</A>, which 6stands for 'Musical Instrument Digital Interface', is a well-established 7standard for representing and communicating musical data. 8 9\section midi2twokits The two kits 10 11The BeOS comes with two different, but compatible Midi Kits. This documentation 12focuses on the "new" Midi Kit, or midi2 as we like to call it, that was 13introduced with BeOS R5. The old kit, which we'll refer to as midi1, is more 14complete than the new kit, but less powerful. 15 16Both kits let you create so-called MIDI endpoints, but the endpoints from midi1 17cannot be shared between different applications. The midi2 kit solves that 18problem, but unlike midi1 it does not include a General MIDI softsynth, nor 19does it have a facility for reading and playing Standard MIDI Files. Don't 20worry: both kits are compatible and you can mix-and-match them in your 21applications. 22 23The main differences between the two kits: 24 25- Instead of one BMidi object that both produces and consumes events, we have 26BMidiProducer and BMidiConsumer. 27- Applications are capable of sharing MIDI producers and consumers with other 28applications via the centralized Midi Roster. 29- Physical MIDI ports are now sharable without apps "stealing" events from each 30other. 31- Applications can now send/receive raw MIDI byte streams (useful if an 32application has its own MIDI parser/engine). 33- Channels are numbered 0..15, not 1..16 34- Timing is now specified in microseconds instead of milliseconds. 35 36\section midi2concepts Midi Kit concepts 37 38A brief overview of the elements that comprise the Midi Kit: 39 40- \b Endpoints. This is what the Midi Kit is all about: sending MIDI messages 41between endpoints. An endpoint is like a MIDI In or MIDI Out socket on your 42equipment; it either receives information or it sends information. Endpoints 43that send MIDI events are called \b producers; the endpoints that receive those 44events are called \b consumers. An endpoint that is created by your own 45application is called \b local; endpoints from other applications are \b 46remote. You can access remote endpoints using \b proxies. 47 48- \b Filters. A filter is an object that has a consumer and a producer 49endpoint. It reads incoming events from its consumer, performs some operation, 50and tells its producer to send out the results. In its current form, the Midi 51Kit doesn't provide any special facilities for writing filters. 52 53- \b Midi \b Roster. The roster is the list of all published producers and 54consumers. By publishing an endpoint, you allow other applications to talk to 55it. You are not required to publish your endpoints, in which case only your own 56application can use them. 57 58- \b Midi \b Server. The Midi Server does the behind-the-scenes work. It 59manages the roster, it connects endpoints, it makes sure that endpoints can 60communicate, and so on. The Midi Server is started automatically when BeOS 61boots, and you never have to deal with it directly. Just remember that it runs 62the show. 63 64- \b libmidi. The BMidi* classes live inside two shared libraries: libmidi.so 65and libmidi2.so. If you write an application that uses old Midi Kit, you must 66link it to libmidi.so. Applications that use the new Midi Kit must link to 67libmidi2.so. If you want to mix-and-match both kits, you should also link to 68both libraries. 69 70Here is a pretty picture: 71 72\image html midi2concepts.png 73 74\section midi2mediakit Midi Kit != Media Kit 75 76Be chose not to integrate the Midi Kit into the Media Kit as another media 77type, mainly because MIDI doesn't require any of the format negotiation that 78other media types need. Although the two kits look similar -- both have a 79"roster" for finding or registering "consumers" and "producers" -- there are 80some very important differences. 81 82The first and most important point to note is that BMidiConsumer and 83BMidiProducer in the Midi Kit are NOT directly analogous to BBufferConsumer and 84BBufferProducer in the Media Kit! In the Media Kit, consumers and producers are 85the data consuming and producing properties of a media node. A filter in the 86Media Kit, therefore, inherits from both BBufferConsumer and BBufferProducer, 87and implements their virtual member functions to do its work. 88 89In the Midi Kit, consumers and producers act as endpoints of MIDI data 90connections, much as media_source and media_destination do in the Media Kit. 91Thus, a MIDI filter does not derive from BMidiConsumer and BMidiProducer; 92instead, it contains BMidiConsumer and BMidiProducer objects for each of its 93distinct endpoints that connect to other MIDI objects. The Midi Kit does not 94allow the use of multiple virtual inheritance, so you can't create an object 95that's both a BMidiConsumer and a BMidiProducer. 96 97This also contrasts with the old Midi Kit's conception of a BMidi object, which 98stood for an object that both received and sent MIDI data. In the new Midi Kit, 99the endpoints of MIDI connections are all that matters. What lies between the 100endpoints, i.e., how a MIDI filter is actually structured, is entirely at your 101discretion. 102 103Also, rather than use token structs like media_node to make connections via the 104MediaRoster, the new kit makes the connections directly via the BMidiProducer 105object. 106 107\section midi2remotelocal Remote and local objects 108 109The Midi Kit makes a distinction between remote and local MIDI objects. You can 110only create local MIDI endpoints, which derive from either BMidiLocalConsumer 111or BMidiLocalProducer. Remote endpoints are endpoints that live in other 112applications, and you access them through BMidiRoster. 113 114BMidiRoster only gives you access to BMidiEndpoints, BMidiConsumers, and 115BMidiProducers. When you want to talk to remote MIDI objects, you do so through 116the proxy objects that BMidiRoster provides. Unlike BMidiLocalConsumer and 117BMidiLocalProducer, these classes do not provide a lot of functions. That is 118intentional. In order to hide the details of communication with MIDI endpoints 119in other applications, the Midi Kit must hide the details of how a particular 120endpoint is implemented. 121 122So, what can you do with remote objects? Only what BMidiConsumer, 123BMidiProducer, and BMidiEndpoint will let you do. You can connect objects, get 124the properties of these objects -- and that's about it. 125 126\section midi2lifespan Creating and destroying objects 127 128The constructors and destructors of most midi2 classes are private, which mean 129you cannot directly create them using the C++ <CODE>new</CODE> operator, on the 130stack, or as globals. Nor can you <CODE>delete</CODE> them. Instead, these 131objects are obtained through BMidiRoster. The only two exceptions to this rule 132are BMidiLocalConsumer and BMidiLocalProducer. These two objects may be 133directly created and subclassed by developers. 134 135\section midi2refcount Reference counting 136 137Each MIDI endpoint has a reference count associated with it, so that the Midi 138Roster can do proper bookkeeping. When you construct a BMidiLocalProducer or 139BMidiLocalConsumer endpoint, it starts with a reference count of 1. In 140addition, BMidiRoster increments the reference count of any object it hands to 141you as a result of \link BMidiRoster::NextEndpoint() NextEndpoint() \endlink or 142\link BMidiRoster::FindEndpoint() FindEndpoint() \endlink. Once the count hits 1430, the endpoint will be deleted. 144 145This means that, to delete an endpoint, you don't call the <CODE>delete</CODE> 146operator directly; instead, you call \link BMidiEndpoint::Release() Release() 147\endlink. To balance this call, there's also an \link BMidiEndpoint::Acquire() 148Acquire() \endlink, in case you have two disparate parts of your application 149working with the endpoint, and you don't want to have to keep track of who 150needs to Release() the endpoint. 151 152When you're done with any endpoint object, you must Release() it. This is true 153for both local and remote objects. Repeat after me: Release() when you're done. 154 155\section midi2events MIDI events 156 157To make some actual music, you need to \link BMidiProducer::Connect() Connect() 158\endlink your consumers to your producers. Then you tell the producer to 159"spray" MIDI events to all the connected consumers. The consumers are notified 160of these incoming events through a set of hook functions. 161 162The Midi Kit already provides a set of commonly used spray functions, such as 163\link BMidiLocalProducer::SprayNoteOn() SprayNoteOn() \endlink, \link 164BMidiLocalProducer::SprayControlChange() SprayControlChange() \endlink, and so 165on. These correspond one-to-one with the message types from the MIDI spec. You 166don't need to be a MIDI expert to use the kit, but of course some knowledge of 167the protocol helps. If you are really hardcore, you can also use the \link 168BMidiLocalProducer::SprayData() SprayData() \endlink to send raw MIDI events to 169the consumers. 170 171At the consumer side, a dedicated thread invokes a hook function for every 172incoming MIDI event. For every spray function, there is a corresponding hook 173function, e.g. \link BMidiLocalConsumer::NoteOn() NoteOn() \endlink and \link 174BMidiLocalConsumer::ControlChange() ControlChange() \endlink. The hardcore MIDI 175fanatics among you will be pleased to know that you can also tap into the \link 176BMidiLocalConsumer::Data() Data() \endlink hook and get your hands dirty with 177the raw MIDI data. 178 179\section midi2time Time 180 181The spray and hook functions accept a bigtime_t parameter named "time". This 182indicates when the MIDI event should be performed. The time is given in 183microseconds since the computer booted. To get the current tick measurement, 184you call the system_time() function from the Kernel Kit. 185 186If you override a hook function in one of your consumer objects, it should look 187at the time argument, wait until the designated time, and then perform its 188action. The preferred method is to use the Kernel Kit's 189<CODE>snooze_until()</CODE> function, which sends the consumer thread to sleep 190until the requested time has come. (Or, if the time has already passed, returns 191immediately.) 192 193Like this: 194 195\code 196void MyConsumer::NoteOn( 197 uchar channel, uchar note, uchar velocity, bigtime_t time) 198{ 199 snooze_until(time, B_SYSTEM_TIMEBASE); 200 ...do your thing... 201} 202\endcode 203 204If you want your producers to run in real time, i.e. they produce MIDI data 205that needs to be performed immediately, you should pass time 0 to the spray 206functions (which also happens to be the default value). Since time 0 has 207already passed, <CODE>snooze_until()</CODE> returns immediately, and the 208consumer will process the events as soon as they are received. 209 210To schedule MIDI events for a performance time that lies somewhere in the 211future, the producer must take into account the consumer's latency. Producers 212should attempt to get notes to the consumer by or before 213<I>(scheduled_performance_time - latency)</I>. The time argument is still the 214scheduled performance time, so if your consumer has latency, it should snooze 215like this before it starts to perform the events: 216 217\code 218snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); 219\endcode 220 221Note that a typical producer sends out its events as soon as it can; unlike a 222consumer, it does not have to snooze. 223 224\section midi2ports Other timing issues 225 226Each consumer object uses a Kernel Kit port to receive MIDI events from 227connected producers. The queue for this port is only 1 message deep. This means 228that if the consumer thread is asleep in a <CODE>snooze_until()</CODE>, it will 229not read its port. Consequently, any producer that tries to write a new event 230to this port will block until the consumer thread is ready to receive a new 231message. This is intentional, because it prevents producers from generating and 232queueing up thousands of events. 233 234This mechanism, while simple, puts on the producer the responsibility for 235sorting the events in time. Suppose your producer sends three Note On events, 236the first on t + 0, the second on t + 4, and the third on t + 2. This last 237event won't be received until after t + 4, so it will be two ticks too late. If 238this sort of thing can happen with your producer, you should somehow sort the 239events before you spray them. Of course, if you have two or more producers 240connected to the same consumer, it is nearly impossible to sort this all out 241(pardon the pun). So it is not wise to send the same kinds of events from more 242than one producer to one consumer at the same time. 243 244The article Introduction to MIDI, Part 2 in <A 245HREF="http://open-beos.sourceforge.net/nsl.php?mode=display&id=36">OpenBeOS 246Newsletter 36</A> describes this problem in more detail, and provides a 247solution. Go read it now! 248 249\section midi2filters Writing a filter 250 251A typical filter contains a consumer and a producer endpoint. It receives 252events from the consumer, processes them, and sends them out again using the 253producer. The consumer endpoint is a subclass of BMidiLocalConsumer, whereas 254the producer is simply a BMidiLocalProducer, not a subclass. This is a common 255configuration, because consumers work by overriding the event hooks to do work 256when MIDI data arrives. Producers work by sending an event when you call their 257member functions. You should hardly ever need to derive from BMidiLocalProducer 258(unless you need to know when the producer gets connected or disconnected, 259perhaps), but you'll always have to override one or more of 260BMidiLocalConsumer's member functions to do something useful with incoming 261data. 262 263Filters should ignore the time argument from the spray and hook functions, and 264simply pass it on unchanged. Objects that only filter data should process the 265event as quickly as possible and be done with it. Do not 266<CODE>snooze_until()</CODE> in the consumer endpoint of a filter! 267 268\section midi2apidiffs API differences 269 270As far as the end user is concerned, the OpenBeOS Midi Kit is mostly the same 271as the BeOS R5 kits, although there are a few small differences in the API 272(mostly bug fixes): 273 274- BMidiEndpoint::IsPersistent() always returns false. 275- The B_MIDI_CHANGE_LATENCY notification is now properly sent. The Be kit 276 incorrectly set be:op to B_MIDI_CHANGED_NAME, even though the rest of the 277 message was properly structured. 278- If creating a local endpoint fails, you can still Release() the object 279 without crashing into the debugger. 280 281\section midi2seealso See also 282 283More about the Midi Kit: 284 285- \ref midi2defs 286- Be Newsletter Volume 3, Issue 47 - Motor Mix sample code 287- Be Newsletter Volume 4, Issue 3 - Overview of the new kit 288- <A HREF="http://open-beos.sourceforge.net/nsl.php?mode=display&id=33">OpenBeOS 289 Newsletter 33</A>, Introduction to MIDI, Part 1 290- <A HREF="http://open-beos.sourceforge.net/nsl.php?mode=display&id=36">OpenBeOS 291 Newsletter 36</A>, Introduction to MIDI, Part 2 292- Sample code and other goodies at the 293 <A HREF="http://open-beos.sourceforge.net/tms/team.php?id=13">OpenBeOS Midi Kit team page</A> 294 295Information about MIDI in general: 296 297- <A HREF="http://www.midi.org">MIDI Manufacturers Association</A> 298- <A HREF="http://www.borg.com/~jglatt/tutr/miditutr.htm">MIDI Tutorials</A> 299- <A HREF="http://www.borg.com/~jglatt/tech/midispec.htm">MIDI Specification</A> 300- <A HREF="http://www.borg.com/~jglatt/tech/midifile.htm">Standard MIDI File Format</A> 301- <A HREF="http://www.io.com/~jimm/midi_ref.html">Jim Menard's MIDI Reference</A> 302 303*/ 304
