stdout
+
+The following classes let you use the Midi Kit's General MIDI synthesizer:
+
+- BSynth controls the synthesizer
+- BMidiSynth connects a BMidi object to the synth
+- BMidiSynthFile connects a MIDI file to the synth
+- BSamples lets you access the synth's sound data stream
+
+To make MIDI data stream through your application, you create a "network" of
+BMidi-derived objects that send and receive MIDI messages.
+
+The old Midi Kit is slowly fading into obscurity. You may want to use the
+\ref midi2 "new kit" instead. Also note that the OpenBeOS implementation
+of the kit sometimes behaves differently than the one from BeOS R5 or what
+the BeBook says, but usually for the better ;-)
+
+Especially the synth classes are not completely functional, but enough to
+play back General MIDI tunes. They should be backwards compatible with the
+majority of BeOS MIDI applications. Not all methods of BSynth, BMidiSynth,
+and BMidiSynthFile are implemented because some of them are rather obscure.
+BSamples is a complete no-op; in other words, with the OpenBeOS Midi Kit
+you cannot push waveform data into the output stream of the softsynth.
+*/
diff --git a/docs/user/midi2/midi2concepts.png b/docs/user/midi2/midi2concepts.png
new file mode 100644
index 0000000000..2278a4d53b
Binary files /dev/null and b/docs/user/midi2/midi2concepts.png differ
diff --git a/docs/user/midi2/midi2intro.dox b/docs/user/midi2/midi2intro.dox
new file mode 100644
index 0000000000..5ba88c7654
--- /dev/null
+++ b/docs/user/midi2/midi2intro.dox
@@ -0,0 +1,303 @@
+/*!
+\page midi2 The new Midi Kit (libmidi2.so)
+
+The Midi Kit is the API that implements support for generating, processing, and
+playing music in MIDI format. MIDI, which
+stands for 'Musical Instrument Digital Interface', is a well-established
+standard for representing and communicating musical data.
+
+\section midi2twokits The two kits
+
+The BeOS comes with two different, but compatible Midi Kits. This documentation
+focuses on the "new" Midi Kit, or midi2 as we like to call it, that was
+introduced with BeOS R5. The old kit, which we'll refer to as midi1, is more
+complete than the new kit, but less powerful.
+
+Both kits let you create so-called MIDI endpoints, but the endpoints from midi1
+cannot be shared between different applications. The midi2 kit solves that
+problem, but unlike midi1 it does not include a General MIDI softsynth, nor
+does it have a facility for reading and playing Standard MIDI Files. Don't
+worry: both kits are compatible and you can mix-and-match them in your
+applications.
+
+The main differences between the two kits:
+
+- Instead of one BMidi object that both produces and consumes events, we have
+BMidiProducer and BMidiConsumer.
+- Applications are capable of sharing MIDI producers and consumers with other
+applications via the centralized Midi Roster.
+- Physical MIDI ports are now sharable without apps "stealing" events from each
+other.
+- Applications can now send/receive raw MIDI byte streams (useful if an
+application has its own MIDI parser/engine).
+- Channels are numbered 0..15, not 1..16
+- Timing is now specified in microseconds instead of milliseconds.
+
+\section midi2concepts Midi Kit concepts
+
+A brief overview of the elements that comprise the Midi Kit:
+
+- \b Endpoints. This is what the Midi Kit is all about: sending MIDI messages
+between endpoints. An endpoint is like a MIDI In or MIDI Out socket on your
+equipment; it either receives information or it sends information. Endpoints
+that send MIDI events are called \b producers; the endpoints that receive those
+events are called \b consumers. An endpoint that is created by your own
+application is called \b local; endpoints from other applications are \b
+remote. You can access remote endpoints using \b proxies.
+
+- \b Filters. A filter is an object that has a consumer and a producer
+endpoint. It reads incoming events from its consumer, performs some operation,
+and tells its producer to send out the results. In its current form, the Midi
+Kit doesn't provide any special facilities for writing filters.
+
+- \b Midi \b Roster. The roster is the list of all published producers and
+consumers. By publishing an endpoint, you allow other applications to talk to
+it. You are not required to publish your endpoints, in which case only your own
+application can use them.
+
+- \b Midi \b Server. The Midi Server does the behind-the-scenes work. It
+manages the roster, it connects endpoints, it makes sure that endpoints can
+communicate, and so on. The Midi Server is started automatically when BeOS
+boots, and you never have to deal with it directly. Just remember that it runs
+the show.
+
+- \b libmidi. The BMidi* classes live inside two shared libraries: libmidi.so
+and libmidi2.so. If you write an application that uses old Midi Kit, you must
+link it to libmidi.so. Applications that use the new Midi Kit must link to
+libmidi2.so. If you want to mix-and-match both kits, you should also link to
+both libraries.
+
+Here is a pretty picture:
+
+\image html midi2concepts.png
+
+\section midi2mediakit Midi Kit != Media Kit
+
+Be chose not to integrate the Midi Kit into the Media Kit as another media
+type, mainly because MIDI doesn't require any of the format negotiation that
+other media types need. Although the two kits look similar -- both have a
+"roster" for finding or registering "consumers" and "producers" -- there are
+some very important differences.
+
+The first and most important point to note is that BMidiConsumer and
+BMidiProducer in the Midi Kit are NOT directly analogous to BBufferConsumer and
+BBufferProducer in the Media Kit! In the Media Kit, consumers and producers are
+the data consuming and producing properties of a media node. A filter in the
+Media Kit, therefore, inherits from both BBufferConsumer and BBufferProducer,
+and implements their virtual member functions to do its work.
+
+In the Midi Kit, consumers and producers act as endpoints of MIDI data
+connections, much as media_source and media_destination do in the Media Kit.
+Thus, a MIDI filter does not derive from BMidiConsumer and BMidiProducer;
+instead, it contains BMidiConsumer and BMidiProducer objects for each of its
+distinct endpoints that connect to other MIDI objects. The Midi Kit does not
+allow the use of multiple virtual inheritance, so you can't create an object
+that's both a BMidiConsumer and a BMidiProducer.
+
+This also contrasts with the old Midi Kit's conception of a BMidi object, which
+stood for an object that both received and sent MIDI data. In the new Midi Kit,
+the endpoints of MIDI connections are all that matters. What lies between the
+endpoints, i.e., how a MIDI filter is actually structured, is entirely at your
+discretion.
+
+Also, rather than use token structs like media_node to make connections via the
+MediaRoster, the new kit makes the connections directly via the BMidiProducer
+object.
+
+\section midi2remotelocal Remote and local objects
+
+The Midi Kit makes a distinction between remote and local MIDI objects. You can
+only create local MIDI endpoints, which derive from either BMidiLocalConsumer
+or BMidiLocalProducer. Remote endpoints are endpoints that live in other
+applications, and you access them through BMidiRoster.
+
+BMidiRoster only gives you access to BMidiEndpoints, BMidiConsumers, and
+BMidiProducers. When you want to talk to remote MIDI objects, you do so through
+the proxy objects that BMidiRoster provides. Unlike BMidiLocalConsumer and
+BMidiLocalProducer, these classes do not provide a lot of functions. That is
+intentional. In order to hide the details of communication with MIDI endpoints
+in other applications, the Midi Kit must hide the details of how a particular
+endpoint is implemented.
+
+So, what can you do with remote objects? Only what BMidiConsumer,
+BMidiProducer, and BMidiEndpoint will let you do. You can connect objects, get
+the properties of these objects -- and that's about it.
+
+\section midi2lifespan Creating and destroying objects
+
+The constructors and destructors of most midi2 classes are private, which mean
+you cannot directly create them using the C++ new operator, on the
+stack, or as globals. Nor can you delete them. Instead, these
+objects are obtained through BMidiRoster. The only two exceptions to this rule
+are BMidiLocalConsumer and BMidiLocalProducer. These two objects may be
+directly created and subclassed by developers.
+
+\section midi2refcount Reference counting
+
+Each MIDI endpoint has a reference count associated with it, so that the Midi
+Roster can do proper bookkeeping. When you construct a BMidiLocalProducer or
+BMidiLocalConsumer endpoint, it starts with a reference count of 1. In
+addition, BMidiRoster increments the reference count of any object it hands to
+you as a result of \link BMidiRoster::NextEndpoint() NextEndpoint() \endlink or
+\link BMidiRoster::FindEndpoint() FindEndpoint() \endlink. Once the count hits
+0, the endpoint will be deleted.
+
+This means that, to delete an endpoint, you don't call the delete
+operator directly; instead, you call \link BMidiEndpoint::Release() Release()
+\endlink. To balance this call, there's also an \link BMidiEndpoint::Acquire()
+Acquire() \endlink, in case you have two disparate parts of your application
+working with the endpoint, and you don't want to have to keep track of who
+needs to Release() the endpoint.
+
+When you're done with any endpoint object, you must Release() it. This is true
+for both local and remote objects. Repeat after me: Release() when you're done.
+
+\section midi2events MIDI events
+
+To make some actual music, you need to \link BMidiProducer::Connect() Connect()
+\endlink your consumers to your producers. Then you tell the producer to
+"spray" MIDI events to all the connected consumers. The consumers are notified
+of these incoming events through a set of hook functions.
+
+The Midi Kit already provides a set of commonly used spray functions, such as
+\link BMidiLocalProducer::SprayNoteOn() SprayNoteOn() \endlink, \link
+BMidiLocalProducer::SprayControlChange() SprayControlChange() \endlink, and so
+on. These correspond one-to-one with the message types from the MIDI spec. You
+don't need to be a MIDI expert to use the kit, but of course some knowledge of
+the protocol helps. If you are really hardcore, you can also use the \link
+BMidiLocalProducer::SprayData() SprayData() \endlink to send raw MIDI events to
+the consumers.
+
+At the consumer side, a dedicated thread invokes a hook function for every
+incoming MIDI event. For every spray function, there is a corresponding hook
+function, e.g. \link BMidiLocalConsumer::NoteOn() NoteOn() \endlink and \link
+BMidiLocalConsumer::ControlChange() ControlChange() \endlink. The hardcore MIDI
+fanatics among you will be pleased to know that you can also tap into the \link
+BMidiLocalConsumer::Data() Data() \endlink hook and get your hands dirty with
+the raw MIDI data.
+
+\section midi2time Time
+
+The spray and hook functions accept a bigtime_t parameter named "time". This
+indicates when the MIDI event should be performed. The time is given in
+microseconds since the computer booted. To get the current tick measurement,
+you call the system_time() function from the Kernel Kit.
+
+If you override a hook function in one of your consumer objects, it should look
+at the time argument, wait until the designated time, and then perform its
+action. The preferred method is to use the Kernel Kit's
+snooze_until() function, which sends the consumer thread to sleep
+until the requested time has come. (Or, if the time has already passed, returns
+immediately.)
+
+Like this:
+
+\code
+void MyConsumer::NoteOn(
+ uchar channel, uchar note, uchar velocity, bigtime_t time)
+{
+ snooze_until(time, B_SYSTEM_TIMEBASE);
+ ...do your thing...
+}
+\endcode
+
+If you want your producers to run in real time, i.e. they produce MIDI data
+that needs to be performed immediately, you should pass time 0 to the spray
+functions (which also happens to be the default value). Since time 0 has
+already passed, snooze_until() returns immediately, and the
+consumer will process the events as soon as they are received.
+
+To schedule MIDI events for a performance time that lies somewhere in the
+future, the producer must take into account the consumer's latency. Producers
+should attempt to get notes to the consumer by or before
+(scheduled_performance_time - latency). The time argument is still the
+scheduled performance time, so if your consumer has latency, it should snooze
+like this before it starts to perform the events:
+
+\code
+snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
+\endcode
+
+Note that a typical producer sends out its events as soon as it can; unlike a
+consumer, it does not have to snooze.
+
+\section midi2ports Other timing issues
+
+Each consumer object uses a Kernel Kit port to receive MIDI events from
+connected producers. The queue for this port is only 1 message deep. This means
+that if the consumer thread is asleep in a snooze_until(), it will
+not read its port. Consequently, any producer that tries to write a new event
+to this port will block until the consumer thread is ready to receive a new
+message. This is intentional, because it prevents producers from generating and
+queueing up thousands of events.
+
+This mechanism, while simple, puts on the producer the responsibility for
+sorting the events in time. Suppose your producer sends three Note On events,
+the first on t + 0, the second on t + 4, and the third on t + 2. This last
+event won't be received until after t + 4, so it will be two ticks too late. If
+this sort of thing can happen with your producer, you should somehow sort the
+events before you spray them. Of course, if you have two or more producers
+connected to the same consumer, it is nearly impossible to sort this all out
+(pardon the pun). So it is not wise to send the same kinds of events from more
+than one producer to one consumer at the same time.
+
+The article Introduction to MIDI, Part 2 in OpenBeOS
+Newsletter 36 describes this problem in more detail, and provides a
+solution. Go read it now!
+
+\section midi2filters Writing a filter
+
+A typical filter contains a consumer and a producer endpoint. It receives
+events from the consumer, processes them, and sends them out again using the
+producer. The consumer endpoint is a subclass of BMidiLocalConsumer, whereas
+the producer is simply a BMidiLocalProducer, not a subclass. This is a common
+configuration, because consumers work by overriding the event hooks to do work
+when MIDI data arrives. Producers work by sending an event when you call their
+member functions. You should hardly ever need to derive from BMidiLocalProducer
+(unless you need to know when the producer gets connected or disconnected,
+perhaps), but you'll always have to override one or more of
+BMidiLocalConsumer's member functions to do something useful with incoming
+data.
+
+Filters should ignore the time argument from the spray and hook functions, and
+simply pass it on unchanged. Objects that only filter data should process the
+event as quickly as possible and be done with it. Do not
+snooze_until() in the consumer endpoint of a filter!
+
+\section midi2apidiffs API differences
+
+As far as the end user is concerned, the OpenBeOS Midi Kit is mostly the same
+as the BeOS R5 kits, although there are a few small differences in the API
+(mostly bug fixes):
+
+- BMidiEndpoint::IsPersistent() always returns false.
+- The B_MIDI_CHANGE_LATENCY notification is now properly sent. The Be kit
+ incorrectly set be:op to B_MIDI_CHANGED_NAME, even though the rest of the
+ message was properly structured.
+- If creating a local endpoint fails, you can still Release() the object
+ without crashing into the debugger.
+
+\section midi2seealso See also
+
+More about the Midi Kit:
+
+- \ref midi2defs
+- Be Newsletter Volume 3, Issue 47 - Motor Mix sample code
+- Be Newsletter Volume 4, Issue 3 - Overview of the new kit
+- OpenBeOS
+ Newsletter 33, Introduction to MIDI, Part 1
+- OpenBeOS
+ Newsletter 36, Introduction to MIDI, Part 2
+- Sample code and other goodies at the
+ OpenBeOS Midi Kit team page
+
+Information about MIDI in general:
+
+- MIDI Manufacturers Association
+- MIDI Tutorials
+- MIDI Specification
+- Standard MIDI File Format
+- Jim Menard's MIDI Reference
+
+*/
diff --git a/docs/user/midi2/midiconsumer.dox b/docs/user/midi2/midiconsumer.dox
new file mode 100644
index 0000000000..5083f5d64e
--- /dev/null
+++ b/docs/user/midi2/midiconsumer.dox
@@ -0,0 +1,54 @@
+/*!
+\class BMidiConsumer MidiConsumer.h
+\brief Receives MIDI events from a producer
+
+A consumer is an object that knows how to deal with incoming MIDI events. A
+consumer can be connected to multiple producers at the same time. There is no
+way to find out which producers are connected to this consumer just by looking
+at the BMidiConsumer object; you will have to consult BMidiRoster for that.
+
+A BMidiConsumer either represents a local consumer, i.e. a class extending from
+BMidiLocalConsumer, or is a proxy for a remote object published by another app.
+
+*/
+
+/*!
+\fn bigtime_t BMidiConsumer::Latency() const
+\brief Returns the latency of this consumer
+
+The latency is measured in microseconds. Producers should attempt to get MIDI
+events to this consumer by (when - latency). You do this by subtracting
+the latency from the performance time when you spray the events (provided that
+you spray these events ahead of time, of course).
+
+You cannot set the latency on a BMidiConsumer, only on a
+BMidiLocalConsumer.
+
+The latency issue gets slightly more complicated when multiple endpoints are
+chained together, as in the following picture:
+
+\verbatim
++-------+ +-------------+ +-------+
+| | | | | |
+| prodA |---->| consB prodB |---->| consC |
+| | | | | |
++-------+ +-------------+ +-------+
+ appA appB (filter) appC
+\endverbatim
+
+Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply
+reports 100ms, then prodA will schedule its events for (t - 100), which is
+really 200ms too late. (Of course, producers send out their events as soon as
+possible, so depending on the load of the system, everything may work out just
+fine.)
+
+ConsB should report the latency of the consumer that is hooked up to its
+output, consC, in addition to its own latency. In other words, the full
+downstream latency. So, the reported latency in this case would be 300ms. This
+also means that appB should change the latency of consB when prodB makes or
+breaks a connection, and when consC reports a latency change. (If multiple
+consumers are connected to prodB, you should take the slowest one.)
+Unfortunately, the Midi Kit provides no easy mechanism for doing any of this,
+so you are on your own here.
+
+*/
diff --git a/docs/user/midi2/mididefs.dox b/docs/user/midi2/mididefs.dox
new file mode 100644
index 0000000000..0374ee59c6
--- /dev/null
+++ b/docs/user/midi2/mididefs.dox
@@ -0,0 +1,89 @@
+/*!
+\page midi2defs Midi Kit definitions (Midi2Defs.h)
+
+\section channelmasks Channel message masks
+
+| B_NOTE_OFF | 0x80 |
| B_NOTE_ON | 0x90 |
| B_KEY_PRESSURE | 0xa0 |
| B_CONTROL_CHANGE | 0xb0 |
| B_PROGRAM_CHANGE | 0xc0 |
| B_CHANNEL_PRESSURE | 0xd0 |
| B_PITCH_BEND | 0xe0 |
| B_SYS_EX_START | 0xf0 |
| B_MIDI_TIME_CODE | 0xf1 |
| B_SONG_POSITION | 0xf2 |
| B_SONG_SELECT | 0xf3 |
| B_CABLE_MESSAGE | 0xf5 |
| B_TUNE_REQUEST | 0xf6 |
| B_SYS_EX_END | 0xf7 |
| B_TIMING_CLOCK | 0xf8 |
| B_START | 0xfa |
| B_CONTINUE | 0xfb |
| B_STOP | 0xfc |
| B_ACTIVE_SENSING | 0xfe |
| B_SYSTEM_RESET | 0xff |
| B_MODULATION | 0x01 |
| B_BREATH_CONTROLLER | 0x02 |
| B_FOOT_CONTROLLER | 0x04 |
| B_PORTAMENTO_TIME | 0x05 |
| B_DATA_ENTRY | 0x06 |
| B_MAIN_VOLUME | 0x07 |
| B_MIDI_BALANCE | 0x08 |
| B_PAN | 0x0a |
| B_EXPRESSION_CTRL | 0x0b |
| B_GENERAL_CTRL_1 | 0x10 |
| B_GENERAL_CTRL_2 | 0x11 |
| B_GENERAL_CTRL_3 | 0x12 |
| B_GENERAL_CTRL_4 | 0x13 |
| B_SUSTAIN_PEDAL | 0x40 |
| B_PORTAMENTO | 0x41 |
| B_SOSTENUTO | 0x42 |
| B_SOFT_PEDAL | 0x43 |
| B_HOLD_2 | 0x45 |
| B_GENERAL_CTRL_5 | 0x50 |
| B_GENERAL_CTRL_6 | 0x51 |
| B_TEMPO_CHANGE | 0x51 |
| B_GENERAL_CTRL_7 | 0x52 |
| B_GENERAL_CTRL_8 | 0x53 |
| B_EFFECTS_DEPTH | 0x5b |
| B_TREMOLO_DEPTH | 0x5c |
| B_CHORUS_DEPTH | 0x5d |
| B_CELESTE_DEPTH | 0x5e |
| B_PHASER_DEPTH | 0x5f |
| B_DATA_INCREMENT | 0x60 |
| B_DATA_DECREMENT | 0x61 |
| B_RESET_ALL_CONTROLLERS | 0x79 |
| B_LOCAL_CONTROL | 0x7a |
| B_ALL_NOTES_OFF | 0x7b |
| B_OMNI_MODE_OFF | 0x7c |
| B_OMNI_MODE_ON | 0x7d |
| B_MONO_MODE_ON | 0x7e |
| B_POLY_MODE_ON | 0x7f |
| B_MIDI_NO_OP |
| B_MIDI_REGISTERED |
| B_MIDI_UNREGISTERED |
| B_MIDI_CONNECTED |
| B_MIDI_DISCONNECTED |
| B_MIDI_CHANGED_NAME |
| B_MIDI_CHANGED_LATENCY |
| B_MIDI_CHANGED_PROPERTIES |
| property | Large (32x32) icon |
| field name | "be:large_icon" |
| field type | 'ICON' |
| property | Small (16x16) icon |
| field name | "be:mini_icon" |
| field type | 'MICN' |
| 0xF1 | B_MIDI_TIME_CODE | data1 only |
| 0xF2 | B_SONG_POSITION | data1 and data2 |
| 0xF3 | B_SONG_SELECT | data1 only |
| 0xF5 | B_CABLE_MESSAGE | data1 only |
| 0xF6 | B_TUNE_REQUEST | no data |
| 0xF7 | B_SYS_EX_END | no data |
| 0xF8 | B_TIMING_CLOCK |
| 0xFA | B_START |
| 0xFB | B_CONTINUE |
| 0xFC | B_STOP |
| 0xFE | B_ACTIVE_SENSING |
| 0xFF | B_SYSTEM_RESET |
| be:op | int32 | B_MIDI_REGISTERED |
| be:id | int32 | ID of the endpoint |
| be:type | string | "producer" or "consumer" |
| be:op | int32 | B_MIDI_UNREGISTERED |
| be:id | int32 | ID of the endpoint |
| be:type | string | "producer" or "consumer" |
| be:op | int32 | B_MIDI_CONNECTED |
| be:producer | int32 | ID of the connector |
| be:consumer | int32 | ID of the connectee |
| be:op | int32 | B_MIDI_DISCONNECTED |
| be:producer | int32 | ID of the connector |
| be:consumer | int32 | ID of the connectee |
| be:op | int32 | B_MIDI_CHANGED_NAME |
| be:id | int32 | ID of the endpoint |
| be:type | string | "producer" or "consumer" |
| be:name | string | the endpoint's new name |
| be:op | int32 | B_MIDI_CHANGED_LATENCY |
| be:id | int32 | ID of the endpoint |
| be:type | string | "producer" or "consumer" |
| be:latency | int64 | the new latency (microseconds) |
| be:op | int32 | B_MIDI_CHANGED_PROPERTIES |
| be:id | int32 | ID of the endpoint |
| be:type | string | "producer" or "consumer" |
| be:properties | BMessage | the new properties |