mdIntro(3dm) mdIntro(3dm) NAME midi, mdIntro - Introduction to the Silicon Graphics MIDI Library (libmd) SYNOPSIS #include <dmedia/midi.h> -lmd DESCRIPTION The Silicon Graphics MIDI library (libmd) provides a programming interface for applications which wish to receive and transmit messages through MIDI interfaces. MIDI (an acronym for the Musical Instrument Digital Interface) is an industry-standard mechanism for connecting to and communicating with a variety of devices. Although it was originally designed primarily for use with electronic music instruments (such as synthesizers and drum machines), MIDI is now used in conjunction with a wide variety of devices, including audio tape decks, theatrical lighting systems, and input devices such as button and slider boxes. The MIDI library makes frequent references to MIDI interfaces. An interface provides a source and a destination for MIDI events. Interfaces are named with case-insensitive strings when they are created, and these names are used throughout the system whenever an interface needs to be referenced. A list of all configured interfaces can be obtained from the startmidi command or through the use of the mdGetName routines. Interfaces are divided into two classes: physical interfaces and internal interfaces. Physical interfaces are used for connections to the outside world and are associated with a physical device to which a physical MIDI interface box is connected. Internal interfaces are the conceptually similar to physical interfaces, but they are associated with software programs rather than physical devices. Internal interfaces provide a mechanism for "looping back" messages: any messages written to an internal interface can be read back from it. Internal interfaces are commonly used in situations where you wish to use MIDI as a form of inter-process communication. For example, the Software Synthesizer (see midisynth(1)) is able to emulate an external synthesizer by playing notes transmitted to it via the "Software Synth" internal interface. Applications don't need to differentiate between physical and internal interfaces; both behave the same way. If you wish to provide a service which receives input or supplies output via an interface in a manner similar to midisynth, you should create a new internal interface for your program (see the mdRegister(3dm) man page for more information). SGI's MIDI implementation allows multiple applications to read and write from an interface simultaneously. If multiple applications are receiving events from the same interface, each application will receive its own copy of any events which arrive on the interfacet. If multiple applications are sending events to the same interface simultaneously, the MIDI library will merge the event streams from the two applications into a single outgoing event stream. The precise order of the events in the merged stream is undefined, but the library guarantees that non-system exclusive data will be merged atomically, and that events from the same stream will not be reordered. Applications connect to interfaces through ports. Ports, which are represented by instances of the MDport data type, are an opaque structure containing information about the state of MIDI data and timing for a connection to a particular interface. Ports can be opened for either input from or output to an interface (via mdOpenInPort(3dm) and mdOpenOutPort(3dm). Once the application has opened a port for an interface, it can transmit or recieve MIDI events. The MDevent data structure is public and is defined as: typedef struct __mdevent { char msg[4]; /* channel message data */ char *sysexmsg; /* sysex message data */ unsigned long long stamp; /* time stamp in nanosecs */ int msglen; /* length of data, sysex only */ } MDevent; stamp is the timestamp of the event. After an application opens a port, it can select one of several stamping modes which control the precise format of the stamp (see mdSetStampMode). msg is an array of characters representing the data of a non-sysexclusive message. The first byte in the array, msg[0], contains the MIDI status byte (which in turn encodes the particular command type and, in many cases, the channel to which that command applies). msg[1] and msg[2] contain additional parameters which are specific to particular command types. For example, the NOTE ON event takes two additional bytes: the note number in msg[1] and the note velocity in msg[2]. The fourth byte in the msg array is unused. sysexmsg hold a pointer to the system exclusive data block when system exclusive data is received or transmitted. msglen contains a count of the number of bytes in the system exclusive block when sysex data is received or transmitted. The MIDI Library contains a number of functions: mdClosePort(3dm) - close down any port mdFree(3dm) - free storage for libmd mdGetDivision(3dm) - gets the divisions per beat or pulses per quarter note mdGetFd(3dm) - retrieve a file descriptor, for select(2) mdGetName(3dm) - get the name of a MIDI hardware or virtual device mdGetStampMode(3dm) - get time stamp mode for a port mdGetTempo(3dm) - get tempo, in microseconds per beat mdInit(3dm) - initialize MIDI library mdMalloc(3dm) - allocate storage for libmd mdOpenInPort(3dm) - open an input port mdOpenOutPort(3dm) - open an output port mdPause(3dm) - discard any events queued on a port and return UST or tick of last event mdPrintEvent(3dm) - format MIDI events for human readable printing mdRegister(3dm) - register an application with the MIDI system mdReceive(3dm) - receive MIDI events mdSend(3dm) - send MIDI events mdSetDivision(3dm) - gets the divisions per beat mdSetStampMode(3dm) - set time stamp mode for a port mdSetStartPoint(3dm) - establish a pairing between a UST and a stamp mdSetTempo(3dm) - set tempo, in microseconds per beat mdTell(3dm) - return UST or tick of last event sent out mdTellNow(3dm) - Return the stamp corresponding to the current time mdUnRegister(3dm) - remove an application from the MIDI system /usr/include/dmedia/midi.h - MIDI Library header file /usr/lib/libmd.so - MIDI library shared object /usr/share/src/dmedia/midi - MIDI example code /usr/share/src/dmedia/midi/* - MIDI Library code examples SEE ALSO MIDI 1.0 Detailed Specification Standard MIDI File Specification 1.0 (both available from the MIDI manufacturer's association) Page 4