Skip to content

Acheron Documentation

Jump to bottom
Liz G edited this page Mar 28, 2024 · 34 revisions

Acheron v1.1.8 Documentation

Acheron is an Electron-based recreation of Elysium, a probabilistic generative MIDI sequencer based on the harmonic table note layout.

Demo/tutorial video by hellvalleyskytrees here: https://youtu.be/y59SFoR82PU

You can support the development of this software here: https://www.patreon.com/whisperdoll

Setup

Download the latest Acheron release here: https://github.com/whisperdoll/acheron/releases

The current version as of this writing is 1.1.8

Please note that Acheron is a MIDI sequencer, and as such produces no sound on its own.

You'll need a Digital Audio Workstation (or other VST host/MIDI receiving application) and MIDI loopback driver (such as loopmidi on Windows, or the built-in IAC driver in the Audio/Midi Settings on Mac), or a MIDI interface and a physical MIDI device.

To use Acheron without a physical MIDI device (e.g. with a DAW or other software):

  • Windows:
    • First, download and install Tobias Erichsen's loopMIDI
    • Use loopMIDI to create a virtual MIDI port (click the plus button at the bottom left of the window.)
  • Mac:
  • Extract Acheron-1.1.8-win.zip or Acheron 1.1.8-mac.dmg and run Acheron.exe/.app.
  • Select Settings (at the bottom of the window.)
  • Under MIDI Outputs select the virtual MIDI port you just created with loopMIDI or the IAC Driver
  • Make sure "loopMIDI port" (on Windows) or "IAC driver" (on Mac) is enabled as an input in your DAW (if applicable.)

Optional:

  • If you don't have a DAW, try onlinesequencer.net which runs in the browser & requires no setup for use with Acheron.
    • Onlinesequencer's record button is on the bottom left of the page, while the save button is near the top middle. the arrow next to the save button allows exporting MIDI or WAV files.
  • Acheron now includes several example files, demonstrating various features. These are in the examples folder.

Visit the main GitHub page for more information, or to contribute: https://github.com/whisperdoll/acheron

IMPORTANT: If you don't see all of the tokens in the Add Token menu, please click on Manage Tokens in the bar at the bottom of the window and make sure the token search paths include /tokens/ in the root of the current Acheron version's folder, and that all of the tokens are enabled.

Keyboard Shortcuts

  • Open Composition (Ctrl+O)
  • Save Composition as (Ctrl+S)
  • Close (Ctrl+W)
  • Add Layer (Ctrl+Shift+N)
  • Toggle Full Screen (F11)
  • Toggle Left Column (Ctrl+L)
  • Toggle Inspector(Right Column) (Ctrl+I)
  • Toggle Multilayer Mode (Ctrl+M)
  • Switch Layer (Ctrl+1 through Ctrl+0 (layers 1 through 10))
  • Zoom In (Ctrl++)
  • Zoom Out (Ctrl+-)

Glossary

The following is a list of terms used by Acheron and their definitions, including information on their properties when applicable:

Menu Bar

At the top of the window. Contains the following items:

  • File
    • Open Composition (Ctrl+O)
    • Save Composition as (Ctrl+S)
    • Close (Ctrl+W)
  • Layer
    • Add Layer (Ctrl+Shift+N)
  • View
    • Toggle Full Screen (F11)
    • Toggle Left Column (Ctrl+L)
      • Show or hide the column on the left, containing the player and layer properties.
    • Toggle Inspector (Ctrl+I)
      • Show or hide the column on the right, containing individual token properties.
    • Toggle Multilayer Mode (Ctrl+M)
      • Allows you to view all layers at once. Note that you can still add and remove tokens in this mode.
  • Help
    • Documentation
      • Links to this page
    • Troubleshooting
      • Links to the troubleshooting section of README.md on the Acheron GitHub.
    • Report a Bug
      • Links to the Bug Report page on the Acheron GitHub.
    • Credits
      • Links to the credits section of README.md on the Acheron GitHub.

Composition

An Acheron document. Options that apply to the whole composition (or all compositions) are located in the bar at the bottom center of the window. These include:

  • Play/Pause (or press enter)
  • Settings, including:
    • Play notes on click
    • Wrap playheads
      • When wrap playheads is on, playheads that exit any side of the grid will appear on the opposite side.
    • Show confirmation prompts when removing things
    • MIDI outputs
      • Here you can select which output(s) you want Acheron to send MIDI data to.
      • If you want to use Acheron with your DAW of choice rather than a hardware device, you'll need a MIDI loopback driver such as loopMIDI
  • Manage Tokens
    • This is where you can add and enable/disable token types. Tokens must be enabled here to add them to a composition.
    • If you don't see all of the tokens in the Manage Tokens window, please make sure the token search paths include /tokens/ in the root of the most recent Acheron version's folder.
    • Optionally you may choose a keyboard shortcut for each token type.
  • Show/Hide inspector (Ctrl-I)
    • Toggles visibility of the column on the right, containing individual token properties.
  • Toggle MultiLayer Mode (Ctrl-M)
    • Allows you to view all layers at once. Note that you can still add and remove tokens in this mode.
  • Report a Bug
    • Links to the Bug Report page on the Acheron GitHub.
  • Support on Patreon

