TugPhonon — User Manual
A digital recreation of the Poulin/Schaeffer rotating tape head machine (1951)
================================================================================


WHAT IS TUGPHONON?
------------------
TugPhonon simulates a rotating magnetic disk with 8 playback heads — a concept
pioneered by Pierre Schaeffer and Jacques Poullin in the early 1950s. Audio is
continuously written onto a virtual tape loop. The 8 heads read back from
different positions on that loop simultaneously, each with its own filter,
effects chain, and spatial placement. The result is somewhere between a tape
delay, a granular texture machine, and a spectral decomposition tool.


INTERFACE OVERVIEW
------------------
The plugin is divided into four main areas:

  [ Preset Bar                                    ]
  [ Left Column ] [ Disk Visualizer ] [ Right Column ]
  [           Head Strip (8 heads)                ]


PRESET BAR
----------
At the top of the plugin, left to right:

  OPEN FOLDER  — Opens a folder browser to choose where presets are stored.
                 Your choice is remembered between sessions.

  SAVE         — Saves the current state as a new preset (you will be prompted
                 for a name).

  Preset dropdown — Select a saved preset. The list reflects the contents of
                    the chosen folder.

  DEL          — Deletes the currently selected preset from disk.


DISK VISUALIZER
---------------
The circular display in the center shows the virtual tape disk rotating in
real time.

  - The outer ring is the disk housing.
  - The 8 playback heads are shown as markers on the disk edge. Their spacing
    depends on the Spread knob.
  - The inner band shows the rotating tape surface with timing marks.
  - At the 12 o'clock position, two orange triangles indicate input signal
    level — they glow brighter as the signal gets louder.
  - The amber dot outside the ring shows which head is currently selected in
    the head strip below.

VU / WAVE toggle (bottom of left column): Switches the disk display between
per-head level meters (VU) and a circular waveform view of the recorded
loop (WAVE).


LEFT COLUMN — LOOP & OUTPUT CONTROLS
-------------------------------------

Loop

  Loop knob / Rate dropdown — Sets the length of the tape loop.

    SYNC on:  Loop length locks to DAW tempo. Choose a note value from the
              dropdown (1nd through 128nt — 24 options).

    SYNC off: Loop length is set in seconds (0.05s to 4.0s). The knob has a
              non-linear curve — the most useful range is in the lower half.

  SYNC button — Toggles between tempo-synced and free-running loop.

Spread

  Spread — Controls how far apart the 8 heads are positioned on the disk.

    At 0:   All heads read the same position (unison/phase effect).
    At 1:   Heads span the full loop length, evenly distributed.
    Between: Various comb-filtering and echo textures.

Output

  Feedback (0.0 – 0.95) — How much of the output is fed back into the loop.
    The feedback path runs through soft saturation, so it will not
    self-oscillate uncontrollably even at high values, but it will build up
    density over time.

  Mix (0.0 – 1.0) — Dry/wet blend. 0 = input only, 1 = processed signal only.

  Wet Gain (0.0 – 4.0) — Extra level boost on the wet signal, up to +12 dB.
    Useful when the effect is subtle and needs to sit louder in the mix.

Utility Buttons

  RESET — Returns all parameters to factory defaults.

  RND   — Randomizes spread, feedback, mix, modulation parameters, and all
          per-head settings. Good for discovering unexpected textures.

  VU / WAVE — Toggles disk display mode (see Disk Visualizer above).


RIGHT COLUMN — MODULATION
--------------------------
TugPhonon has two modulation modes, switched by the button at the top of
this column.

Global Modulation (default)

  A single LFO modulates the position of all 8 heads together. The heads move
  in a ripple — like a wave passing across them — rather than all moving
  identically.

  Wave     — LFO shape: Sine, Sawtooth, Triangle, Square, Reverse Saw,
             or Sample & Hold.

  Mod Rate / SYNC — Rate of the LFO. Same sync/free logic as the loop:
             SYNC on locks to DAW tempo with a note value dropdown;
             SYNC off sets frequency directly (0.05 – 20 Hz).

  Depth    — How much the heads move. At 0 there is no modulation. At 1 the
             swing is ±12% of the full loop length.

  Duration — Gate duty cycle. At 1.0 the modulation runs continuously.
             Lower values create a gate effect — the modulation is active for
             only a portion of each LFO cycle, then cuts off. At 0.5 the
             effect pulses on and off in equal time.

