.TH MIDI.OSC "1" 0.2 "November 2004"
.SH NAME
midi.osc \- MIDI Packet Publication Daemon
.SH SYNOPSIS
.B midi.osc
.RI [ options ]
.SH OPTIONS
.TP
.B \-p
Set the port number (default=57150).
.SH DESCRIPTION
.B midi.osc 
publishes MIDI packets on the local host
.B MIDI
system as
.B OSC 
packets over a 
.B UDP 
connection.  midi.osc allows any environment that supports OSC to act
as a MIDI client, sending and receiving MIDI data, and monitoring and
initiating changes to the host MIDI system.
.PP
There is support for ALSA Sequencer and CoreMidi hosts.
.PP
Clients register with the midi.osc server by sending a "request
notification" packet,
.BR /receive . 
This packet has the form
.RS
.sp
.B /receive
.I category
.sp
.RE
where 
.I category
is an <integer> bit-mask indicating the classes of packets to
receive. The bit locations are:
.IP
.TS
;
l lb li .
#define	RECEIVE_MIDI	0x00000001
#define	RECEIVE_META	0x00000002
#define	RECEIVE_ALL	0xFFFFFFFF
.TE
.PP
Clients can be registered at an address that is not that of the packet
that sends the request by sending a "request notification at" packet,
.BR /receive_at .
This packet has the form
.RS
.sp
.B /receive_at
.I category port-number host-name
.sp
.RE
where 
.I category 
is as for 
.B /receive
and where
.IR port-number " and " host-name
give the address of the client to be registered.
.PP
Once a client is registered subsequent 
.BR /receive " and " /receive_at
messages edit the category value for that client.  To delete the
client from the register send a request with a
.I category
value of negative one.
.PP
After requesting notification the client will receive all relevant
MIDI packets sent over the host MIDI system.
.PP
The MIDI packets sent by midi.osc are of the form
.RS
.sp
.B /midi 
.I source-identifier packet-data
.sp
.RE
where the source identifier is an <integer> and the packet data is an
OSC <blob>.
.PP
The change notification packets sent by midi.osc are of the form
.RS
.sp
.B /change 
.I message-identifier
.sp
.RE
where the message identifier is an <integer>.  
.PP
Clients can request a server reset by sending a message
.B /reset
message which requires no argument.  The requesting client receives a
.B /reset.reply
and all clients receive a 
.B /change
packet.
.PP
Clients request to receive a MIDI system status packet by sending a
"request status" message,
.BR /status ,
to the midi.osc server.  This message has no arguments.  The server
replies with a
.BI /status.reply " number-of-sources number-of-destinations"
message.
.PP
The MIDI ports at the host system are given and addressed as
enumerated sets of source and destination ports.  Source and
destination ports are each addressed using zero indexed <integer>
values.
.PP
Clients can query the name of a MIDI port by sending a "request name"
message,
.BR /name ,
to the midi.osc server.  This message has the form
.RS
.sp
.B /name
.I direction port-identifier
.sp
.RE
The <string> direction should be "source" or "destination".  The
server replies with a
.BI /name.reply " device-name port-name"
message.
.PP
midi.osc implements only a subset of the OSC protocol.  In particular
it does not implement the patten matching rules and does not implement
a scheduler for incoming messages.
.PP
midi.osc drops all unrecognized incoming packets.
.SH AUTHOR
Rohan Drape <http://www.slavepianos.org/rd/>.
.SH SEE ALSO
.BR "OSC" "(7) <http://cnmat.berkeley.edu/OSC/>"