ICST Ambisonics Plugins · Motion Map v2.4.5

Source Motion Mappingfor Spatial Composition in REAPER

Guide, setup, and creative techniques for positioning, animating, and automating up to 64 sound sources in three-dimensional space.

Beginner–Intermediate · Composer · Sound designer · Spatial-audio technician

Animated AmbiEncoder64 Motion Map interface with moving sources and trajectories in the preview
Animated preview (schematic) · 64 sources · 3D motion · REAPER automation · OSC

About Motion Mapping

The ICST motion mapping tools let you position, animate, and control multiple sound sources in 3D space. They support compositional workflows as well as live performance and integrate directly with REAPER automation and OSC.

Map & Animate

Position and move up to 64 sources with precise XYZ control.

Flexible Control

Combine REAPER automation, OSC preview, presets, and timing curves.

Creative Workflows

Move from fixed composition to algorithmic trajectories and live performance.

In This Section


1. Requirements

Before you start, make sure you have:

  • REAPER v6 or later
  • ICST AmbiEncoder_64 on the target track (see Installation)
  • Python 3 installed — required only for the live OSC preview feature
  • Both script files in the same folder: JS_AmbiEncoder64_Motion_Map_GUI.lua and JS_Write_AmbiEncoder64_Spat_Motion_Automation.lua

2. Installation

Video: installation and first launch of the Motion Map, step by step (about 80 seconds). The written steps follow below.

Step 1 — Download the bundle

Download the ICST Ambi Motion Map Bundle and unzip it. Keep both Lua files together in one folder (e.g. your REAPER Scripts directory).

Step 2 — Load the script into REAPER

In REAPER, open Actions → Load ReaScript… and select JS_AmbiEncoder64_Motion_Map_GUI.lua. You only need to load the GUI script — it finds the writer automatically.

Warning

The writer script JS_Write_AmbiEncoder64_Spat_Motion_Automation.lua must be in the same folder as the GUI script. Do not separate the two files.

Step 3 — Assign the action (optional)

In the Actions window, find JS_AmbiEncoder64_Motion_Map_GUI and assign a keyboard shortcut or toolbar button for quick access.

For a more detailed walkthrough including Python OSC setup for macOS and Windows, see the Motion Map Setup guide.


3. First Launch

  1. In REAPER, select exactly one track that contains the ICST AmbiEncoder_64 FX.
  2. Set a time selection (loop range) in the REAPER timeline — this defines where automation will be written.
  3. Run the GUI script from the Actions menu (or your shortcut). The Motion Map window opens.
Warning

If you see “Bitte genau einen Track mit ICST AmbiEncoder_64 selektieren” (message appears in German), no AmbiEncoder track is selected. Select the correct track, then reopen the GUI.

If you see “Bitte zuerst eine Loop/Time Selection setzen” (message appears in German), set a loop range in the timeline before clicking Write.


4. The Interface at a Glance

Motion Map v2.4.5 in REAPER (24 s): first the Figure Editor reshapes the Astroid of S2, then the live OSC preview runs with Sync: the preview plays and stops with the REAPER transport, and the sources move in the encoder radar.

New in the recording (details in the sections named):

  • Figure Editor (v2.3): reshape a figure per source or for all sources that use it (§6).
  • Tempo sync (v2.4): the cycle is set in beats (Zyklus (Beats)), with Taktstart locking the phase to the bar lines (§10).
  • Quantize (v2.4.3): Quant T, Q X/Y/Z turn any figure into stepped motion (§7).
  • Preview transport with Sync (v2.4.4/v2.4.5): Sync ties the preview to REAPER. It runs while REAPER plays, stands still when REAPER stops, and Play / Stop in the GUI start and stop the REAPER transport (§12).
  • Latch (v2.4.5): written tracks are always set to Latch automation (§13).

The window is divided into three areas:

Left — Source Grid: Rows for sources S0–S63. Each row has an enable toggle, a source label, and 16 motion-shape cells (Line through Lis, including Lat).

