.TH JACK.OSC "1" 0.5 "November 2006"
.SH NAME
jack.osc \- JACK Transport Publication Daemon
.SH SYNOPSIS
.B jack.osc
.RI [ options ]
.SH OPTIONS
.TP
.B \-c
Set the drift correction interval in periods (default=64).
.TP
.B \-p
Set the port number (default=57130).
.SH DESCRIPTION
.B jack.osc
publishes the transport state of the local
.B JACK
server as
.B OSC
packets over a
.B UDP
connection. jack.osc allows any OSC enabled application to act as a
JACK transport client, receiving sample accurate pulse stream timing
data, and monitoring and initiating transport state change.
.PP
Clients request to receive timing and change notification packets by
sending a "request notification" packet,
.BR /receive ,
to the jack.osc server. This packet has the form
.TP
.BI /receive " category"
.PP
where
.I category
is a bit mask that indicates what categories of notification packets
are requested. The bit locations are:
.PP
.TS
;
l lb li .
#define REQUEST_TICK 0x0000001
#define REQUEST_PULSE 0x0000002
#define REQUEST_CORRECTION 0x0000004
#define REQUEST_TRANSPORT 0x0000008
#define REQUEST_ALL 0xFFFFFFF
.TE
.PP
Clients request notification messages to be sent to an address that is
not that of the packet that requests the notification by sending a
"request notification at" packet,
.BR /receive_at .
This packet has the form
.TP
.BI /receive_at " category port-number host-name"
.PP
where
.I category
is as for
.B /receive
and where
.IR port-number " and " host-name
give the address that notification should be sent to.
.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
timing packets sent by the server. All jack.osc timing packets are
sent at the start of a JACK period as OSC message and have the same
shape:
.TP
.BI tag " ntp utc frm arg..."
.PP
where
.B tag
is the command name, and
.IR ntp , " utc " and " frm"
are time stamps that indicate the same time point, the start of the
JACK period when the packet was sent.
.I ntp
is an unsigned 64bit integer NTP value.
.I utc
is a double precision real valued representation of the UTC time.
.I frm
is a signed 64bit integer frame counter the absolute value of which is
not defined but which increments synchronously with the
.I ntp
and
.I utc
time stamps.
.I arg...
is the set of
.I tag
specific arguments.
.PP
The timing packets sent by jack.osc are:
.TP
.BI /pulse " ntp utc frm p-ntp p-utc p-frm pulse"
Pulse Location. This packet indicates that the nearest frame to the
integer pulse
.I pulse
occurs at the time given by the time stamps
.IR "p-ntp", " p-utc " and " p-frm" .
The pulse number is one based. This packet is sent at the start of
the JACK period in which the integer pulse will occur. This packet is
not sent if the transport is stopped. This packet is sent before the
.B /tick
packet for the same period.
.TP
.BI /tick " ntp utc frm frame pulse"
Period Tick. This packet is sent once per JACK period. The integer
value
.I frame
is the transport location in frames, the double precision real value
.I pulse
is the transport location in pulses. The pulse value is read from an
accumulator and is approximate only, the accumulator is corrected at
each integer pulse location.
.TP
.BI /drift " ntp utc frm ntp-dif utc-dif"
Drift Correction. This packet is sent whenever the clock drift
correction is run. The frequency of this is set by the
.B \-t
option to the jack.osc server. The integer value
.I ntp-dif
is the NTP form of the corrected drift value and
.I utc-dif
the UTC form. Since JACK is a sample clock there is no frame drift
value.
.PP
The state change packets sent by jack.osc are:
.TP
.BI /transport " ntp utc frm fps ppm ppc pt state"
Transport state change. This packet is sent whenever the JACK
transport changes. The double precision real value
.I fps
is the sample rate in frames per second. The double precision real
value
.I ppm
is the tempo in pulses per minute. The double precision real value
.I ppc
is the measure length in pulses per cycle. The double precision real
value
.I pt
is the pulse type. The integer value
.I state
is zero if the transport has stopped and one if it has started. See also the
.B /status
message described below.
.PP
Clients can request the current frame and pulse values by sending a
.B /current
packet, which requires no argument. The replies with a
.B /current.reply
packet, which has the same form as a
.B /tick
packet. The precise interpretation of packets acquired in this manner
is problematic.
.PP
Clients request a status packet by sending a "request status" packet,
.BR /status ,
which requires no argument. The server replies immediately with a
status reply packet,
.BR /status.reply .
The status packet is an OSC message and is not timestamped. It has
the shape:
.TP
.BI /status.reply " fps ppm ppc pt state"
.PP
where the argument values are as described for the
.B /transport
message. It is intended that a client will request a single status
packet before requesting notification for all subsequent state
changes.
.PP
Clients initiate a change in transport roll state by sending a
"request transport operation" packet,
.BR /start " or " /stop
to the jack.osc server. Neither requires an argument.
.PP
Clients initiate a change in transport location by sending a "request
locate operation" packet,
.BR /locate ,
to the jack.osc server. It has the shape:
.TP
.BI /locate " location"
.PP
where the single precision real value
.I location
is the requested transport location in seconds.
.PP
Clients can connect and disconnect ports by sending
.BR /connect " and "
.B /disconnect
messages to the jack.osc server. Both have the shape:
.TP
.BI /[dis]connect " left right"
.PP
jack.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
jack.osc drops all unrecognized incoming packets.
.SH AUTHOR
Rohan Drape .
.SH SEE ALSO
.BR jackd "(1), " "OSC" "(7) "