﻿Polivoks — Polivoks synthesizer emulation: installation and use
================================================================

Formats:
- Windows x64: Polivoks.vst3 (for your DAW) and Polivoks.exe (standalone app).
- macOS 10.15 or later, Apple Silicon and Intel: Polivoks.component (Audio Unit for Logic Pro,
  GarageBand, MainStage), Polivoks.vst3 (Ableton Live, Bitwig, Reaper, Cubase and other DAWs)
  and Polivoks.app (standalone app).


INSTALLATION — WINDOWS
----------------------
1. Copy the whole Polivoks.vst3 folder to
   C:\Program Files\Common Files\VST3\
2. Ableton Live: Options -> Settings (Preferences in older versions) -> Plug-Ins:
   turn on "Use VST3 Plug-In System Folders" and press "Rescan".
3. The plugin appears in the browser under Plug-Ins -> VST3 (possibly in the
   Ivan Abrosimov folder). Drag it onto a MIDI track.

Without a DAW: Polivoks.exe is a standalone app with an on-screen keyboard.
Options -> Audio/MIDI Settings: choose your audio interface and MIDI keyboard.

Windows may show a SmartScreen warning for Polivoks.exe because the program is not signed.
Click "More info" -> "Run anyway".


INSTALLATION — macOS
--------------------
1. Copy the files:
     Polivoks.component -> ~/Library/Audio/Plug-Ins/Components/
     Polivoks.vst3      -> ~/Library/Audio/Plug-Ins/VST3/
   (The ~/Library folder is hidden: in Finder use Go -> Go to Folder… and type the path.)
2. The plugin is not yet signed with an Apple certificate, so macOS blocks files downloaded
   from the internet. Run these commands once in Terminal:
     xattr -dr com.apple.quarantine ~/Library/Audio/Plug-Ins/Components/Polivoks.component
     xattr -dr com.apple.quarantine ~/Library/Audio/Plug-Ins/VST3/Polivoks.vst3
     xattr -dr com.apple.quarantine /path/to/Polivoks.app
3. Logic Pro: Logic Pro -> Settings -> Plug-in Manager. Find Ivan Abrosimov -> Polivoks;
   if it failed validation, press "Reset & Rescan Selection".
   The plugin is under AU Instruments -> Ivan Abrosimov -> Polivoks.
4. Ableton Live and other DAWs on Mac use Polivoks.vst3 — enable VST3 in the DAW's plug-in
   settings and rescan.


WHERE YOUR DATA IS STORED
-------------------------
- Your presets (*.polivoks):
    Windows: Documents\Polivoks\Presets
    macOS:   ~/Library/Audio/Presets/Ivan Abrosimov/Polivoks
- Ratings (ratings.xml), default MIDI Learn mappings (midi-map.xml), language and the
  first-launch flag (settings.xml):
    Windows: %APPDATA%\Polivoks
    macOS:   ~/Library/Application Support/Polivoks


CONTROLS
--------
- All knobs are laid out as on the original panel. Double-click returns a knob to its default.
- A detailed guide to every control is built into the plugin: gear at the top right ->
  GUIDE tab (in all 13 languages).
- HOLD switch (bottom right, in the amplifier section; "ВКЛ." on the original):
  up (ON) — played notes keep sounding after you release the keys; a new chord played after
  releasing all keys replaces the held one; when switched on, the last played note sounds
  (if nothing has been played yet — silence until the first note). Down (OFF) — normal mode.
- OUTPUT switch: ON — sound passes, OFF — the plugin is muted.
- The mod wheel (CC1) or an expression pedal (CC11) works as the cutoff pedal, as on the original.
- Pitch bend and the sustain pedal work, although the original had neither.
- External input: the plugin has an audio input, but whether your DAW sends audio to an
  instrument's input depends on the DAW (not yet checked in Ableton). The input level is set
  with the EXTERNAL knob; together with HOLD (play one note) the filter works as an effect.

Top bar (not on the original)
From left to right: LIBRARY, ◀ preset name ▶, rating, SAVE, SUPPORT THE AUTHOR;
on the right — TEMPO and the gear.

Keyboard at the bottom
- Full MIDI range (C-1…G9), 4 octaves on screen. Scroll with the arrows at the edges, the mouse
  wheel or a touchpad gesture. Click a key with the mouse to play a note.