Right top — Trajectory Preview: Animated canvas showing the path each active source will travel. Axes are labelled X (left–right) and Y (up–down). The selected source shows a coordinate readout in the current scale unit (e.g. S0 X:-0.16 Y:-0.04).

Right bottom — Settings: Controls for scale, spatial parameters, timing, presets, and output options.


5. Enabling Sources

On first launch, all 64 sources are enabled and have shapes automatically assigned (Auto round-robin). There are three ways to toggle a source on or off:

  • Click the ✓ checkbox in the “On” column — toggles that source on or off.
  • Click the source label (e.g. S0, S1) — also toggles enable/disable with a larger click area.
  • Shift+click a source label — enables all sources from the currently selected source down to the one you clicked (range enable).

The bottom bar shows Quick Selectors: All Src, None Src, S0-7, S8-15 for instant multi-source selection.

The counter in the top-right of the settings panel shows how many sources are currently active (e.g. 3 / 64 active).


6. Assigning Motion Shapes

Each row has 16 shape buttons. Click one to assign that movement pattern to a source. Assigning a shape also enables the source automatically.

Overview of all 16 motion shapes and their trajectories

LabelShapeMovement Character
LinelineLinear sweep across the field
Arc+arc_upArc curving upward with smooth easing
Arc−arc_downArc curving downward
Ss_curveS-shaped sweep — sinusoidal Y motion
StepstepFour discrete position steps
ZigzigzagFast X/Y zigzag
CirccircleFull circle in the XY plane
SpirspiralExpanding spiral from center outward
Fourfourier_xyzComplex 3-D path from summed harmonics
Hrtheart_curveHeart-shaped parametric curve
CardcardioidCardioid — single-lobed teardrop curve
R8rose8Rose curve with 8 petals
BernbernoulliLemniscate of Bernoulli — figure-eight variant
AstastroidAstroid — 4-cusped star curve
EpiepicycloidEpicycloid — complex looping orbit
LislissajousLissajous figure — X and Y at different frequencies

When multiple sources share the same shape, use the Src offset slider (see §7) to spread them across the trajectory — otherwise they all move together at the same position.

Figure Editor

Info

The Figure Editor is available from Motion Map v2.3 (current version: v2.4.5). The interface labels inside the window are currently in German; the English equivalents are given in brackets.

Each motion shape has a figure editor: a second tab below the trajectory preview that lets you reshape a figure instead of only choosing it. Open it with the FIGURE EDITOR · S0 tab (the label shows the selected source) or with the Figur bearbeiten ▸ button in the settings. ◂ Settings returns to the normal controls. The preview updates while you drag the sliders.

The header line shows the selected source and its shape, for example S6 · Circ. Two buttons decide what an edit affects:

  • Figur: alle Quellen (figure: all sources) — the edit applies to every source that uses this shape.
  • Nur S6 (only S6) — the edit applies to the selected source alone.

To edit another shape, click its column or click the shape icon of the source again.

Figure parameters (FIGUR) depend on the shape. Shapes without their own parameters, such as Line, show only the transformation.

ShapeParameters
CircUmläufe (revolutions), Startwinkel (start angle), Ellipse Y
Lisfrequency ratios of X and Y (not checked in detail)
SpirUmläufe, Radius innen (inner radius), Radius aussen (outer radius), Easing, Startwinkel
FourTeiltöne (partials), Obertöne (overtones)
StepStufen (steps), Höhe (height)

Transformation (TRANSFORMATION) is the same for every shape:

ControlEffect
Drehung °Rotates the figure
Skalierung X / YStretches or compresses the figure along each axis
Versatz X / YShifts the figure
ZeitversatzDelays the start of the movement in time
Rückwärts0 plays forward, 1 plays the figure backwards

Figur zurücksetzen resets the current figure, Alle Figuren zurücksetzen resets all figures.

Above the editor, the preview can be switched between XY and Time view. ↓ Score → Region renders the preview (XY, or X/Y/Z over time) as a PNG and inserts it as a video item on a Motion Score track, stretched over the target region (time selection, otherwise a region at the edit cursor, otherwise the named region). In tempo-sync mode the Time view shows bar lines.

