Live

cue:osc --- Discrete OSC Event Cue

osc(...) sends a single OSC message when triggered.

It is event-based, not continuous. It turns drawn objects into discrete control events, typically consumed by environments like SuperCollider, Pd, or Max.

BASIC FORM

osc(addr:, :, ...)

Required:

Key Meaning

addr OSC address name (without leading /)

Example:

osc(addr:voice, pitch:y, env:size)

EVENT BEHAVIOUR

osc() is a logical cue, not an animation cue.

VISUAL PARAMETER SOURCES (NORMALISED)

All visual sources are normalised to 0–1.

Source Meaning

x Object centre X position y Object centre Y position size Max(width, height) mapped to viewport scale Current visual scale value rotation 0--360 mapped to 0--1 opacity Computed opacity fill Numeric colour hash

Example:

osc(addr:voice, pitch:y, amp:size)

Here the Y-axis produces a continuous control pitch, interpreted downstream.

FIXED CONTROL PITCH — pitch:<number>

pitch:0.63 sends a fixed 0–1 value in the same form as pitch:y (pitchType 4), so a receiver built for pitch:y needs no change. Use it when an object's note should not depend on where it happens to be on screen — zoomed, panned or rotated:

osc(addr:star, pitch:0.63, env:size, trig:playhead)

SEMANTIC PITCH VALUES

Beyond visual values, osc() supports typed pitch declarations.

Hz (absolute)

osc(addr:voice, pitch:hz(440))

MIDI note number

osc(addr:voice, pitch:midi(60))

Scale degree + octave

osc(addr:voice, pitch:deg(5,3))

Represents:

The receiver chooses how to interpret the scale.

OPTIONAL ROOT OVERRIDE

You may specify a root in the cue:

osc(addr:voice, pitch:deg(2,4), root:48)

If omitted, the receiver uses its global default (~oscRoot in SC).

PITCH PRIORITY

When multiple forms are present, resolution is:

  1. deg(d,o) (scale-based symbolic pitch)
  2. hz() / midi() (absolute pitch)
  3. visual mapping (e.g., pitch:y)

Only one pitch representation is used per event.

NOTE EVENTS

dur: — timer-based

When dur: is supplied, a single element sends note-on at trigger time and note-off after dur beats via setTimeout. Useful for hand-authored cues where element geometry doesn't represent note duration.

osc(addr:voice, pitch:midi(60), dur:1.5, trig:playhead)

AMPLITUDE OVERRIDE (amp:)

amp: accepts a static 0–1 value that overrides the visual size field in the OSC payload. Useful when notes are generated from MIDI velocity rather than element geometry.

osc(addr:voice, pitch:midi(64), amp:0.75, dur:0.5, trig:playhead)

TRIGGERS

Key Meaning

trig:auto Send immediately

UID (OPTIONAL)

osc(addr:voice, pitch:y, uid:v1)

UID can be used downstream to associate events with voices/players/etc.

OSC OUTPUT FORMAT (AUTHORITATIVE)

Ready-made receivers for Pd, Max and SuperCollider, plus the address table for every other OSC-sending object, are on OSC Output.

osc() sends positional arguments, not keyed pairs — the layout below, unless args: gives the arguments itself.

YOUR OWN ARGUMENTS — args:[…]

osc(addr:parallaxis/p1/event, args:[5, 0.092], trig:ph1) osc(addr:hit, args:[2, y, size, rand(0,1), "low"])

The message is exactly that list, in that order: numbers as written, rand() drawn each time it fires, a visual source (x, y, size, scale, rotation, opacity, fill, width, height, area, aspect) sampled as it fires, and any other word as a string. gate:/dur: still append the gate, and pos:1 the frame position.

GENERAL PACKET FORMAT (without dur:)

/oscilla/ pitchType, pitchA, pitchB, size, env, density, [optional root]

PACKET FORMAT WITH dur: (note events)

/oscilla/ pitchType, pitchA, pitchB, size, env, density, [optional root], gate

Where gate is 1 for note-on and 0 for note-off. All other fields are identical between the two messages.

Where:

Field Meaning

pitchType 0=none, 1=deg/oct, 2=hz, 3=midi, 4=y-control pitchA meaning depends on pitchType pitchB octave (deg mode only) size 0--1 (overridden by amp: if supplied) env 0--1 density 0--1 (area-derived) root optional per-event root override gate 1=note-on, 0=note-off (present when gate: or dur: set)

SuperCollider decoding for piano-roll scores (pitchType 4 = y-control):

~pitchMin = 24; ~pitchMax = 108; midiNote = (~pitchMin + msg[1] * (~pitchMax - ~pitchMin)).round; gate = msg[msg.size - 1]; // 1 = on, 0 = off

Examples

Control pitch from Y

/oscilla/voice 1 5 3 0.41 0.41 0.12

Absolute pitch

/oscilla/voice 2 440 0 0.18 0.22 0.10

Degree + octave + root override

/oscilla/voice 1 5 3 0.33 0.20 0.15 48

Receivers are expected to decode according to this positional layout.

DESIGN NOTES

SUMMARY

osc() converts visual gestures into one-shot OSC control events, supporting symbolic, absolute, and control-driven pitch --- while leaving musical semantics to the instrument.

Tip: use ← → or ↑ ↓ to navigate the docs