﻿Harmelody - setup and troubleshooting
=====================================

Read the next two paragraphs before anything else. They account for most of
what gets reported as broken, and neither one is a bug.


What each plugin needs
----------------------

  Harmelody       A vocal and a chord source. With no chord source it still
                  harmonizes, using the Root/Scale key shown in the header,
                  which is C major on a fresh instance. So if the harmonies
                  sound like they're in the wrong key, that's why. Nothing is
                  routed yet.

  Harmelody Tune  A vocal and a key source. With Mode set to MIDI Scale (the
                  default) and no MIDI routed, it does nothing, on purpose. It
                  won't correct toward a key you didn't pick. To use it without
                  MIDI, set Mode to Scale Preset and choose a root and scale.

The two behaving differently is deliberate, not an oversight. A harmonizer that
sits silent until a chord shows up looks broken. A tuner that guesses at a key
sounds worse than one that waits.


What you can put through it
---------------------------

It doesn't have to be a voice. A bass, a synth lead, single notes on a guitar
all work fine.

What it can't do is chords. Both plugins track ONE note at a time, so a strummed
guitar or a held keyboard chord gives the pitch detector nothing it can lock
onto, and you'll hear it flipping between the notes. That's a limitation, not a
bug I can fix - the whole chain is built on knowing what single note is sounding.

Set Voice Range to match your source. It's labelled for voices but it's really
just the frequency range being searched:

  Low    55-500 Hz    bass and baritone, guitar, bass guitar above E2
  Mid    80-1000 Hz   the default
  High   150-1600 Hz  soprano, leads up high

If you're playing a 5-string bass or anything below E2 (41 Hz), it's under the
floor of even the Low setting and won't track. Tell me if you need that and
I'll widen it.


Ableton Live - chords over MIDI
-------------------------------

1. Put Harmelody on the audio track with the vocal.
2. Make a separate MIDI track for the chords.
3. On that MIDI track, set "MIDI To" to the vocal's audio track.
4. Underneath that, pick Harmelody as the target device.
5. Play chords while you sing. The harmonies follow the chord.


Ableton Live - chords from audio
--------------------------------

Use this when the chords are already audio: a guitar, a keyboard part, a
bounced stem.

1. Put the chord instrument on its own track.
2. In Harmelody's device header, set the sidechain source to that track.
3. Set "Key From" to Audio, or MIDI + Audio to use both.

The dot next to KEY FROM lights up when audio is actually coming in. An
unrouted sidechain doesn't produce an error of any kind, so if the key never
settles, check that dot first. It's the quickest way to tell a routing mistake
from a detection problem.

Detection is tuned for a chord instrument playing chords. A full mix with drums
in it is a lot noisier and won't be as reliable.


Reaper
------

Add channels 3/4 to the track, then pin them to the plugin's sidechain input in
the routing matrix. Reaper exposes this more directly than Ableton does.


No DAW at all
-------------

Both plugins ship as standalone apps too, in the Standalone folder of this
archive. They take live audio and MIDI in, set your interface under
Options > Audio Settings. It's the quickest way to hear the plugin without
setting up any routing, and a good way to tell a plugin problem from a routing
problem.


What I'd like you to try
------------------------

Anything you want, but these four are what I most need answered:

- Does key detection follow YOUR material? Chord changes, key changes, anything
  modal or ambiguous. This is the part most likely to let you down.
- Is the latency workable while tracking? Engine is on Auto, which means you
  get the fast engine (~17-31 ms) while you play and the best-sounding one
  automatically when you export. Tell me if the live latency still gets in the
  way, and whether your exports sound right.
- Do the harmonies sit like other singers, or like an effect? Detune, Humanize
  and Width are the controls that decide that.
- Does anything crash, glitch, or stop making sound? Note what you did right
  before it happened.


TROUBLESHOOTING
===============

Harmelody Tune does nothing
  Mode is on MIDI Scale (the default) and no MIDI is routed. Either route MIDI
  chords, or set Mode to Scale Preset and pick a root and scale. See the top of
  this file, this one is by design.