Quick-assign buttons (PRESETS bar below the grid)

ButtonEffect
AutoAssigns all 16 shapes in round-robin order across all 64 sources
RandomAssigns a random shape to every source
All LineSets all active sources to Line
All CircleSets all active sources to Circle
All StepSets all active sources to Step
S0-7 ArcAssigns Arc+ to sources 0–7
S8-15 CircAssigns Circle to sources 8–15
Clear AllRemoves all shape assignments and disables all sources

7. Spatial Parameters

Coordinate system

The GUI works in Cartesian XYZ space (unit sphere −1..+1). The Scale value sets a display multiplier so you can think in metres instead of normalised units. REAPER automation is always written in the native unit sphere — Scale never changes what is recorded, only how values are displayed and how OSC distance is sent.

  • X = left–right (−1 = left, 0 = center, +1 = right)
  • Y = up–down (−1 = below, 0 = horizon, +1 = above)
  • Z = distance (0 = near, 1 = far)

Controls

All sliders are draggable. Hold Shift while dragging for fine control. Click the value field on the right side of a slider to type an exact value.

ParameterDefaultDescription
Scale (m)1Room size in metres. Displayed coordinates are in Scale units (e.g. Scale 10 → range −10..+10 m). REAPER automation and OSC use values scaled back to the unit sphere. Type any value 1–1000.
Steps/sec12Automation point density per second. Higher = smoother but more envelope data.
Motion amount1.00Overall amplitude multiplier. 1.0 = full range; 0.5 = half; values above 1.0 extend beyond the defined spread and are clamped at the unit boundary.
X center0.00Left–right center of the movement field (−Scale..+Scale).
X spread2.00Total left–right range (0..2×Scale). 2.0 at Scale 1 = full −1..+1 sweep — the maximum range that can be written to REAPER.
Src offset0.00Temporal offset between sources along the trajectory. 0 = all sources at the same position; 1 = sources evenly distributed across the full path. Use this to separate sources that share the same motion shape.
Y center0.00Up–down center (−Scale = below, 0 = horizon, +Scale = above).
Y spread0.56Total vertical range.
Z center0.75Distance center (0 = near, Scale = far).
Z spread0.35Distance variation range.

Quantize controls

Quantization can be applied to any motion shape. It turns continuous motion into stepped motion in time, space, or both. The four fields Quant T, Q X, Q Y, Q Z sit in the Settings tab to the right of the Clear existing toggle (available from v2.4.3).

ParameterDefaultDescription
Quant T (Time / T)0Number of time slices per figure cycle. 0 disables time quantization. Example: 16 updates the curve at 16 evenly spaced moments.
Q X / Q Y / Q Z0.00Spatial rounding step per axis in scale units (like X/Y/Z center). 0 disables rounding; 0.1 rounds that axis to the nearest 0.1.

Use this when you want any shape to behave like a sequenced spatial grid: the trajectory is sampled in discrete time and/or rounded to discrete positions.

Reset button

Click ⟲ Reset (next to Write) to restore all spatial and timing parameters to their defaults while keeping shape assignments and presets unchanged.

Scale and OSC distance

When OSC Preview is active, the sent distance value equals the unit-sphere radius multiplied by Scale. At Scale 10, a source at the edge of the sphere sends a distance of ~10 m to the AmbiEncoder.


8. Time Curve — Shaping the Movement Rhythm

The Time Curve section controls how the animation progresses through time. Three modes:

Time Curve comparison — Linear, Exp, Log

ModeBehavior
LinearConstant speed — the shape unfolds at even pace (default).
ExpSlow start, fast finish — motion accelerates toward the end.
LogFast start, slow finish — motion decelerates toward the end.

The n slider (exponent) sets how strong the curve is. At n = 1 all three modes produce identical results. A typical value is 2.0–3.0.

When to use it: Exp is useful for sources that should “arrive” abruptly; Log gives a sweeping entry that settles. Combine with Palindrome for symmetric acceleration.


9. Palindrome Mode

When Palindrome is enabled, the motion plays forward and then backward within the same time selection: the shape travels 0 → 1 → 0 instead of 0 → 1.