Individual Modulation

  When switched to Individual Modulation, each head has its own independent
  LFO. The global controls become inactive. Settings are found in each head's
  MOD tab (see Head Strip below).


HEAD STRIP
----------
The bottom section shows 8 head channels, scrollable horizontally.
Each head has:

  Number label (1–8) and an enable toggle — disable a head to remove it from
  the mix entirely without losing its settings.

  Pan knob    — Stereo placement, left to right. Uses equal-power panning.

  Offset knob — Fine-tunes this head's tap position relative to its default
                evenly-spaced slot. Useful for rhythmic displacement.

  Gain knob   — Output level for this head.

Each head has four tabs:


FILTER Tab
----------
  Freq  (20 Hz – 18 kHz)
    Center frequency of the band-pass filter for this head. Default values
    follow a V-curve across the 8 heads (heads 1 and 8 are bright, heads 4
    and 5 are dark), giving spectral spread out of the box.

  Q  (0.5 – 12)
    Resonance of the band-pass filter. Higher Q = narrower, more resonant band.

  Drive  (0.0 – 1.0)
    Tape saturation. Applies soft-clipping after the filter. At low values it
    adds subtle warmth; at high values it becomes obviously distorted.

  LFO Depth
    Amount of random pitch/frequency scatter applied to this head. At full
    depth the frequency swings up to ±3 octaves.

  LFO Rate
    How fast the scatter changes. Uses a sample-and-hold mechanism — the
    frequency jumps to a new random value at each LFO period. Selects from
    the same 24 note values as the loop rate.


MOD Tab  (visible in Individual Modulation mode)
------------------------------------------------
  Same parameters as Global Modulation, but specific to this head:
  Wave shape, Rate (sync or free), Depth, Duration.


FX Tab
------
  Tremolo Rate  (0.1 – 20 Hz)
    Speed of amplitude modulation. A sine LFO scales this head's output level.

  Tremolo Depth  (0.0 – 1.0)
    Amount of amplitude swing. At 1.0 the signal swings between full and
    approximately 50% level.

  Ring Freq  (10 – 5000 Hz)
    Carrier frequency for the ring modulator. Ring modulation multiplies the
    head signal by a sine wave, producing sum and difference sidebands.

  Ring Mix  (0.0 – 1.0)
    Blend between the dry filtered signal and the ring-modulated signal.


RES Tab
-------
  Physical modeling resonators that respond to the head's audio and re-emit it
  at a specific pitch and decay time.

  Mode — Resonator type:

    Off       — Bypass, no resonator.

    K-S       — Karplus-Strong string model. Bright attack, pitch-shifted decay.

    Comb      — Simple delay feedback without frequency shaping. Bright, metallic.

    Bell      — Partial ratios based on measured church bell acoustics.
                Slightly inharmonic, rich overtones.

    Pipe      — Closed-open cylindrical pipe. Only odd harmonics, hollow character.

    Marimba   — Undercut wooden bar tuning. The second mode is pulled sharp,
                which is characteristic of real marimba bars.

    Beam      — Free-free Euler-Bernoulli bar. Very high inharmonicity —
                metallic and unpitched-sounding even at a defined fundamental.

    Membrane  — Circular drum modes using Bessel function zero ratios.
                Dense upper partials.

  Pitch  (20 – 4000 Hz)
    Fundamental frequency of the resonator.

  Decay  (0.01 – 8 sec)
    T60 decay time. Higher modes always decay faster than the fundamental
    regardless of this setting.

  Mix  (0.0 – 1.0)
    Blend between the head's filtered/FX signal and the resonator output.


AUTOMATION
----------
All 169 parameters are automatable. Per-head parameters follow the naming
convention paramName_0 through paramName_7 (zero-indexed). For example, the
BPF frequency of head 3 is bpfFreq_2.


SIGNAL FLOW
-----------

  Input
    |
    +---> Delay line (write head)
              |
              +---> 8 parallel tap reads  (position = spread + modulation + offset)
                        |
                        each tap:
                          band-pass filter
                            drive (saturation)
                              tremolo
                                ring modulator
                                  resonator
                                    pan & gain
                                      |
                                      +---> L/R sum bus
                                                |
                                                wet gain
                                                  tanh limiter
                                                    dry/wet mix
                                                      |
                                                      Output
                                                      |
                                                      feedback (x0.9) ---> delay line


================================================================================
TugPhonon by 2Rule — Esat Tugrul Akyuz
