Soundtracker DMA v2.0
=====================
By Zik/Futurs', released on June 2021.

Soundtracker DMA is a music editing software for Amstrad Plus. It takes
advantage of CPC+ audio DMA lists to allow AY-SID and AY-sample sounds while
keeping CPU usage low.

The editor runs on Amstrad Plus with 128KB of memory.

This text file is a minimal user manual, you can read a complete version at:
https://soundtrackerdma.cpcscene.net


Soundtracker DMA is freeware.

Please send your comments, suggestions and bug reports in English or French by
e-mail to zik@cpcscene.net

========================================
== General
========================================
Remarks:
 - UniDOS is supported (display and browse directories)
 - Music is exported as a stream of data
 - Filenames are generated from objet names (sample, instrument, song)
 - Numbers use hexadecimal notation

========================================
== Keyboard shortcuts
========================================
Remarks:
 - Warning! "Ctrl + Shift + Esc" is enabled
 - French, English and Spanish keyboards are supported

Common keys
-----------
 * f1/f2/f3     * Mute/Unmute A/B/C channel
                  (from menu, while playing song or pattern)
 * f6           * Octave+1
 * f9           * Octave-1
 * f5           * Item+1
 * f8           * Item-1
 * Shift + f5   * Next linked item for samples, item+1 for other objects
 * Shift + f8   * Previous linked item for samples, item-1 for other objects
 * Ctrl + right * Change active list
 * Ctrl + left  * Change active list
 * Ctrl + f6    * Change active list
 * Ctrl + f4    * Change active list

Menu keys
---------
 * Escape             * Go up one level in the menu hierarchy
 * Tab                * Enter song list editor
 * Space              * Select current menu entry
 * up/down/left/right * Move cursor

Play song keys
--------------
 * Tab           * Move to the next song-list position
 * Esc           * Stop music
 * Shift + space * on "Play Song", play music from the start of the song-list
                   otherwise, play from the last selected song-list position

Songlist editor keys
--------------------
 * Esc          * Leave song list editor
 * up/down      * Move cursor
 * left/right   * Move cursor
 * f1           * Go to first position
 * f3           * Go to last position (song length)
 * Return       * Set music length (song length)
 * Space        * Set music looping step (song "loop to")
 * Shift + up   * Increase value
 * Shift + down * Decrease value
 * Ctrl + up    * Increase value (pattern+8)
 * Ctrl + down  * Decrease value (pattern-8)
 * Ctrl + n     * Set pattern number to the first empty pattern available
 * Del          * Clear the current value (set to 0)
 * f0           * Insert one position
 * f.           * Remove one position

Pattern editor keys
-------------------
When entering editor from menu:
 * Space         * Edit pattern (last edited pattern)
 * Shift + space * Edit pattern (from song list position)
 * Ctrl + space  * Edit pattern (last played pattern at last played step)

In pattern editor:
 * Esc          * Leave pattern editor
 * Return       * Stop all sounds
 * f4           * Pattern+1
 * f7           * Pattern-1
 * f0           * Insert line to current channel
 * f.           * Remove line from current channel
 * Shift + f0   * Insert pattern line
 * Shift + f.   * Remove pattern line
 * Copy         * Play current pattern position
 * up/down      * Move cursor
 * left/right   * Move cursor
 * Ctrl + 1     * Move to the first line of the pattern
 * Ctrl + up    * Move 8 lines up
 * Ctrl + down  * Move 8 lines down
 * Shift + 1    * Copy track to clipboard
 * Shift + 2    * Cut track to clipboard
 * Shift + 3    * Paste track from clipboard
 * Shift + 7    * Copy note to clipboard
 * Shift + 8    * Paste note from clipboard
 * Shift + 0    * Reset clipboard position
 * Tab          * Increase "skip" value
 * Ctrl + Tab   * Decrease "skip" value
 * Del          * Clear field or note
 * Clr          * Write a "Res" to pattern
 * Ctrl + r     * Write a "Res" to pattern
 * Ctrl + s     * Write a "Smp" to pattern
 * piano keys   * Write note to pattern
 * 0-9, A-F     * Enter hex value

Instrument editor keys
----------------------
 * Esc          * Leave instrument editor
 * Ctrl + right * Switch editor (to sequence editor)
 * Ctrl + left  * Switch editor (to sample editor)

 * Enter      * Change instrument name
     * Esc    * Abandon name input
     * Return * Confirm name
     * Del    * Delete last character

 * up/down       * Move cursor
 * left/right    * Move cursor
 * f1            * Go to first step
 * f3            * Go to last step (length)
 * f4            * Speed+1
 * f7            * Speed-1
 * Return        * Set instrument length
 * Space         * Set looping step
 * Ctrl + space  * Toggle loop
 * Shift + up    * Increase value
 * Shift + down  * Decrease value
 * Ctrl + up     * Increase value (fast, for arp and periods)
 * Ctrl + down   * Decrease value (fast, for arp and periods)
 * Del           * Clear/reset field
 * Shift + del   * Clear/reset complete line
 * f0            * Insert an empty line
 * f.            * Remove a line
 * Shift + f0    * Insert a duplicate line
 * Shift + f.    * Remove a line
 * piano keys    * Play instrument
 * any other key * Stop sound