This means:

  • The source returns to its start position at the end.
  • Useful for oscillating movements without a hard jump cut.
  • Works with all motion shapes.
  • Combine with Exp or Log time curve for asymmetric forward/backward speeds.

10. Output Options

OptionDescription
Clear existingDeletes existing envelope points in the time selection before writing. Turn off to layer movement on top of existing automation.
Automation: LatchNot an option: the track is always set to Latch automation mode after writing (from v2.4.5), so live parameter movements record on the next playback pass.
Overwrite regionIf a region with the same name already exists, it is repositioned to match the current time selection instead of creating a duplicate.
Use Z motionIncludes distance (Z) variation. Disable to keep sources at a fixed distance while X and Y still move.

Tempo sync (BPM)

From v2.4 the time base can follow the project tempo. The BPM button switches from seconds to beats:

  • The figure cycle is given in beats (Zyklus (Beats), default 16 = 4 bars) and repeats over the whole time selection.
  • Steps are then counted per beat.
  • Taktstart locks the phase of the cycle to the bar lines.
  • The preview and the OSC animation follow the project tempo and the DAW transport.

Region name

Sets the name of the REAPER render region created at the time selection. Default: BFormat_TS. Name regions to match your scene structure — they appear in the REAPER project and in render exports.


11. Preset System

The Preset bar at the top of the Settings panel lets you save, load, and delete complete parameter snapshots.

A preset stores: all motion shape assignments, which sources are enabled, Scale, all XYZ spatial parameters (center and spread for X, Y, Z), Src offset, Steps/sec, Motion amount, all Quantize settings, Time Curve mode and exponent, Palindrome, Use Z motion, and all output options.

Saving a preset

  1. Type a name in the Preset text field (e.g. Circle_Wide).
  2. Click Save.

Loading a preset

  • Click a preset chip (the buttons below the text field) to load it instantly.
  • Or type the name and click Load.

Deleting a preset

Type the name (or click the chip to fill it in) and click Delete.

Use the ◄ ► arrows to scroll through more than 6 saved presets. Presets persist across REAPER sessions (stored via REAPER ExtState).


12. Live OSC Preview

The OSC Preview section sends live position data to the AmbiEncoder while the animation plays in the GUI — so you can hear the movement before committing it to automation.

Recording: the Motion Map (v2.4) driving the AmbiEncoder live via OSC; the sources move in the encoder radar.

Step-by-step setup

  1. In REAPER Preferences → Control/OSC/web, enable “Allow binding of REAPER action and FX parameters to OSC” and note or set the port (default 9001).
  2. In the GUI, set Host to 127.0.0.1 (or the IP of your REAPER machine) and Port to match.
  3. Click Connect. The status dot turns green when the Python helper is running.
  4. Enable Live Preview (sends AED to AmbiEncoder).

The GUI now sends converted OSC position messages at ~30 Hz for every enabled source using the address:

/icst/ambi/sourceindex/aed <int index> <float azimuth> <float elevation> <float distance>

Example — source 3 at 45° azimuth, −15° elevation, 2.5 m distance:

/icst/ambi/sourceindex/aed 3 45.0 -15.0 2.5

OSC distance is sent in physical metres (unit radius × Scale).

Click Disconnect to stop sending OSC.

Preview transport (from v2.4.4, Sync from v2.4.5)

Below the OSC panel (bottom left) a small transport controls the animation in the trajectory preview and in the live OSC preview. It does not change what is written as automation.

ControlFunction
Speed ×Speed factor for the preview (0 to 16). Without tempo sync the preview runs at 0.28 cycles per second; with BPM on, one cycle takes the set number of beats at the project tempo.
> Fwd / < RevPlays the preview forwards or backwards.
▶ PlayStarts the preview animation.
■ StopFreezes the animation, so you can listen to one position.
SyncThe preview follows the REAPER transport: it runs while REAPER plays and stands still when REAPER stops. ▶ Play and ■ Stop then start and stop the REAPER transport.

