JACK-OSC(1)

📦
this version · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 JACK-OSC 💖 (that's section 1 of the manual, bestie)

okay so. gather round. this is jack-osc — the JACK Transport Publication Daemon — and honestly? she's giving glow-up energy. ✨

🌸 NAME 🌸

jack-osc — JACK Transport Publication Daemon, aka the girl who tells everybody what the transport is doing. 👑

✨ SYNOPSIS ✨

jack-osc [options]

that's it. that's the whole vibe. options go in, magic comes out. 💅

🎀 OPTIONS 🎀

  • -c — sets the drift correction interval, measured in periods. default is 64. ngl she checks herself on the regular. 🪞
  • -p — sets the port number. default is 57130. that's her number, don't lose it. 📞

🦋 DESCRIPTION 🦋

okay so here's the tea, bestie. jack-osc publishes the transport state of the local JACK server as OSC packets over a UDP connection. and the way that works? any OSC-enabled application can act as a JACK transport client — receiving sample accurate pulse stream timing data, and monitoring and initiating transport state change. she really said "everybody eats." 🍽️

📨 how clients sign up (the request packets)

Clients request to receive timing and change notification packets by sending a "request notification" packet, /receive, to the jack-osc server. This packet has the form:

/receive category

where category is a bit mask that indicates what categories of notification packets are requested. The bit locations are:

  • REQUEST_TICK — mask 0x0000001 🎯
  • REQUEST_PULSE — mask 0x0000002 💓
  • REQUEST_CORRECTION — mask 0x0000004 🛠️
  • REQUEST_TRANSPORT — mask 0x0000008 🚂
  • REQUEST_ALL — mask 0xFFFFFFF 🌈 (the "give me literally everything" option, and honestly? respect.)

🏠 sending your mail somewhere else

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, /receive_at. This packet has the form:

/receive_at category port-number host-name

where category is as for /receive, and where port-number and host-name give the address that notification should be sent to. lowkey she'll deliver to your friend's house, no questions asked. 🫶

🗑️ the unsubscribe arc

Once a client is registered, subsequent /receive and /receive_at 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. it's giving "we're not friends anymore" but politely, in bitmask. 💀

⏱️ the timing packets (the main character era)

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 messages and have the same shape:

tag ntp utc frm arg...

where:

  • tag is the command name 🏷️
  • 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-osc are:

💓 /pulse

/pulse 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 /tick packet for the same period. ⏳

✅ /tick

/tick 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. she's doing her best, okay?? 😭

🌊 /drift

/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 -c option to the jack-osc 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. 🧚

🚂 the state change packets

/transport

/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 fps is the sample rate in frames per second. The double precision real value ppm is the tempo in pulses per minute. The double precision real value ppc is the measure length in pulses per cycle. The double precision real value pt is the pulse type. The integer value state is zero if the transport has stopped and one if it has started. See also the /status message described below. 👀

🔍 asking for the current thing

Clients can request the current frame and pulse values by sending a /current packet, which requires no argument. The server replies with a /current.reply packet, which has the same form as a /tick packet.

the precise interpretation of packets acquired in this manner is problematic. just so you know. 🙈

📋 status check

Clients request a status packet by sending a "request status" packet, /status, which requires no argument. The server replies immediately with a status reply packet, /status.reply. The status packet is an OSC message and is not timestamped. It has the shape:

/status.reply fps ppm ppc pt state

where the argument values are as described for the /transport message. It is intended that a client will request a single status packet before requesting notification for all subsequent state changes. like a little "hey what's the sitch" before you commit to the group chat. 💬

▶️⏹️ starting and stopping

Clients initiate a change in transport roll state by sending a "request transport operation" packet, /start or /stop, to the jack-osc server. Neither requires an argument. no notes, just vibes. ✨

📍 locating

Clients initiate a change in transport location by sending a "request locate operation" packet, /locate, to the jack-osc server. It has the shape:

/locate location

where the single precision real value location is the requested transport location in seconds. ⏲️

🔌 connecting and disconnecting

Clients can connect and disconnect ports by sending /connect and /disconnect messages to the jack-osc server. Both have the shape:

/[dis]connect left right

matching them up like a situationship. 🫂

⚠️ the fine print (read this part, bestie, fr fr)

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.

jack-osc drops all unrecognized incoming packets. into the void. gone. 🕳️💀

💜 AUTHOR 💜

Rohan Drape — http://rd.slavepianos.org/

🎀 SEE ALSO 🎀

👑 AUTHOR (yes, again, she said it twice and she's iconic for it) 👑

  • Rohan Drape <rd@slavepianos.org> — Author. 🫶

and that's the whole page, bestie. no cap. 💖

this little masterpiece is dated 10/04/2025, and it lives in section JACK-OSC(1) of your friendly neighbourhood manual. go forth and publish that transport state. slay. 💅✨🌈

📦 where this page comes from