% GrooveTransfer — User Manual
% XeniAudio
% v1.0.0

# GrooveTransfer

**Cross-track transient envelope transfer — no MIDI, no sidechain routing.**

GrooveTransfer extracts the rhythmic *groove* envelope of one track and
stamps it onto another. Put one instance on the track whose feel you want
to borrow (the **Sender**) and another on the track you want to move
(the **Receiver**); they pair by name through shared memory and the
receiver rides its own dynamics to the sender's groove.

Because the link is made through inter-instance shared memory — not audio
sidechain or MIDI — there is no routing to set up in your DAW, and it
works across tracks, busses and even between plugin formats.

---

## Installation

GrooveTransfer ships as **VST3**, **CLAP** and (on macOS) **Audio Unit**.

- **Windows** — run the installer, or copy `GrooveTransfer.vst3` to
  `C:\Program Files\Common Files\VST3` and the `.clap` to
  `C:\Program Files\Common Files\CLAP`.
- **macOS** — open the `.dmg` and run the installer package. Plugins are
  installed to `~/Library/Audio/Plug-Ins/` (VST3, CLAP, Components).
- **Linux** — run `install.sh`, or copy the `.vst3` / `.clap` to
  `~/.vst3` and `~/.clap`.

Restart your DAW and rescan plugins after installing.

---

## Quick start

1. Insert GrooveTransfer on the **source** track (the groove you want to
   copy) and set its **Role** to **Sender**.
2. Insert GrooveTransfer on the **target** track and set its **Role** to
   **Receiver**.
3. Give the Sender a recognisable name (double-click the title to rename),
   then click the Receiver's **Peer** selector until that name shows. The
   two are now paired.
4. Raise the Receiver's **Mix** until the target track breathes with the
   source's groove.

Use **Both** if a single instance should simultaneously broadcast its own
envelope and follow a peer.

---

## Controls

| Control | Range | Default | What it does |
|---|---|---|---|
| **Sensitivity** | 0.0 – 1.0 | 0.5 | How strongly the envelope follower reacts to transients. Higher values track finer detail; lower values smooth the groove out. |
| **Attack** | 0.1 – 100 ms | 5 ms | How quickly the follower rises on a transient. Short = snappy and percussive, long = softer onsets. |
| **Release** | 5 – 2000 ms | 80 ms | How quickly the follower falls after a transient. Short = tight and gated, long = sustained, flowing movement. |
| **Mix** | -24 – +24 dB | 0 dB | How much of the transferred groove is applied to the receiver. Negative values duck against the groove instead of riding with it. |
| **Role** | Sender / Receiver / Both | Both | Whether this instance publishes its envelope, follows a peer's, or does both. |

### The interface

- **Title** — double-click to rename the instance. This is the name other
  instances see in their Peer selector, and what pairing is saved under.
- **Peer selector** — click to cycle through every other GrooveTransfer in
  the session (one more click unbinds). If the selected peer is set to
  **Receiver**, the selector shows a red *receive-only* warning — a
  Receiver publishes no envelope, so there is nothing to follow until its
  role is changed.
- **Scope** — the last 1.5 s of envelope: what you broadcast (Sender/Both)
  or what you receive (Receiver).
- **Hints** — hover any control and a one-line description appears in the
  bottom-left corner.
- **Resize** — drag the bottom-right grip; the window keeps its aspect
  ratio and the size is saved with the project.

### Roles in detail

- **Sender** — analyses the incoming audio and publishes its groove
  envelope to shared memory. Audio passes through unchanged.
- **Receiver** — reads a peer's envelope and applies it to this track's
  dynamics, scaled by **Mix**.
- **Both** — does both at once: useful in a chain where every track should
  share a common groove.

---

## How pairing works

Each instance registers under its display name in a shared registry
(`xa_groove_registry`, up to 16 instances). Receivers pick a Sender by
name with the Peer selector, so the link survives project reloads as long
as the names match. Renaming a Sender breaks any Receiver still pointing
at the old name — just re-select it.

The envelope is detected with a fast/slow follower pair and broadcast at a
reduced control rate, so the inter-instance link is light on CPU even with
many pairs running.

---

## Tips

- **Kick → bass.** Sender on the kick, Receiver on the bass, short attack
  and a medium release — the bass pumps in time with the kick without a
  compressor sidechain.
- **Drums → pad/synth.** Longer release for a flowing, breathing pad that
  follows the drum groove.
- **Negative Mix** ducks the receiver against the groove (a classic
  "make room" effect) instead of reinforcing it.
- Pairing is **by name** — keep Sender names distinct and meaningful.

---

## Support

Visit <https://xeni-audio.com> or contact <support@xeni-audio.com>.

GrooveTransfer is free. If it earns a place in your sessions, the rest of
the XeniAudio range is one click away.
