Turbochip v0.48 - Junosix 21.01.19
----------------------------------

What is Turbochip?
------------------
Turbochip is a software-synthesizer tracker/sequencer for any Atari ST
computer which has DMA sample playback (STE/Mega STE/TT/Falcon).  Its sound
generation is based on similar principles to several soundchips such as the
Konami SCC (as used in MSX and arcade games) and HuC6280 (used in the
PC Engine game console).

These kind of soundchips create sounds using wavetables and usually have
6 channels.  Wavetables in this sense mean that sounds are made up of short
samples (typically 32 bytes) which are looped.  This enables a more
interesting depth to the sound than the simple square wave typical of
earlier soundchips, but a sound that is still more synthetic when compared
to other sample-based chips such as the Commodore Amiga's Paula which due to
its host computer's large memory is capable of playing back longer samples
which can give a more realistic sound.  The Paula soundchip has 4 channels.

Atari STs with DMA sample playback have two forms of sound generation at
their disposal: the YM2149F PSG soundchip giving 3 square wave channels and
1 noise generator, and a DAC allowing for 1 mono or 1 stereo channel of
PCM audio.  In most cases, it is common to either choose the YM2149F and use
this to create synthesized-sounding music, or use the DAC and use it for
playing sampled music either as a mono or stereo clip sampled from a song
and played back at a fixed frequency, or to play back instrument samples at
varying frequencies and mixing them into several channels in software.

Turbochip takes the approach of combining all of these methods to create
synthesized music from primitive, editable PCM waveforms along with one
fixed-frequency PCM channel, in addition to the YM2149F's square waves in a
form very similar to the Konami and Hudson chips mentioned above.  In total
this provides 7 channels of sound.

