Automation Mapper

The Automation Mapper maps MIDI CC numbers to automation parameters. It works with both MIDI hardware controllers and OSC devices (like TouchOSC on an iPad).

Open it from Settings > Automation.

How It Works

Internally, all automation values are stored as normalized floats in the range -1.0 to +1.0. This keeps the engine fast and makes automation composable — LFOs, offsets, and shakes all operate in the same normalized space.

The mapper converts between normalized values and real-world units using a simple linear formula:

output = input * a + b

Where input is the normalized value (-1.0 to +1.0), and a (scale) and b (offset) define the real-world range.

Mapping Table

Each row in the mapper has:

Column	Description
CC	MIDI CC number (0-127). This is what your hardware sends.
Parameter	The automation parameter ID (e.g., scene3d.azimuth).
x a	Scale factor. Multiplied by the normalized input.
+ b	Offset. Added after scaling.
Range	Computed output range (read-only). Shows the resulting min..max.
Unit	Display unit for the UI (e.g., deg, %, px).
Label	Human-readable name shown in automation lanes.

Examples

Parameter	a	b	Range	Unit	Explanation
Azimuth	180	0	-180..180	deg	Full 360-degree orbit
Elevation	89	0	-89..89	deg	Nearly vertical tilt
Distance	9.95	10.05	0.1..20		Camera distance from target
Focal Length	89	90	1..179	deg	Lens field of view
Opacity	50	50	0..100	%	Fully transparent to fully opaque

Understanding a and b

Think of a as “how wide the range is” (half the total span) and b as “where the center is”:

• a = 180, b = 0 — centered at 0, spans -180 to +180
• a = 89, b = 90 — centered at 90, spans 1 to 179
• a = 50, b = 50 — centered at 50, spans 0 to 100

Signal Flow

Hardware fader (0-127)
  -> normalize to -1.0..+1.0
  -> store in automation lane (normalized)
  -> on playback: scale by a/b to real units
  -> apply to layer/parameter

The normalization and recording happen at CC input time. The scaling to real units happens at playback time, in the compositor render loop.

Adding a Mapping

1. Click + Add to create a new row
2. Set the CC number to match your hardware controller
3. Enter the Parameter ID (see parameter reference below)
4. Set a and b to define the output range
5. Optionally set Unit and Label for display

Removing a Mapping

Click the x button on the right side of any row to remove it.

Default Mappings

Plinken ships with default mappings for the 3D camera on CC 40-51:

CC	Parameter	Label
40	scene3d.orbit_target_x	Orbit Target X
41	scene3d.orbit_target_y	Orbit Target Y
42	scene3d.orbit_target_z	Orbit Target Z
43	scene3d.distance	Distance
44	scene3d.azimuth	Azimuth
45	scene3d.elevation	Elevation
46	scene3d.focal_length	Focal Length
47	scene3d.focus_distance	Focus Distance
48	scene3d.look_target_x	Look Target X
49	scene3d.look_target_y	Look Target Y
50	scene3d.look_target_z	Look Target Z
51	scene3d.follow_deadzone	Follow Deadzone

Parameter Reference

Transform (CC 0-9)

Parameter	Description
transform.x	Horizontal position
transform.y	Vertical position
transform.scale_x	Horizontal scale
transform.scale_y	Vertical scale
transform.rotation	Rotation angle
transform.anchor_x	Anchor point X
transform.anchor_y	Anchor point Y
transform.content_zoom	Content zoom level
transform.content_x	Content pan X
transform.content_y	Content pan Y

Layer

Parameter	Description
opacity	Layer opacity (0-1)

Mask (CC 20-27)

Parameter	Description
mask.x	Mask position X
mask.y	Mask position Y
mask.width	Mask width
mask.height	Mask height
mask.corner_radius	Rounded corner radius
mask.feather	Edge feather amount
mask.rx	Ellipse radius X
mask.ry	Ellipse radius Y

3D Camera (CC 40-51)

Parameter	Description
scene3d.orbit_target_x	Camera orbit center X
scene3d.orbit_target_y	Camera orbit center Y
scene3d.orbit_target_z	Camera orbit center Z
scene3d.distance	Distance from orbit target
scene3d.azimuth	Horizontal orbit angle (degrees)
scene3d.elevation	Vertical orbit angle (degrees)
scene3d.focal_length	Lens focal length / FOV (degrees)
scene3d.focus_distance	Depth of field focus distance
scene3d.look_target_x	Look-at target X
scene3d.look_target_y	Look-at target Y
scene3d.look_target_z	Look-at target Z
scene3d.follow_deadzone	Follow deadzone radius

OSC Integration

The Automation Mapper works seamlessly with OSC. OSC messages are converted to MIDI CC events before entering the mapper. Configure OSC address-to-CC mappings in Settings > OSC, then set up the parameter scaling here in the Automation Mapper.