Sequence editor keys
--------------------
 * Esc          * Leave sequence editor
 * Ctrl + right * Switch to next editor
 * Ctrl + left  * Switch to next editor

 * Enter      * Change sequence name
     * Esc    * Abandon name input
     * Return * Confirm name
     * Del    * Delete last character

 * up/down       * Move cursor
 * left/right    * Move cursor
 * f1            * Go to first step
 * f3            * Go to last step (length)
 * f4            * Speed+1
 * f7            * Speed-1
 * Return        * Set sequence length
 * Space         * Set looping step
 * Shift + up    * Increase value
 * Shift + down  * Decrease value
 * Ctrl + up     * Increase value (+12)
 * Ctrl + down   * Decrease value (-12)
 * Tab           * Copy value to next position
 * Del           * Clear current value (set to 0)
 * piano keys    * Play sequence using current instrument
 * any other key * Stop sound

Sample editor keys
------------------
 * Esc          * Leave sample editor
 * Ctrl + right * Switch editor (to instrument editor)
 * Ctrl + left  * Switch editor (to sequence editor)

 * Enter      * Change sample or alias name
     * Esc    * Abandon name input
     * Return * Confirm name
     * Del    * Delete last character

 * Shift + right * Increase offset (for a sample alias)
 * Shift + left  * Decrease offset (for a sample alias)
 * Shift + up    * Fast offset increase (for a sample alias)
 * Shift + down  * Fast offset decrease (for a sample alias)
 * Ctrl + a      * Create a new sample alias
 * Space         * Play/Stop sample

Discop keys
-----------
 * Esc      * Cancel file selection
 * Del      * Go up one directory level (Unidos)
 * up/down  * Move cursor
 * Space    * Select current item


Stream save keys - from discop menu
-----------------------------------
 * Esc   * Cancel file save

========================================
== Pattern & FX options
========================================

Valid combinations
------------------

Note/Ins/Vol/FX/Param
C#4  7F   F  A  35
C#4  7F   -  A  35 => volume maximum is unchanged
D#4  --   F  A  35 => change note but continue instrument
---  --   F  A  35 => volume & effect but no note
C#4  7F   F  -  -- => note & volume at maximum
C#4  7F   -  -  -- => note alone (at current volume)
---  --   D  -  -- => only change maximum volume for current note or sample
---  --   -  A  35 => effect only
Res  --   -  -  -- => stop sound (note or sample), no volume or effect change
Res  --   C  -  -- => stop sound (note or sample), change maximum volume
Res  --   -  X  00 => stop sound & effects
Smp  03   -  -  -- => sample (at full volume)
Smp  03   4  -  -- => sample at specified volume (full or dimmed)

Invalid combinations
--------------------
List is not exhaustive.

Note/Ins/Vol/FX/Param
Smp  --  -   -  -- => ignored
---  7F  -   -  -- => ignored

Volume of samples
------------------
Two volume levels are possible for samples: full or dimmed. Hence, volume
column for samples works a bit differently than for instrument notes:

Smp nn -  => full volume (when no volume is specified)
Smp nn v  => full volume if v>=8; dimmed volume if v<8 (0 included)
--- -- v  => full volume if v>=8; dimmed volume if v<8 (0 included)
--- -- -  => no volume change


Effect reference
----------------

"Special" column effects (leftmost column):
 - Txx - Set tempo (T00 is ignored; T01 is the fastest tempo)
 - Bxx - Break pattern if xx=0, ignored otherwise
 - Exx - Entry point (xx=00 to 3F, ignored otherwise)
 - Sxx - Signal to external application (xx=00 to 7F, ignored otherwise)


A/B/C channel effects:
 - Axy - Set Arpeggio (3 note arpeggio +0 +x +y)
 - Uxy - Slide pitch Up (portamento up), x=speed, y=depth; 0x=repeat
 - Dxy - Slide pitch Down (portamento down), x=speed, y=depth; 0x=repeat
 - I0x - Fade volume In
 - O0x - Fade volume Out
 - Vxy - Vibrato
           x=speed (1 is the fastest; option ignored if 0y)
           y=depth (x0 stops vibrato; option ignored if y > 7)
 - Xxx - Stop all FXs (arpeggio, arp seq, vibrato, pitch seq, SID offset)
           xx parameter is ignored
 - Sxx - Use arpeggio Sequence (option ignored if xx > 63)
 - Pxx - Pitch sequence (option ignored if xx > 63)
 - Bxx - Change arpeggio speed (Axy or Sxx arpeggio)
 - Qxx - Change pitch sequence speed
 - Jxx - Change instrument speed
 - Zxx - Set SID offset (add offset to calculated note, unit is 1 HBL)
           xx is a signed hexadecimal value (FF == -1), default is 0.
           This option is not related to a channel as there is only
           one SID at a time.

Remark:
All effects continue until they are stopped, except portamento up/down
and volume fade in/out.
