A mirror of SoundHelix, the software MadHelix is based on.

[[ 🗃 ^zoKmE soundhelix ]] :: [📥 Inbox] [📤 Outbox] [🐤 Followers] [🤝 Collaborators] [🛠 Commits]

Clone

HTTPS: git clone https://vervis.peers.community/repos/zoKmE

SSH: git clone USERNAME@vervis.peers.community:zoKmE

Branches

Tags

soundhelix-0.0.4 :: doc /

README-BASICS.txt

SoundHelix
----------

Author: Thomas Schürger (thomas@schuerger.com)


Ticks
-----

The basic time unit in SoundHelix is a tick. A tick subdivides a beat into an
integer number of parts. Songs usually use 4 ticks per beat, but other numbers
(3, 8, 12, 16 or 24) are also common. For the MIDI player, the number of ticks
per beat must divide 24 (at least if MIDI time synchronization is used), so 16
would not be a valid number in this case, but the others would.


Harmony
-------

A harmony is a sequence of chords that is used as a repeating template
throughout the song. Each chord in the template has a length that is usually
counted in beats. A chord template usually forms a chord section. Within a
chord section the active instruments generally don't change. However, it is
also possible to subdivide a chord template into more than one chord section.

Harmonies are created using HarmonyEngines. Currently, only one HarmonyEngine
is included in SoundHelix, which is the PatternHarmonyEngine. The PatternHarmonyEngine
takes a string that defines the sequence of chords. Normally, the whole pattern forms
a chord section. In order to start a new chord section within the pattern, use
a '+' character. Example: "Am/4,C/4,Am/4,F/4,+Am/4,C/4,Dm/4,F/4".


Sequence
--------

A sequence (class Sequence) is a sequence of notes and pauses for one voice. A
note has a pitch, a length in ticks, a velocity (volume) and a legato flag. The
legato flag if set will make sure that the note-on for the following note will
be sent before the note-off for the current note. This makes it possible to
change the pitch of a note without restarting the ADSR (attack, decay, sustain,
release) cycle. Together with portamento, this makes nice slides possible.
Note however, that legato and portamento must be supported by the MIDI playback
device if it is to be used.

Sequences are combined into tracks, which are assigned to an instrument. Tracks
are generated by SequenceEngines. Several SequenceEngines are provided with
SoundHelix, for example ArpeggioSequenceEngine, ChordSequenceEngine,
DrumSequenceEngine, MelodySequenceEngine, MultiPatternSequenceEngine,
PadSequenceEngine, PatternSequenceEngine and RandomSequenceEngine.

All generated sequences usually span the whole song.


Patterns
--------

Like sequences, patterns are sequences of notes and pauses for one voice.
However, patterns are often used repetitively to create a sequence. While
applying a pattern to create a sequence, often the pattern's notes are
transposed according to the current chord. Therefore, patterns usually don't
use pitches directly, but offsets in a chord table, which are then converted to
pitches when a sequence is created. Additionally, patterns may contain wildcard
characters, which may have a special meaning. Patterns are created by
PatternEngines.


Track
-----

One or more sequences form a track. A whole track is assigned to an instrument.
A track can be of melodic or of rhythmic type. Melodic tracks are subject to
note transposition by the player whereas rhythmic tracks are not subject to
transposition.


Arrangement
-----------

An arrangement is a list of generated tracks and forms the song.


Player
------

A player is responsible for playing an arrangement. Currently, only a MIDI
player is available in SoundHelix.  The MIDI player uses an instrument mapping
table in order to map instruments to MIDI devices and MIDI channels.


ActivityVector
--------------

An ActivityVector is a set of bits that defines for each tick whether an
instrument should be active or not. ActivityVectors usually span the whole
song. SequenceEngines get one or more ActivityVectors as input and together
with the provided patterns, produces a sequence that is active or inactive
according to the ActivityVector.

A SequenceEngine need not strictly adhere to the ActivityVectors it receives.
For example, the DrumSequenceEngine supports conditional patterns, which allow
creating notes whenever ActivityVector activity changes. This allows for example
to create a snare crescendo before the base drum starts. This creation of notes
is allowed even if the ActivityVector is inactive at that time.
[See repo JSON]