Tick

Time between beats, defined by the player or layer tempo.

Hex

One of the 204 hexagonal cells in the grid at the center of the window, each corresponding to a musical note on the harmonic table

LFO

Low frequency oscillator. Can be used to control most properties, by selecting 'LFO' in the control mode menu next to the propery name. When a property's control mode is set to LFO, a button appears under the property, allowing you to edit the properties of the LFO. These include:

  • LFO Type
    • Can be set to Sin, Square, Random, Sequence, or Sawtooth
  • Minimum Value
  • Maximum Value
  • Period
    • The time it takes the LFO to complete a cycle.
  • Low Period (Square only)
    • The time spent every cycle at the minimum value
  • High Period (Square only)
    • The time spent every cycle at the maximum value

Properties

Properties are located in the panels on the left and right sides of the window.

  • The lefthand panel contains global (player tab) and layer specific (layer tab) properties.
  • The righthand panel contains properties relating to individual tokens. To change the control mode of a property, use the menu immediately to the right of the property name.
  • Properties followed by a * in this document can be controlled by LFOs.
  • Properties followed by a ^ in this document can be inherited from the player or layer settings, and usually are by default.

Player

The player tab in the lefthand panel defines global settings for the composition. It has the following user editable properties:

  • Note settings

    • Transpose*
    • Tempo* (in beats per minute)
    • Bar Length*
      • Controls whether volume is determined by the emphasis property (first beat of each bar) or the velocity property (all other beats.)
    • Velocity*
      • MIDI note velocity. Usually controls the volume of notes.
    • Emphasis*
      • Overrides velocity on the first beat of each bar.
    • Tempo Sync*
      • When Tempo Sync is on, Note Length is measured in Ticks (beats).
      • When Tempo Sync is off, Note Length is measured in seconds.
      • Tempo Sync is on by default.
    • Note Length*

  • Generator settings:

    • Time to Live*
      • Number of ticks to wait before automatically deleting playheads.
    • Pulse Every*
      • Number of ticks to wait between emitting playheads from generator tokens.

Layer

Each layer is its own separate hex grid. Layers can be used to play multiple instruments, at multiple tempos, or simply to create melodies that don't interact with each other. The layer controls are located at the top center of the window, from here you can select, create, delete, and rename layers. The layer tab in the lefthand panel controls the settings of the currently selected layer. It contains all of the same properties as the player tab (inherited from the player tab by default) as well as the following:

  • Enabled*
    • enable or disable the layer
  • MIDI channel* (1-16)
  • Key*
    • When a key is selected, the notes in that key are highlighted, and note tokens not in the selected key won't play

Playhead

A red hex that moves across the grid, one hex at a time, each tick. Playheads are emitted by generator tokens. A midi note plays when a playhead enters a hex containing a note token. Playheads have the properties direction and lifespan (number of ticks before deletion)

  • These properties are not directly editable by the user. instead, they are manipulated by placing tokens.

Tokens

Tokens create and manipulate playheads. You can place tokens on the selected hex using the add token button near the top of the righthand panel, or by right clicking on a hex, or with user definable keyboard shortcuts. You can remove tokens by clicking the red x at the top right of the panel of the desired token, or by right clicking on a hex, or by combining your user defined keyboard shortcuts with the Alt key. Pressing delete will remove all tokens from the selected hex. One way that Acheron differs from Elysium is that Acheron allows multiple tokens of the same type on a single hex. You may also drag and drop tokens from one location on the grid to another (hold shift while dragging to copy) Users can create their own tokens with json and javascript, for more information see the custom token documentation

Built in tokens

Acheron currently comes with the following tokens:

Note token