The harmonies are in the wrong key
  No chord source is reaching the plugin, so Harmelody is falling back. In MIDI
  mode the Root and Scale controls get relabelled FALLBACK and sit to the right
  of the KEY FROM dot. They move when you change Mode, which can look like they
  vanished. Set them to the song's key, or route a chord source.

The key takes a moment to settle
  That's expected. A hand-played chord doesn't land all at once, so the detector
  collects for 0.15-0.45 seconds from the first note before it commits.
  Otherwise whichever note you hit first would decide the key by itself. Key
  Stability scales that window.

The sidechain does nothing
  The sidechain input stays disabled until something is routed to it, and it
  doesn't complain when nothing is. Check the dot next to KEY FROM, and check
  KEY FROM is set to Audio or MIDI + Audio rather than MIDI.

Some voices are silent
  Voices mute when pitch confidence drops below the Sens threshold, when the
  input is below the gate, or when the voice is set to Off. Voices 1 and 2 are
  on by default, 3 and 4 are Off. Breathy or very quiet passages will drop
  voices, that's the confidence threshold doing its job.

Crackling or static on note attacks
  Fixed in 0.9.2. The shift ratio was dropping out whenever the pitch detector
  briefly lost confidence, which happens on every attack of a plucked or struck
  note, so the voices snapped to unison and slid back several times a second.
  If you still hear it on 0.9.2, tell me - and say whether it's on the attacks
  or the sustains, because that distinguishes two different causes.

Clicks or ticks on the lead in an export
  Fixed in 0.9.4. On the Studio engine - which Auto uses for every
  export - the lead's delay moved whenever a harmony voice slid to a new note.
  Re-export anything bounced on an earlier version. If you still hear it on
  0.9.4, tell me which engine the readout showed.

Doubling or smearing while I sing
  You're monitoring through the plugin and hearing its latency. On Auto that
  should be ~17-31 ms, which most people can sing through. If it feels like
  ~48 ms, either Engine is set to Studio by hand, or Throat Length
  is off centre - see below. Keep your host's delay compensation on either way.

My export doesn't sound the same as what I monitored
  That's Auto working. While you play you get the fast engine, and the moment
  your host renders, bounces, freezes or exports it switches itself to
  the Studio engine, which sounds better but is far too slow to sing through. It's the same
  performance rendered better, not a different take.

  Confirmed in both hosts: Ableton's Export Audio and Freeze Track, and Reaper's
  Render on its default Full-speed Offline setting. Harmelody switches to the
  Studio engine for the render and back to the fast engine afterwards, with nothing for
  you to do.

  The one case not checked is Reaper's "Online Render" modes. Those run in real
  time on purpose, so you'll likely get the fast engine - if you use them and it
  matters, set Engine to Studio by hand.

  If you need the two to match exactly, pick an engine by hand instead of Auto.

  Harmelody shows which engine is actually running next to the Engine control,
  and Harmelody Tune shows it in the status bar along the bottom - "running
  Live - 31 ms" or "running Studio - 48 ms". On Auto that readout is the only
  way to tell, and it's the first thing to look at if the latency changes.

Throat Length does nothing
  You're on the Live (PSOLA) engine. It keeps formants by copying waveform
  grains, which is also why it can't shift them. On Auto this can't catch you
  out: turning Throat off centre switches you to Studio for playing as well
  as exporting, so what you hear is what you'll get. You will hear the latency
  go up when it does - that's the switch, and it's the point.

The old version keeps loading after I update
  Either the plugin folder got nested inside itself during the copy, or your
  host still has the previous build loaded in memory. Check the install
  instructions for your platform, then remove and re-add the plugin. A rescan
  on its own won't reload code that's already loaded.

The plugin never shows up at all
  Rescan plugins in your host. Ableton caches plugins hard and usually needs a
  full quit and relaunch, not just a rescan. On macOS, Logic and GarageBand
  need:  killall -9 AudioComponentRegistrar


If something breaks
-------------------

The plugin header shows a version like "v0.9.1 - 3 Aug 14:22". Send me that and
the filename of the zip you installed from, the version is what identifies the
build. Add your DAW and OS version, and what you did right before it happened.

blaine.cowen@gmail.com
