Learn Multi platform Z80 Assembly
Programming... With Vampires!
ChibiSound PRO / ChibiTracks / ChibiTracker PRO!
ChibiSound PRO, ChibiTracks,
ChibiTracker PRO - The Unholy Trinity!
the huge number of platforms and CPU's I cover, I had a bit of a
problem! In the past I had done simple sounds with my
multiplatform 'Chibisound' driver, and music with the AY based
'Arkostracker'... but while I had managed to write AY wrappers to
allow it to play on some extra Z80 systems, it was too complex for
me to realistically port to more platforms.
solution I came up with was to develop my own music software from
ChibiSound PRO is the platform specific
sound driver, it handles making consistent pitched tones and noise
effects on the hardware.
ChibiTracks is the player, it works
currently on Z80, GBZ80, 6502 and 68000, however it is simple
enough to be ported to other systems, and such ports are likely!
ChibiTracks is designed for simple music and provides a multiplatform
solution to play a single compiled music binary file on multiple
ChibiTracks is NOT designed to provide advanced features comparable to
solutions like ArkosTracker
To understand how ChibiTracks works, lets look at all the components:
ChibiSound is the sound driver that handles the particularities of a
system, there is typically one driver per system, though the CPC and MSX
drivers are essentially identical except for the AY register setting
The original 'ChibiSound' gave us one channel, one
Volume bit, six pitch bits, and the ability to turn noise on. Pitches
were not matched across systems, so sound 32 won't sound the same on all
The updated 'ChibiSound Pro' gives us all the channels
provided by the hardware, 8 volume bits, 16 pitch bits, and the ability
to turn noise on. Pitches were not matched across systems, however the
'ChibiOctave' lookup table provides values which ARE matched across all
ChibiSound PRO is essentially a reduced subset of AY functionality, and
was designed on the Z80 - it's 'PRO' suffix is a parody of the
'SoundBlaster PRO' - which could only do 8 bit sound so wasn't up to
professional standards! (neither is ChibiSound PRO)
ChibiSound PRO provides a standard interface to the underlying
hardware, it allows the following features to be set for each channel on
the underlying hardware:
|Channel Number (bit 0-6)
Noise On/Off (bit 7)
||Multiple channels can be supported, but on single channel
systems only Channel 0 will be sure to play.
If possible Channel 0 will be a center channel, Channels 1+ may be
Noise bit turns the noise effect on (1) or off (0) - this can be
set on any channel, if the underlying hardware only supports one
noise channel, this will be resolved by the driver.
||Set volume of the channel (0-255). Higher numbers are louder. O
||Set the pitch of the channel (0-65535). Higher numbers are
Using DE does not standardize the resulting pitch - however a
'Lookup table' of notes 'ChibiOctave' provides a standardized way
of getting the correct DE value to get a pitch correct note on the
Chibisound PRO does not offer features like Envelope, LFE etc, as
providing consistent functionality across different platforms would not
ChibiTracks is the player for music files.
A Song contains multiple Channels (Currently tested
A Channel takes it's commands from a Sequence of
Patterns contains a set of lines. Each of the lines contain a sequence of one or more commands, and a delay to
wait until the next line.
Channels also play instruments (usually started by
the pattern). These are also a sequence of commands and delays, and are
used to set ChibiSound settings for the playing sound. A channel will
stop making a sound when an instrument ends (unless it loops)
It is important to note that functionally Patterns
and Instrument command lines are identical - they are
literally processed by the same code in ChibiTracks, however it would
not make sense to
ChibiTracker PRO can output two kinds of file - a binary file (.CBT)
which can be used with any player, or an ASM file - the default format
used to save and reload files (.ASM) - This is a VASM/MAXAM compatible
Z80 ASM file which contains all the binary data in DB/DW lines, and all
extra data for the player in rem statements (Starting with a semicolon).
There should be no difference between an compiled ASM and a binary CBT
There are two optional functions which can be enabled (but make the
ChibiTracks_AllowRelocation - This
allows a song to be played from a different address than it was built,
For example if a CBT binary was a save address of &4000, it can be
loaded and played from address &8000 provided this function is
This function is mandatory on 68000, as only 16 bit addresses are
specified in the binary files.
ChibiTracks_AllowSpeedChange - This
allows the speed of songs to be changed via the 'SongSpeed' function -
allowing songs to be sped up or slowed down on playback at the cost of a
slightly slower and bigger player - Alternatively you can save with the
'PreMultiply Song Speed' option - in which case it's not needed.
ChibiTracks - A song file!
Lets take a look at the ASM file to see how ChibiTracks works.
|At the start of the ASM file is the 'ChibiTracker' block
These lines all appear as comments in the ASM file, but are
functional lines to ChibiTracker PRO.
These define settings and data that are used by the editor, but
are not needed by the ChibiTracks player - because they are in REM
statements, they will not be contained in any built file.
|Next is the binary header - this is used by ChibiTracks
player.... All 16 bit addresses are in Little Endian (even on
This contains the channel count (Should always
be 3 at this stage as the player does not support more)
Repeatpoint is the entry number in the sequence
which the song should restart when it reaches the end.
Songspeed is the multiplier for the line delay,
A delay of 2 with a song speed of 5 would wait 10x interrupts
before moving to the next line. NOTE: it is possible to assemble
the player without songspeed support (ChibiTracks_AllowSpeedChange
not defined). You can still get the same result by saving with
'Premultiplied songspeed' option enabled in ChibiTracker
PatternList is a pointer to the pattern list
table. This list appears at the end of the ASM file
InstrumentList is a pointer to the Instrument
list table. This list appears at the end of the ASM file
There then follows one 16 bit address for each channel, which
points to the sequence of patterns for that channel.
|The Sequences define the pattern numbers that make up the
song. These are looked up in the PatternList table.
Patten 255 represents the end of the song, at which play will
resume at the repeatpoint.
|Here are two sample patterns.
Each line in the ASM file is a line of the pattern. Lets take a
look at one!
first is the length of the delay after
this line before the next line is processed. 2 means 2*Songspeed
ticks until the next line.
There then follows a sequence of commands
to be processed by ChibiTracks.
&0D means set pitch to note &3A
&0B means play instrument &01
&00 is the 'End of commands'
command, the player will wait until the delay finishes before
processing the next line
Line 33 of the first pattern just has the 'End
of pattern' command &10 - This tells the player to
move to the next pattern in sequence - The delay has no effect in
|Instruments are in the exact same format, and use the exact same
decoding routine of the player.
However!... a instrument should end with a delay of 0, at which
point the instrument will stop sounding.
it is also possible to loop an instrument with a loop (Byte
&0C, followed by a negative byte), the byte value will be
added (subtracted) from the current position in the command
sequence, effectively looping part of the sequence.
To stop such a loop, a silent instrument, or other instrument
should be played on the channel to stop the looping one.
|At the end of the song data is the PatternList and
These are a table of little endian 16 bit addresses of the pattern
and instrument command sequences.
ChibiTracks - Byte commands
There are two types of command in ChibiTracks.
One Byte commands have the command number in the high nibble, and the 4
bit parameter in the bottom nibble, For Example
&F1: &F_ = Shift
volume &_1= Volume up 1
Two Byte commands have a second byte parameter, their top nibble is
always Zero, For Example &0E,&FF: &0E =
Set Volume &FF= New Volume
|Vol shift -8 to +7
|Pitch shift down 0 to -15
|Pitch shift up 0 to +15
||Noise state x (1=on 0=off)
|End of Pattern
||Pitch to x
||Vol to x
||Note to x (Even=true pitch Odd = Flat/Sharp)
||Loop to Offset -0 to -255 bytes (eg &FF = back 1 byte)
||Play Instrument x
||Reserved for you to add custom functionality to the player!
(Named in ChibiTracker IXH IXL IYH IYL)
Top Nibble commands: &B0 A0 90 80 70 60 50 40 30 20 spare!
Two Byte Commands: &0A 09 08 07 06 05 04 03 02 01 spare!
ChibiTracker PRO is a DotNet 3.5 application.
It requires SlimDX (SlimDX
Runtime .NET 2.0 (January 2012).msi or SlimDX
SDK (January 2012).msi), which is used for the sound buffer.
ChibiTracker supports a variety of MIDI controllers where available.
|This is the instrument list.
It's used to select an instrument to enter into the pattern when
It's also used to select the edited instrument in the instrument
|This is the sequence list, it
defines the patterns played in the song.
Each column is a different channel, each row is a pattern to play
at that point.
You can change the selected pattern at a point by double clicking,
and selecting a new pattern from the list.
|This is the Play controls and
The play controls allow for start, stop, looping and edit of the
The Status line shows the byte data produced by the player, and
MIDI data received from the controller when connected.
|This is the Pattern editor.
each column is a different channel.
When in 'Edit Mode' (purple background) the pattern can be edited.
Space - Toggle edit mode
letter / num keys - note keys.
Num0 - Num9 - Drum (when editing) / Select instrument 0-9
Backspace - clear line
Insert - Add line
Delete - Remove line
F1 - Restart Play
F2 - Resume Play
F3 - Pattern Loop
F4 - Stop
F8 - Octave down
F9 - Octave up
F9 - Set Volume
F10 - Set Pitch
|This is the instrument editor...
it's rather basic at the moment!
A line of the instrument can be selected in the top list.
The Command / events for that line can be altered in the bottom
The data in the top list is in the format:
Delay (byte count) Commands........
|This is the settings page. It
allows various changes.
Song Settings define options of the edited song.
Editor settings change how the editor works, if
you're getting 'clicking' or poor performance, you can try
Midi Controller Allows you to connect a Midi
Controller such as a piano type keyboard.
|This is the pattern list.
You can double click on a pattern to rename it - This is optional,
and is just to allow you to organize your song more easilly
|This is the Info Panel.
It shows some help info by default, and may show debug information
in some special cases.
|This is the Midi Editor.
This only appears if you connect a midi device.
This allows you to map buttons and dials to ChibiTracker events.
Of course A keyboard can also be used to set notes in the pattern!
State Memory, symbols, and the silent instrument
|ChibiTracks uses a 16 byte
block to keep track of each of the channels (16*3=48 bytes total)
These contain the values to be passed to the ChibiSound PRO
There are address pointers for the playing Instrument Line and
Pattern Line, as well as 'Timeouts' after which the next line must
There is also an address for the sequence position - this has no
timeout, as the next sequence is loaded when the playing pattern
ChibiTracks will zero and initialize the memory it is provided for
its channel data. Instrument/Pattern/Sequence data are loaded from
the playing song.
There are EQU definitions which are used as offsets to the
corresponding data for a channel
|Some Extra EQU definitions point to the start of the channels,
and the end of the data block
|When a channel ends it must be switched to a 'silent instrument'
- this is an instrument script which only sets the channel volume
is designed to work from ROM, so the variables for channels and
other core purposes can be loaded in a small block of RAM.
In addition to the 48 bytes here there are aso : SongOffset
(word),SongBase (word), Instrumentlist (word), Patternlist
(word), SongChannels (byte),SongSpeed (byte) and RepPoint
So ChibiTracks needs less than 64 bytes RAM total!
ChibiSound PRO may need a few more though - depending on the