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