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
Page 1
mdIntro(3dm)mdIntro(3dm)
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
Page 2
mdIntro(3dm)mdIntro(3dm)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
Page 3
mdIntro(3dm)mdIntro(3dm)SEE ALSO
MIDI 1.0 Detailed Specification
Standard MIDI File Specification 1.0
(both available from the MIDI manufacturer's association)
Page 4
