﻿Harmelody - Windows install
===========================

Two plugins in here:

  Harmelody       adds up to 4 in-key harmony voices to a vocal
  Harmelody Tune  autotune on its own

Both are VST3, so they work in Reaper, Ableton, Cubase, Studio One, FL Studio,
Bitwig. There's no AU version, that's a Mac-only format. Standalone apps are in
here too and don't need installing at all.


Unblock the zip first
---------------------

Windows flags anything you download. Clear it on the zip before you extract and
everything inside comes out clean:

  Right-click the zip -> Properties -> tick "Unblock" -> Apply

Then Extract All.

You can skip this, but you'll get a few extra "are you sure" prompts, and
clearing it afterward means doing it one file at a time.


Install
-------

Drag both folders out of the VST3 folder and into your plugin folder:

  VST3\Harmelody.vst3        ->  C:\Program Files\Common Files\VST3\
  VST3\Harmelody Tune.vst3   ->  C:\Program Files\Common Files\VST3\

Windows asks for admin because that folder is shared. Click Continue. Rescan
plugins in your DAW and that's it.

These are folders, not files, even though Windows draws them with a plugin
icon. Drag the whole folder.

No reboot, and nothing gets installed anywhere else. Delete those two folders
and the plugins are gone.


Updating later
--------------

Don't skip this part. It's the thing that goes wrong every time.

If a folder with the same name is already in your VST3 folder, delete it first.
Don't drag the new one on top. Windows merges same-named folders instead of
replacing them, so you end up with:

  Harmelody.vst3\Harmelody.vst3\...

and your DAW keeps loading the old version. No error, no warning, and the
update looks like it did nothing at all.

Delete, then copy. Or use the installer, which can't get this wrong.


The installer
-------------

Double-click Install-Harmelody.bat

Same copy, except it deletes the old version first and then checksums what it
installed, so it can't nest folders. Worth using for updates even if you
dragged them in by hand the first time.

Uninstall-Harmelody.bat removes both plugins.

Use the .bat, not the .ps1 sitting next to it. Windows blocks PowerShell
scripts by default, so right-clicking the .ps1 and picking "Run with
PowerShell" fails on most machines with "running scripts is disabled on this
system". The .bat isn't subject to that rule and does the same thing. The .ps1
is there if you want to pass it options.


Installing somewhere else
-------------------------

If you'd rather not give admin at all, put the folders anywhere you can write
and add that path to your DAW's VST3 search paths. The installer will do it
for you:

  powershell -ExecutionPolicy Bypass -File .\Install-Harmelody.ps1 -Destination "D:\My VST3"


"Windows protected your PC"
---------------------------

You'll get this. These builds aren't code-signed. I'm not buying a certificate
for a private beta, so the warning turns up no matter what and doesn't mean
anything is wrong.

  Click "More info" -> "Run anyway"

Defender might also stop to scan the standalone .exe the first time.

If you want to confirm you've got the file I actually sent, check its SHA-256
against the one in my email:

  Get-FileHash .\Harmelody-0.9.1-Windows.zip

There's no signature on these, so that's the only way to be sure. If it doesn't
match, don't run it, just tell me.


Restart your DAW
----------------

Reaper rescans whenever you ask it to. Ableton caches plugins hard and needs a
full quit and relaunch, a rescan on its own usually isn't enough.

The standalone apps don't need installing. Run them straight out of the
Standalone folder.


Using it
--------

GETTING-STARTED.txt covers routing chords in Ableton and Reaper, plus
troubleshooting. Two things to know going in:

  - Harmelody with no chord source still harmonizes. It uses the key shown in
    the header, which is C major on a fresh instance.
  - Harmelody Tune with no key source does nothing, on purpose. Set Mode to
    Scale Preset and pick a root and scale, or route MIDI chords.


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

The plugin header shows a version like "v0.9.1 - 3 Aug 14:22". Send me that and
the name of the zip you installed from, plus your DAW and Windows version.
It's the only way I can tell which build you're on.

blaine.cowen@gmail.com


What changed in 0.9.4
---------------------

- Studio is now Harmelody's own engine. It keeps the singer's formants intact
  better on wide shifts, tunes exactly, and costs less CPU. Auto still switches
  to it on export, so exports made with 0.9.4 can sound slightly different from
  earlier ones.
- Engine now defaults to Auto: the fast engine while you play, Studio
  when your host renders. See "Known limits" below for what that means for
  your exports.
- Fixed clicks in the lead vocal on the Studio engine. Whenever a harmony voice slid
  to a new note, the lead's own delay moved with it, which ticked at every step
  of the slide and left the lead about 1 ms late against your other tracks.
  On Auto that is every export, so if an earlier bounce had faint ticks on the
  lead, re-export it.


What changed in 0.9.2
---------------------

- Fixed crackling / static on note attacks. The pitch detector briefly loses
  confidence at the start of every plucked or struck note, and the harmony
  voices were dropping to unshifted and sliding back each time. On a voice that
  happens at consonants, so it was occasional roughness; on an instrument it's
  every note, which is why it came across as constant static.
- Mix and Lead no longer step when you move them, so no zipper noise on a knob
  drag or under automation.
- Switching Autotune off no longer replays a short burst of stale audio.
- With a sidechain routed on a mono track, the chord source was leaking into
  the lead. Fixed.
- Key detection no longer runs its FFT when Key From is set to MIDI, which
  saves some CPU if you have a sidechain routed.


Known limits in this beta
-------------------------

- Not code-signed, so Windows warns on first run. See above.
- One note at a time. Chords in, harmonised chords out, is not something it
  does - see GETTING-STARTED.txt.
- Both windows resize from the bottom-right corner. They scale as a whole and
  keep their proportions, so nothing reflows.
- Engine shows which engine is actually running - beside the control in
  Harmelody, in the bottom status bar in Harmelody Tune. On Auto that is the
  only way to tell.
- Engine defaults to Auto: the fast engine (~17-31 ms) while you play, and
  Studio automatically when your host renders, bounces, freezes or
  exports. So your export won't be identical to what you monitored - it's the
  same performance rendered better. Pick an engine by hand if you need them to
  match exactly.
- Throat Length can't be shifted by the fast engine, which keeps formants by
  copying waveform grains. On Auto, turning Throat off centre switches you to
  Studio for playing as well as exporting, so the latency goes up.
