# HumanizerHost

**Make your sample libraries breathe.** HumanizerHost is a free VST3
instrument for macOS that hosts your favourite sound libraries and writes a
musical dynamics curve — a swell, a messa di voce, a fade — onto every
sustained note, as MIDI CC, exactly fitted to each note's length. Repeated
notes never sound copy-pasted: every rendition is subtly different.

Built for notation-based workflows (Dorico, Cubase) with sample libraries
that respond to CC dynamics (VSL, Spitfire, EastWest, and others).

## Requirements

- macOS 11 or later — Apple Silicon and Intel (universal binary)
- A VST3 host (developed and tested with Dorico and Cubase)
- Your own VST3 instruments to host inside it

## Installation

Double-click `HumanizerHost-x.y.z.pkg` and follow the installer. The plugin
is installed for all users into:

    /Library/Audio/Plug-Ins/VST3/HumanizerHost.vst3

The package is signed and notarized by Apple — no security warnings, no
terminal commands needed. To uninstall, simply delete that file.

## Quick start

1. Insert **HumanizerHost** as an instrument in your DAW.
2. *Instrument* tab → **Manage plugins...** → scan for your VST3 plugins
   (first run only). Then **Load instrument...** on a slot — type a few
   keywords to filter the list — and load your library. Optionally add an
   insert FX (e.g. a reverb) per slot.
3. *Notes* tab → enable a lane, pick the CC your library responds to
   (CC1 Mod Wheel or CC11 Expression, usually), choose a curve preset,
   and play.

## How it works — the delay is a feature

HumanizerHost delays all MIDI by an analysis window (default 5 s). That is
what lets it know each note's duration *in advance*, so the curve fits the
note exactly. During playback and export the delay is simply part of the
sound; while your DAW's transport is stopped, the plugin passes MIDI
straight through (**Playback only**, on by default), so auditioning and
entering notes feels instant.

Tips:

- Set the **long-note threshold** ~10% below the shortest note you want
  humanized; only notes longer than it get a curve.
- **Variation** (per lane) randomizes each note's curve slightly — around
  20–35% reads as natural playing. Exports are reproducible: rendering the
  same passage gives the same performance.
- **Glide** smooths the CC into each new curve and is legato-aware: on
  overlapping notes it pre-glides so your library's legato transitions
  trigger at the right dynamics.
- The green **Enabled** / red **Disabled** button (top right of the window)
  bypasses the humanizer in every instance at once for A/B comparison —
  instruments and insert FX keep running.
- Save your own curve shapes with **Save as preset...** — they are stored
  app-wide and available in every project.

Everything — hosted plugins, their state, curves, settings — is saved with
your DAW session, and offline export/render is fully supported.

## Phrase humanization

The *Phrase* tab shapes your dynamics CC across whole musical phrases, not
just single notes. A phrase is a run of notes closer together than the
**gap** (default 100 ms), starting after a real **silence** (default 1 s).
The first note sets the reference: the CC is scaled up as the melody rises
above it and down as it falls below, and the phrase dies away to zero on
its final note — the natural give-and-take of a live player.

- **Dynamics CC**: the controller to shape (usually the same CC your
  library uses for dynamics).
- **Scale per octave**: how strongly the contour follows the melody
  (25% ≈ a quarter louder one octave up).
- **Keyswitch threshold**: keyswitches sit below this pitch (default C0,
  American notation with middle C = C4 — e.g. `C0`, `C-1`, `F#1`). They
  still play, but are invisible to the humanizer: no curves, no phrase
  detection, hidden from the Monitor.

## Version

0.4.0 — the pitch threshold becomes a global **Keyswitch threshold**:
notes below it still play but no longer trigger the long-note curves or
the legato pre-glide either, and they are hidden from the Monitor's note
strip. Smoother output overall: Glide now eases the combined output
(curve × phrase contour), and outside a curve the CC ramps to the
player's value instead of jumping. Variation keeps each note's start and
end exactly on the designed curve. New defaults for fresh instances:
scale per octave 70%, Variation 25%.

0.3.0 — new *Monitor* tab: a live before/after view of every humanized
CC — the output as a solid curve, the player's original values dashed —
with a piano-roll note strip, a sliding 1–30 s window and a Freeze
button.

0.2.0 — phrase humanization: the dynamics CC follows each phrase's melodic
contour and fades on its last note, with a pitch threshold so keyswitches
don't disturb it. Session-wide bypass is now a green/red button above the
tabs; the Humanize tab is renamed *Notes*.

0.1.0 — first public release.

## Credits & legal

Created by Franck Dansaert.

Made with [JUCE](https://juce.com). VST is a trademark of Steinberg Media
Technologies GmbH, registered in Europe and other countries. This product
uses the VST 3 SDK, © Steinberg Media Technologies GmbH, under the
MIT License.

This software is provided free of charge, as is, without warranty of any
kind. Back up your projects. Feedback and bug reports are welcome.