Plays the midi note of the hex it is located on when entered by a playhead. It has the following properties, editable in the righthand panel:

  • Probability*
    • Controls whether a token runs or is ignored in a probabilistic manner. It's value is the percent chance the token will run.
  • Triad*
    • Plays the selected three note chord (relative to the token's hex) instead of a single note.
      • One of the advantages of the harmonic table layout is that these simple clusters form common chords, the shapes of which are the same in any key.
  • Transpose*
  • Gate:
    • Controls whether a token runs or is ignored in a deterministic manner.
    • Each time a token is entered by a playhead, the token's internal gate sequence is advanced by one. When the gate sequence reaches the end, it loops.
      • Gate Off*
        • Number of times to ignore token. Runs first by default.
      • Gate On*
        • Number of times to run token. Runs after gate off by default.
      • Gate Offset*
        • Offsets the gate sequence.
        • For example, if you set gate off to four, gate on to four, and gate offset to two, you get the sequence ( off, off, on, on, on, on, off, off )
    • Velocity*^
      • MIDI note velocity. Usually controls the volume of notes.
    • Emphasis*^
      • Overrides velocity on the first beat of each bar.
    • Note Length*^ (in ticks or seconds)

Generate token

Emits playheads in the chosen direction. It has the following properties, editable in the righthand panel:

  • Trigger Mode*
    • When set to beat, playheads are emitted at the beginning of each period defined by the pulse every property. This is the default.
    • When set to impact, playheads are emitted when a playhead enters the hex containing the token.
    • When set to MIDI, playheads are emitted when the user plays the midi note corresponding to the hex containing the token.
  • Probability*
    • See the probability section of the note token documentation.
  • Direction*
  • Pulse every*^
    • Number of ticks to wait between emitting playheads.
  • Offset*
    • Position in the cycle defined by pulse every at which playheads are emitted.
    • For example, if pulse every is set to four, and offset is set to one, the following pattern will result, with 0 representing the emission of a playhead: x0xxx0xxx0xxx0xx...

Rebound token

Changes the direction of any playhead that enters the hex it is located on. It has the following properties, editable in the righthand panel:

  • Probability*
    • See the probability section of the note token documentation.
  • Direction*
  • Gate*
    • See the gate section of the note token documentation.

Skip token

Moves any playhead that enters it in the direction it's currently going (or the direction of a rebound token on the same hex) by the specified amount. Supports negative numbers, allowing a playhead to "skip backwards" in the opposite of its current direction. It has the following properties, editable in the righthand panel:

  • Probability*
    • see the probability section of the note token documentation.
  • Skip Amount*
  • Gate*
    • See the gate section of the note token documentation.

Split token

When a playhead enters a hex with a split token, a playhead is generated in every direction except the one the initial playhead came from, unless Bounceback is turned on, in which case it generates one that way too. It has the following properties, editable in the righthand panel:

  • Probability*
    • see the probability section of the note token documentation.
  • Gate*
    • See the gate section of the note token documentation.
  • Bounceback*

Absorb token

Deletes any playhead that enters its hex. It has the following properties, editable in the righthand panel:

  • Probability*
    • See the probability section of the note token documentation.
  • Gate*
    • See the gate section of the note token documentation.

Wormhole token

Transports any playhead that enters its hex to the location of another wormhole token on the same channel. Note that this works between layers. It has the following properties, editable in the righthand panel:

  • Probability*
    • see the probability section of the note token documentation.
  • Gate*
    • See the gate section of the note token documentation.
  • Sync Channel I/O*
    • When checked, input and output channel are the same. On by default.
  • Channel*
    • the channel to send and receive playheads on (when Sync Channel I/O is on)
  • Send to Channel* (only visible when Sync Channel I/O is off)
    • The channel to send playheads to when Sync Channel I/O is off.
    • You can create wormholes that can receive playheads, but can also be passed over safely, by setting Send to Channel to a channel not in use by any wormholes.
  • Receive from Channel* (only visible when Sync Channel I/O is off)
    • The channel to receive playheads from when Sync Channel I/O is off.
  • Send Behavior*
    • Determines where to send playheads when more than one wormhole is available to receive on the same channel. Its options are:
      • Random
        • Chooses a wormhole (other than the one entered) at random.
      • Sequence
        • Chooses a wormhole (other than the one entered) in a sequence defined by the Priority property.
  • Priority*
    • When a wormhole token's Send Behavior is set to Sequence, and more than one wormhole is available to receive on the same channel, Priority determines which wormhole will receive sent playheads, with higher priority wormholes receiving first, then proceeding in sequence to lower priority wormholes.

Randomize token

Randomizes the position, direction, and/or layer of any playhead that enters its hex. It has the following properties, editable in the righthand panel:

  • Probability*
    • see the probability section of the note token documentation.
  • Random Location*
  • Random Direction*
  • Random Layer*
  • Gate*
    • See the gate section of the note token documentation.

Lifespan token

Adds or subtracts from the lifespan of any playhead that enters its hex. It has the following properties, editable in the righthand panel:

  • Probability*
    • See the probability section of the note token documentation.
  • Amount*
    • Number of beats to add to or subtract from lifespan.
  • Gate*
    • See the gate section of the note token documentation.

Twist token

Rotates the direction of any playhead that enters its hex. Positive values rotate clockwise, negative values rotate counterclockwise. It has the following properties, editable in the righthand panel:

  • Probability*
    • See the probability section of the note token documentation.
  • Twist Amount*
    • Number of steps to rotate.
  • Gate*
    • See the gate section of the note token documentation.
Clone this wiki locally