Turbochip is named as such because the North American version of the
PC Engine was known as the TurboGrafx-16, and its game cartridges were
called TurboChips.  Also, Hudson Soft who co-developed the PC Engine with
NEC used a bee as their logo (much like the Atari ST's "busy bee" icon).
Furthermore, Atari licensed the precursor to the HuCard/TurboChip known as
the Bee Card for use with the Atari Portfolio handheld computer.

How to use Turbochip
--------------------
If you are familiar with tracker programs, the immediate functions should be
easy to understand.  However, as this is neither a standard sample tracker
nor standard soundchip tracker, there are a few concepts to get used to.

The files and folders that make up Turbochip are as follows:

SND                     samples folder (contains signed 8-bit samples)
TC                      songs folder
TC.PRG                  the editor/player
TCMANUAL.TXT            this file

Double-click TC.PRG in low or medium resolution to launch the program.
After a few moments you will see the Operations page.

Operations page
---------------
This page is used for editing waveforms, loading and erasing samples,
loading and saving songs, erasing patterns, and quitting back to the
desktop.

The required operation is selected using function keys F1 to F4 and
controlled using the keyboard inputs listed below.

F1 - Waveform editor
--------------------
Move to previous waveform                       F5
Move to next waveform                           F6

Move to previous waveform sample byte           Left
Move to next waveform sample byte               Right

Smooth decrement of waveform sample byte value  Down
Smooth increment of waveform sample byte value  Up

Coarse decrement of waveform sample byte value  F7
Coarse increment of waveform sample byte value  F8

Mute any currently previewed waveform           F9
Preview waveform, change octave per press       F10

F2 - Sample loader
------------------
Move to previous sample slot                    F5
Move to next sample slot                        F6

Load sample                                     Up, then Return

(When loading samples of 32K or more, they will be truncated to 32767 bytes)

Erase sample                                    Down, then Return

F3 - Disk operations
--------------------
Load song                                       Up, then Return
Save song                                       Down, then Return

F4 - System operations
----------------------
Erase patterns                                  Up, then Return
Quit to desktop                                 Down, then Return

Switch to Editor page                           Esc

Toggle high-contrast display mode on/off        Space

Editor page
-----------
This page is for entering musical notes and parameter data.  These functions
are carried out using the keyboard inputs listed below.  

Note                    Base octave             Base octave + 1
----                    -----------             ---------------
C                       z                       q
C#                      s                       2
D                       x                       w
D#                      d                       3
E                       c                       e
F                       v                       r
G                       b                       t
G#                      h                       6
A                       n                       y
A#                      j                       7
B                       m                       u

Numerical input
---------------
Hexadecimal values                              0 to F (main keyboard)

Function                                        Main keyboard   Keypad
--------                                        -------------   ------
Move to previous pattern in pattern list        F1              -
Move to next pattern in pattern list            F2              +

Move to previous pattern list page              F3              (n/a)
Move to next pattern list page                  F4              (n/a)

Set selection marker start / select pattern     F6              (
Set selection marker end                        F7              )

(F6 also sets selection marker end to the bottom of the channel.  This is
useful for copying entire channels quickly)

Paste selected notes at cursor, with cut        F8              1
Paste selected notes at cursor, without cut     F9              2
Paste whole pattern                             F10             3

(Paste function provides the following conditions:
1: Notes, effects, and volumes can be pasted between Channels 1 to 6 and in
any pattern
2: Tone/noise parameters are preserved between Channels 1 to 3
3: Wave parameters are preserved between Channels 4 to 6
4: Detune parameters are preserved only within their respective channel
5: PCM sample indexes are preserved only within the PCM channel)

Octave down                                     ;               /
Octave up                                       '               *

Transpose selected notes down                   ,               7
Transpose selected notes up                     .               9

Clear song loop                                 `               0
Set song loop at pattern list cursor position   =               .

Move edit cursor up                             Up              (n/a)
Move edit cursor down                           Down            (n/a)
Move edit cursor left                           Left            (n/a)
Move edit cursor right                          Right           (n/a)

Quick move edit cursor up                       Shift + Up      8
Quick move edit cursor down                     Shift + Down    5
Quick move edit cursor left                     Shift + Left    4
Quick move edit cursor right                    Shift + Right   6

Delete note                                     Delete          (n/a)
Move pattern notes up from cursor position      Backspace       (n/a)
Move pattern notes down from cursor position    Insert          (n/a)

Toggle note scratchpad on/off                   Space           (n/a)

Reset edit/play cursors, move to first pattern  Clr Home        (n/a)

Play song                                       Return          Enter

Switch to Operations page                       Esc             (n/a)

Overview of Editor page
-----------------------
4 1--EVTND  2--EVTND  3--EVTND  4--EVWD  5--EVWD  6--EVWD  7  NF  D  A-12  S  01
1 ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  01
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
2 ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
3 ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
4 ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
5 ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
6 ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
7 ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
8 ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00
  ---00000  ---00000  ---00000  ---0000  ---0000  ---0000  0  00  0  0 00  6  00

"4" in top left         current octave
"1--" etc               channel number
E                       effect number           (0 to F - see table below)
V                       volume                  (0 to F)
T                       tone enable             (YM channels (1 to 3) only) 
N                       noise enable            (YM channels (1 to 3) only)
D                       detune enable
W                       waveform select         (DMA channels (4 to 6) only)
                        (waveforms 9, B, D and F are treated as wavestep
                        effect - explained below)

7                       PCM channel, enter sample index numbers 0 to F

NF                      noise frequency         (YM channels (1 to 3))

D                       global detune value     (0 to 3)

A                       channel select for arpeggiator
1                       number of semitones above base note for first arp
2                       number of semitones above base note for second arp

S                       number of vertical blank periods frames until next
                        tempo change (use value 0 to skip to next pattern)

01                      pattern list column (current pattern is displayed at
                        top)

Channels 1 to 3
---------------
Channels 1 to 3 use the YM2149F square wave to generate sound.  In addition
to setting the volume, you will need to choose whether to use the tone
generator, noise generator, or both.  You can select this by placing a '1'
in the 'T' or 'N' columns.

The volume levels of these channels are logarithmic in relation to each
other.  The position of these channels is in the centre of the stereo field.

Channels 4 to 6
---------------
Channels 4 to 6 use the stereo DAC to play back the 32-byte waveforms as
defined in the Operations page.  The waveform is selected in the 'W' column.
A value of 0 in this column selects a square wave. A value of 1 to 7 selects
any of the waveforms that are stored at these indexes.

Waveforms 8 to F are considered 'special' waveforms.  Any waveform can be
defined here, however by default a pulse-width waveform has been set up in
these locations and a wave-stepping function can be applied in order to
actuate a pulse-width modulation effect on the sound.  Other channel effects
are still available.

The functions selected by a value in the waveform column are as follows:

8               50%-duty square wave
9               fast bounce between waveforms 8 to F
A               37.5%-duty square wave
B               slow bounce between waveforms 8 to F
C               25%-duty square wave
D               fast bounce between waveforms 8 to F, reset on new note
E               12.5%-duty square wave
F               slow bounce between waveforms 8 to F, reset on new note

The volume levels of these channels are linear in relation to each other.
Due to a hardware oversight by the engineers at Atari, the maximum volume of
the DAC channels is lower than that of the YM2149F (cheers guys!!!!!), so
pay attention to this fact when selecting a value for the volume column.

Channels 4 and 6 are positioned in the left of the stereo field, and Channel
5 is positioned in the right.

Channel 7
---------
Channel 7 is for use with the fixed-frequency PCM samples, intended for use
typically with percussion samples but if you wanted to use a sample of
someone saying, for instance, "Hey!", then you can if you want to.  But only
if you want to.  You can use any 8-bit signed sample of 25033Hz.  It is up
to you how you create these sounds.  If you have access to one of those PCs
or Macs that you get then there is a program called Audacity which can do
just the trick.  I developed Turbochip on the Ubuntu operating system, there
is also a version of Audacity for this.  Make sure the filename has '.SND'
as its extension and that it is placed in the 'SND' folder.

The position of this channel in the stereo field is in the right.

Effects
-------
Channels 1 to 6 can also use the effects listed below:

Volume-based effects:
0                       no effect
1                       staccato
2                       attack fast
3                       attack slow
4                       decay fast
5                       decay slow
6                       tremolo fast
7                       tremolo slow

Pitch-based effects:
8                       pitch up fast
9                       pitch up slow
A                       pitch down fast
B                       pitch down slow
C                       vibrato fast
D                       vibrato slow
E                       octave blip
F                       octave blip with decay

Detune
------
To enable detune on Channels 1 to 6, enter '1' in the column.  The depth of
the detune is determined by the value in the 'D' column, which decreases
the pitch of a note by one quarter-semitone per value.

Arpeggio
--------
To enable an arpeggio on Channels 1 to 6, select the channel to apply the
arpeggio to by placing a value in the 'A' column, then in the '1' and '2'
columns enter the number of semitones to offset the base note of the channel
by.  The base note, offset 1, and offset 2 will be cycled on every vertical
blank interrupt.

Playback mode
-------------
F1 to F7                mute/unmute channels 1 to 7
F10                     unmute all channels

Return / Enter          short press: stop song, long press: repeat pattern

Example files
-------------
There are a few demo songs in the TC folder, they are:

BLANK
BONKEND         (cover of PC Genjin/Bonk's Adventure end theme)
FAERIE          (awesome contribution by Dma-Sc)
FRANKIE         (named after baby booby x)
HUEY
NEMESIS         (cover of Nemesis/Gradius stage 1 theme)
PACMAN          (cover of Pac-Mac arcade intro theme)
SWEET           (cover of Johannes Bjerregaard's C64 tune)
TCDEMO          (the first Turbochip tune)

BLANK can be loaded to delete all patterns and samples, and reset all
waveforms back to their default values.

Try loading these files on the Operations page and having a look at them in
the Editor page to get the jist of how things work.

There is a Roland TR-909 sample set in the SND folder which can be loaded on
the Operations page.  The sample names are:

909BD
909BDSD
909CH
909CP
909CR
909HT
909LT
909MT
909OH
909RD
909RS
909SD

There are generic bassdrum and snare samples, they are:

BASSDRUM
SNARE

Conclusion
----------
Be inspired, have fun!

Play Gomola Speed and Bonk's Adventure on the PC Engine when you get the
chance.

Stay cosmic and stay cool, because Dennis Greenidge says so.

Made in Plymouth, UK using
--------------------------
Audacity
bless
gedit
gimp
Hatari
LibreOffice
Sublime Text
vasm

running on Ubuntu 16.04LTS on a Lenovo ThinkPad X230

8x5 font from Sky Soldiers (1988, SNK)
