NAME
jack.clock - JACK Transport Publication Daemon
SYNOPSIS
jack.clock [options]
OPTIONS
-c Set the drift correction interval in periods (default=64).
-p Set the port number (default=57130).
DESCRIPTION
jack.clock publishes the transport state of the local JACK server as
OSC packets over a UDP connection. jack.clock 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.
Clients request to receive timing and change notification packets by
sending a "request notification" packet, /jck_rn, to the jack.clock
server. This packet has the form
/jck_rn category
where category is a bit mask that indicates what categories of
notification packets are requested. The bit locations are:
#define REQUEST_JCK_TK 0x00000001
#define REQUEST_JCK_PL 0x00000002
#define REQUEST_JCK_DC 0x00000004
#define REQUEST_JCK_MC 0x00000008
#define REQUEST_JCK_TC 0x00000010
#define REQUEST_JCK_RC 0x00000020
#define REQUEST_JCK_FC 0x00000040
#define REQUEST_JCK_ALL 0xFFFFFFFF
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, /jck_ra. This packet has the form
/jck_ra category port-number host-name
where category is as for /jck_rn and where port-number and host-name
give the address that notification should be sent to.
Once a client is registered subsequent /jck_rn and /jck_ra messages
edit the category value for that client. To delete the client from the
register send a request with a category value of negative one.
After requesting notification the client will receive all relevant
timing packets sent by the server. All jack.clock timing packets are
sent at the start of a JACK period as OSC message and have the same
shape:
tag ntp utc frm arg...
where tag is the command name, and ntp, utc and frm are time stamps
that indicate the same time point, the start of the JACK period when
the packet was sent. ntp is an unsigned 64bit integer NTP value. utc
is a double precision real valued representation of the UTC time. frm
is a signed 64bit integer frame counter the absolute value of which is
not defined but which increments synchronously with the ntp and utc
time stamps. arg... is the set of tag specific arguments.
The timing packets sent by jack.clock are:
/jck_pl ntp utc frm p-ntp p-utc p-frm pulse
Pulse Location. This packet indicates that the nearest frame to
the integer pulse pulse occurs at the time given by the time
stamps 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 /jck_tk
packet for the same period.
/jck_tk ntp utc frm frame pulse
Period Tick. This packet is sent once per JACK period. The
integer value frame is the transport location in frames, the
double precision real value 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.
/jck_dc 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 -t
option to the jack.clock server. The integer value ntp-dif is
the NTP form of the corrected drift value and utc-dif the UTC
form. Since JACK is a sample clock there is no frame drift
value.
/jck_rc ntp utc frm state
Roll-state Change. This packet is sent whenever the JACK
transport rolling state changes. The integer value state is
zero if the transport has stopped and one if it has started.
/jck_tc ntp utc frm ppm
Tempo Change. This packet is sent whenever the JACK transport
tempo changes. The double precision real value ppm is the new
tempo in pulses per minute.
/jck_mc ntp utc frm ppc pt
Measure Change. This packet is sent whenever the JACK transport
measure length or pulse type changes. The double precision real
value ppc is the new measure length in pulses per cycle, the
double precision real value pt is the pulse type.
/jck_fc ntp utc frm fps
Frame-rate Change. This packet is sent whenever the JACK sample
rate changes. The double precision real value fps is the new
sample rate in frames per second.
Clients can request a /jck_tk packet by sending a "request update"
packet, /jck_ru, which requires no argument. The tick packet is sent
only to the client that requested it, and is sent without consulting
any category flag for that client. The precise interpretation of tick
packets acquired in this manner is problematic.
Clients request a status packet by sending a "request status" packet,
/jck_rs, which requires no argument. The server replies immediately
with a status packet, /jck_st. The status packet is an OSC message and
is not timestamped. It has the shape:
/jck_st fps ppm ppc pt status
where fps is the sample rate in frames per second, ppm is the tempo in
pulses per minute, ppc is the measure length in pulses per cycle, pt is
the pulse type, and status is the transport status. It is intended
that a client will request a single status packet before requesting
notification for all subsequent state changes.
Clients initiate a change in transport roll state by sending a "request
transport operation" packet, /jck_rt, to the jack.clock server. It has
the shape:
/jck_rt status
where status is the requested transport roll status and has the same
meaning described earlier.
Clients initiate a change in transport location by sending a "request
locate operation" packet, /jck_rl, to the jack.clock server. It has
the shape:
/jck_rl location
where the single precision real value location is the requested
transport location in seconds.
jack.clock 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.
jack.clock drops all unrecognized incoming packets.
SEE ALSO
jackd(1), OSC(7) <http://cnmat.berkeley.edu/OSC/>
AUTHORS
Rohan Drape.