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
deleted file mode 100644
index 2278a4d53b..0000000000
Binary files a/docs/user/midi2/midi2concepts.png and /dev/null differ
diff --git a/docs/user/midi2/midi2intro.dox b/docs/user/midi2/midi2intro.dox
deleted file mode 100644
index 5ba88c7654..0000000000
--- a/docs/user/midi2/midi2intro.dox
+++ /dev/null
@@ -1,303 +0,0 @@
-/*!
-\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
deleted file mode 100644
index 5083f5d64e..0000000000
--- a/docs/user/midi2/midiconsumer.dox
+++ /dev/null
@@ -1,54 +0,0 @@
-/*!
-\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
deleted file mode 100644
index 0374ee59c6..0000000000
--- a/docs/user/midi2/mididefs.dox
+++ /dev/null
@@ -1,89 +0,0 @@
-/*!
-\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 |