INTERFACE LANGUAGE
------------------
- 13 languages: English, Chinese, Hindi, Spanish, Arabic, French, Bengali, Portuguese,
  Indonesian, Urdu, Russian, German, Japanese.
- Choose it in the About window or in the settings (gear -> GUIDE tab -> INTERFACE LANGUAGE).
  Translated: panel labels, the top bar, the library, settings, factory preset names, the guide,
  and the parameter names and values shown by your DAW. The "ПОЛИВОКС" logo stays as on the
  original.
- Some DAWs re-read parameter names only after the plugin or the project is reloaded.


ABOUT THE PLUGIN AND SUPPORTING THE AUTHOR
------------------------------------------
- On the first launch of each format (VST3 in a DAW, AU in Logic, the standalone app) the About
  window appears (in English by default; choose the language in the list at the top of the
  window). Close it with "Continue" — it won't appear again.
- To open it again, press SUPPORT THE AUTHOR in the top bar: donations and contacts are there.
- Terms of use are in the License folder (a file in your language).


PRESETS
-------
- LIBRARY (or a click on the preset name) opens the list. Click a row to load it.
  Filters on the left: ALL / FACTORY / USER, MINIMUM RATING (1–5 stars), search by name
  and description. The ◀ ▶ arrows step through presets respecting these filters.
- Rating: click a star to rate, click the same star again to clear the rating.
  You can rate in the list and in the top bar. Ratings are shared by all instances of the plugin
  on this computer.
- SAVE stores the current sound as your own preset. If the name is taken, the preset is
  overwritten (a warning tells you). Delete your presets in the library: DELETE, then
  REALLY DELETE?.
- Your presets live in the preset folder (see "Where your data is stored"; OPEN PRESET FOLDER
  button in the library). You can copy them between computers.
- An asterisk and MODIFIED next to the name mean the sound differs from the saved preset.
- Presets do not store the tempo or the OUTPUT switch.


TEMPO
-----
- PROJECT — tempo and grid come from your DAW. MANUAL — set the tempo in the field on the right:
  drag up/down (hold Shift for fine steps), use the mouse wheel or double-click and type a number
  (30–300 BPM).
- The standalone app has no project, so it only has the manual tempo field.
- If the DAW does not report a tempo, the plugin uses its own tempo.

Tempo sync
- Modulator: the TEMPO SYNC button under the rate knob. When it is lit, the RATE knob becomes
  DIVISION: from 4 bars to 1/32, including dotted (.) and triplet (T) values. The current tempo
  and its source are shown on the right. In PROJECT mode during playback the modulator phase
  follows the project grid; when stopped, the modulator keeps running at the same tempo.
- Envelope loops: the ENV MODE switch in the filter and in the amplifier has three positions —
  one-shot / loop / TEMPO. In the TEMPO position the envelope restarts on every grid division
  (DIVISION knob next to it) while a key is held or HOLD is on.


GEAR AT THE TOP RIGHT
---------------------
A panel opens on the right side of the window (the window gets wider). Tabs:
- GUIDE — opens first: language choice and a detailed guide to all parameters in the selected
  language (the table of contents is clickable). The language applies to the whole plugin.
- MIDI — MIDI Learn (below).

MIDI Learn (gear -> MIDI tab)
Many DAWs (for example, Ableton with Push) map parameters to a controller by themselves — then
you don't need MIDI Learn. It helps where your DAW doesn't do that.
1. Gear -> MIDI tab -> TURN ON MIDI LEARN — the knobs light up.
2. Click a knob or switch — it gets selected.
3. Move a knob on your controller — the mapping is done, and the CC number appears on the knob.
- In this mode, right-click a mapped control to remove its mapping; the list on the right has a
  cross for each mapping.
- To leave the mode: EXIT on the banner above the panel, the button in the settings, or Esc.
- Mappings are saved with the project. SAVE AS DEFAULT MAPPINGS — new instances of the plugin
  start with them (file midi-map.xml, see "Where your data is stored").
- The controller must reach the MIDI track with the plugin (in Ableton: the track input is your
  controller, Monitor is In, or Auto with record arm on). If the same controller is assigned in
  Ableton's MIDI Map (Ctrl+M on Windows, Cmd+M on Mac), Ableton takes it before the plugin.
- A mapped CC controls only the parameter: if you map CC1 (mod wheel) or CC64 (sustain), their
  usual function is disabled for this plugin.