With BPM on and the REAPER transport playing, the preview follows the project position (tempo sync). With Sync on, the preview runs only while REAPER plays; with BPM on it follows the project position, otherwise it runs at the set Speed and direction.

Warning

Live Preview requires Python 3 to be installed and accessible as python3 in your system PATH. If the status dot stays red, open a terminal and run python3 --version to verify.


13. Writing Automation

Once sources are set up and parameters look right in the preview:

  1. Make sure the correct REAPER track is selected.
  2. Confirm the time selection covers the region you want to fill.
  3. Click ▶ Write Automation + Region.

The script will:

  • Delete existing envelope points in the time selection (if Clear existing is on).
  • Write XYZ automation for every enabled source directly in the unit sphere (−1..+1), independent of the Scale display setting.
  • Set the track to Latch mode (always, from v2.4.5).
  • Create or update a named render region.

A status message at the bottom of the GUI confirms completion.


14. Trajectory Preview

The preview canvas shows all active sources simultaneously. The horizontal axis is X (left–right) and the vertical axis is Y (up–down), both labelled in the current Scale unit.

  • Each source gets its own color. The selected source has a pulsing halo and a coordinate readout (e.g. S0 X:-0.16 Y:-0.04 at Scale 1, or S0 X:-1.6 Y:-0.4 at Scale 10).
  • Non-selected sources show smaller dots at 80% opacity.
  • All dots animate at the same speed — you see the full spatial scene in real time.
  • Trails show the full path each source will travel.

Click a source label in the grid to select it and see its coordinates in the preview.


15. Good Practices

  • Full left–right sweep: set X center = 0, X spread = 2×Scale (e.g. 2.00 at Scale 1, 20.00 at Scale 10). This writes the full −1..+1 range to REAPER automation.
  • Separate overlapping sources: if two sources have the same shape and their trails overlap, increase Src offset to 0.3–0.5 to spread them along the trajectory.
  • Scale as room size: set Scale to your actual room radius (e.g. 8 for an 8 m radius space). The OSC preview then sends distances in metres. REAPER automation is unaffected.
  • Start with Auto + 3–4 sources enabled to explore the default shape spread.
  • Use Steps/sec 6–8 for broad, slow sweeps; 20–30 for detailed, dense movement.
  • Keep Motion amount at 1.0 initially — values above 1.0 can clip at the unit sphere boundary.
  • Use Clear existing off to layer a Circle on top of an existing Line automation.
  • Palindrome + Log creates a movement that sweeps quickly outward and gently returns — good for reverb-like spatial tails.
  • Save a preset before experimenting so you can always return to a known state.
  • Name render regions to match scenes: Intro_BFormat, Verse_BFormat, Outro_BFormat.
  • Quantize for rhythmic motion: set Quant T = 16 on a Circle shape to turn a smooth orbit into 16 discrete positions — snaps to the beat if Steps/sec matches your tempo.

16. Troubleshooting

No sources move after writing

Check that at least one source has a ✓ in the “On” column and an assigned shape (highlighted cell). The status bar at the bottom reports what was written.

Sources all move to the same position

Increase Src offset above 0 so that sources with the same shape are temporally distributed along the path.

The automation doesn’t match the preview

Make sure Motion amount, X/Y/Z spread, and Time Curve settings are the same as when you previewed. If you changed parameters after previewing but before writing, the written automation reflects the state at write time.

OSC Preview — dot stays red

  • Verify Python 3 is installed: open a terminal and run python3 --version.
  • Check that the Port matches your REAPER OSC settings.
  • Click Disconnect, then Connect again to restart the helper.

Writer script not found

Both Lua files must be in the same directory. If you moved the GUI script after loading it into REAPER, reload it from the new location via Actions → Load ReaScript.

Steps/sec too low for short regions

A 0.1-second time selection at 12 Steps/sec produces only 1 automation point. Increase Steps/sec or lengthen the time selection.

Quantize has no visible effect

Quant T must be greater than 0 to activate time quantization. A value of 0 (the default) disables it. Set Quant T to the number of steps you want (e.g. 16) and make sure Steps/sec is high enough that each time slice contains at least one automation point.


See also