file_id.diz
-----------------------------------------------------------------------
CCCC HH HH IIIIII PPPPPP NN NN SSSSS FFFFFFF XX XX
CC CC HH HH II PP PP NNN NN SS SS FF F XX XX
CC HH HH II PP PP NNNN NN SS FF F XXX
CC HHHHHH II PPPPP NN NNNN SSSSS FFFF XXX
CC HH HH II PP NN NNN SS FF F XX XX
CC CC HH HH II PP NN NNN SS SS FF XX XX
CCCC HH HH IIIIII PPPP NN NN SSSSS FFFF XX XX
CHIPNSFX, cross-platform lightweight music tracker and player
developed by Cesar Nicolas Gonzalez / CNGSOFT
website http://cngsoft.no-ip.org/chipnsfx.htm
-----------------------------------------------------------------------
0.- Index
=========
1.- Copyright and warranty
2.- What is CHIPNSFX?
3.- Requirements and setup
4.- Using the tracker
5.- Using the player
A.- Version history
1.- Copyright and warranty
==========================
CHIPNSFX was developed by me, Cesar Nicolas Gonzalez (CNGSOFT).
CHIPNSFX is freeware. Shareware distributors can distribute it if they
only take fee for copying. Software and documentation are provided "as
is" with no warranty.
CHIPNSFX is not public domain. I retain the copyright, although I plan
to switch to GPL in the future if I manage to meet certain conditions.
2.- What is CHIPNSFX?
=====================
CHIPNSFX is a software suite whose purpose is to let the user write
music to be played on 1980s 8-bit platforms based on the Z80 processor
and three-channel, white-noise sound generators such as the AY-3-8910
and YM2149 chips. This spans several platforms: Amstrad CPC, Sinclair
Spectrum 128, MSX1, Sega Master System... In theory other platforms
such as the Commodore 64 would be supported as well.
The suite is divided in two halves: on one hand, CHIPNSFX.EXE, the
tracker, a Win32 console application that handles both the writing of
the music and the generation of binary data to be used by the player;
on the other hand, CHIPNSFX.I80, the player, a Z80 library to be used
by games and demos requiring a tiny code size (between 600 and 800
bytes) while still allowing for sound effects such as amplitude and
noise envelopes and effects, chord arpeggios and note vibratos.
The suite also includes several songs written with the tracker and a
simple jukebox for Amstrad CPC as an example of how to use the player.
3.- Requirements and setup
==========================
The tracker requires Windows 2000 or later to work. A sound card is
optional if the tracker is used as a data generator for the player.
The player is written for the Z80 assembler AS80, although modifying
it for other assemblers such as MAXAM shouldn't be too difficut.
4.- Using the tracker
=====================
The tracker can run in two modes: data generator and tracker proper.
The first mode is limited to translating a song into raw data for the
player: it's thus to be used within batch processing, Makefile scripts
and other command-line activities. By default, it simply takes two
command line parameters, the first one being the source song CHP file,
the second one being the target INCLUDE file. Several command line
options let the user fine-tune its behavior:
* -l STRING: sets the prefix of the data within the INCLUDE file. For
example, "-l xyz_" means that the three channels are labelled "xyz_a",
"xyz_b" and "xyz_c" respectively.
* -c N: sets the INCLUDE file maximum width in characters (default 80)
just in case the assembler cannot accept overly long lines.
* -b: forbids long calls within the song. Use it if the song is small,
it will save further space by using short calls. Using it on big songs
will lead to the assembler complaining about byte field overflows.
* -r: forbids loops. Loops are used to compress the song when strings
of identical notes are detected, but they make data generation slower
and also make playback slightly slower.
* -w: export full song into a target WAVE file.
* -W: export song loop into a target WAVE file.
The second mode enables the tracker proper and is run with either no
command line parameters or with only one, the song CHP file. It allows
two options: -p (start playing the song after loading it) and -m
(mute mode, don't use the sound card at all)
The tracker proper is similar to other musical editors. The general
idea is to define the songs as fragments (the "patterns") arranged on
an ordered list (the "orders") and type the notes on these fragments
as instances of sound wave styles (the "instruments").
The screen layout is divided in five panels: a narrow header (song
title and description), a body divided in three columns (current
pattern, instruments, order list) and a narrow footer (song parameters
and runtime information).
Navigation is to be done with the keyboard, either with Control+Tab or
Control+I to switch to the next panel (Control+Shift+Tab or Control+H
switch to the past panel) or with single keypresses: F2 enables the
pattern panel, F3 enables the instrument panel, F4 enables the order
list panel and F9 enables the parameter panel.
The arrow keys ("cursors") let the user move within a single panel.
In the panels where area selection is possible, Shift+Cursor lets the
user define the span of the currently selected area. Tab, Shift+Tab,
Home, End, Page Up and Page Down allow for faster motion.
The currently loaded song can be played by pressing F5 (whole song
from the beginnign), F6 (current pattern only) and F7 (whole song from
the current location). F8 stops the playback.
F1 shows a simple help screen with the keyboard shortcut list:
* Numberpad + goes to the next order in the order list.
* Numberpad - goes to the past order.
* Numberpad * or Control+Right select the next octave.
* Numberpad / or Control+Left select the past octave.
* > or Control+Down select the next instrument.
* < or Control+Up select the past instrument.
* SPACE either assigns the currently selected instrument to the note
below the cursor (if the pattern panel is active) or plays the note A4
(440 Hz) with the current instrument (if it's the instrument panel).
* ENTER either selects the instrument used by the note below the
cursor (pattern panel) or plays a noise-only version of the current
instrument (instrument panel).
* The letters and numbers in the keyboard either write notes on the
pattern (pattern panel), modify the name and the values of the
instrument (instrument panel) or modify the pattern indices in the
order list (order list panel). As in other trackers, notes are set
on the keyboard as if it were a piano: thus ZXCVBNMQ would play
the eight major notes of the currently active octave.
* Control+F1 enables all playback channels at once; Control+F2 toggles
channel A, Control+F3 toggles channel B and Control+F4 toggles channel
C. Pressing Control+Shift rather than just Control makes the channel
play solo.
* Control+Q and Control+A raise and lower the currently selected notes
(pattern panel) or the currently selected patterns (order list panel)
by a semitone. Pressing Control+Shift rather than just Control raises
or lowers said notes and patterns by a whole octave.
* Control+T and Control+G shift the active notes, instrument or orders
up and down within their lists. Use them to fix mistakes while writing
the notes, to rearrange the instruments or the pattern order, etc.
* Control+K sets the end of the current pattern, the last instrument
or the last pattern in the song at the current panel cursor's
position. By default all patterns grow to accomodate notes as the user
types them, so this can be used to trim patterns that grew longer than
they should. It's also to be used to amend inconsistences when
rearranging patterns within the order list window: inconsistent
pattern lengths are tagged with "!!" in the order list, and using this
shortcut in the right location in the pattern panel will solve said
inconsistency. Data outside the boundaries set by Control+K isn't
saved, so use it to get rid of unused instruments and patterns. Bear
in mind that patterns can be up to 96 notes long, there can be up to
255 different instruments and songs can be up to 256 patterns long.
* Control-L sets the looping point in the song, or resets if pressed
two times. A song that plays its last pattern can either loop to the
pattern pointed by Control-L (tagged in the order list with "**") or
stop if no looping point was set.
* Control-Z and Control-Y undo and redo the last change in the song.
* Control+X, Control-C and Control-V cut, copy and paste respectively
areas previously selected by the user. Control-P pastes data too, but
also moves to the end of the pasted area, effectively allowing for
repeated appending of pasted data.
* Control+N erases the currently loaded song from memory; it will ask
the user for confirmation ("Are you sure? [Y/N]"), who will push
ENTER or Y to accept or ESCAPE or N to cancel.
* Control+O loads a song from disc. It may ask for confirmation if
the current song was edited but not saved yet. A simple user interface
will let the user look for the song to be loaded: ENTER accepts the
song file under the cursor and ESCAPE cancels the loading.
* Control+R reloads the current song from disc. Confirmation will be
requested if any edits have been done.
* Control+S saves the song to disc. The user interface lets the user
select the song (by default, the last one saved or loaded) or enter
a new filename by choosing the last entry in the list, "<new file>".
* ESCAPE quits the tracker. It requests confirmation, especially if
the song was modified but not saved.
The pattern panel allows for certain special notes to be written:
* . clears the current note.
* 1 inserts a rest, shown as "^^^".
* L inserts a noise-only note, shown as "C-B".
The instrument panel defines data with eleven hexadecimal fields:
* The first two digits are the starting amplitude: FF is the maximum
level, 01 is the minimum level that still plays a note. 00 disables
the note altogether.
* The next two digits are the amplitude envelope: 00 keeps the
amplitude constant, the range 01 to 6F makes the amplitude rise as
time goes on (01: slowly; 6F: quickly), the range 70 to 7F makes the
amplitude drop once (70: strong drop; 7F: weak drop), 80 sets a simple
tremolo effect (amplitude rises and falls in a loop), the range 81 to
8F makes the amplitude rise once (81: weak rise; 8F: strong rise), and
the range 90 to FF makes the amplitude drop as time goes on (90:
quickly; FF: slowly).
* The following two digits are the starting noise value: 00 means no
noise, 01 means high-pitched noise, and FF means low-pitched noise.
* Similarly, these two digits are followed by two more digits that
define the noise envelope: 00 keeps the noise constant, the range 01
to 7F makes its pitch drop as time goes on (01 very slowly, 7F very
quickly), and the range 80 to FF makes it rise as time goes on (80
quickly, FF slowly).
* The last three digits set the sound effect. The first out of these
three can be either 0 (arpeggio) or 1 (vibrato), while the last two
digits set the sound effect parameter XY:
The arpeggio's X and Y set the distances in semitones between
the first and second notes and the second and third notes,
respectively. When Y is 0 the arpeggio is 2-step rather than
3-step. For example, XY 47 stands for the C major triad.
The vibrato's X sets its speed (1 fastest, F slowest) while Y
sets its depth (1 weakest, F strongest).
Instrument 00 is special because it sets a simple portamento onto the
notes it's used with: for example, "C-4 01 ... D-4 00" starts a new
note (C4) with instrument #01, then raises its frequency to D4 without
resetting the wave style.
Indices in the order list panel are hexadecimal numbers.
Values in the parameter panel can be modified as follows:
* Insert and Delete increase and decrease respectively the clock base
(25 Hz, 50 Hz, 100 Hz). Higher bases allow for more definition in the
song, but are more burdensome for the player.
* Up and Down increase and decrease respectively the clock divider.
The higher the divider, the slower the song.
* Right and Left increase and decrease respectively the transposition
in semioctaves. The higher the transposition, the sharper the song.
The song title can be edited with F11, and the description with F12.
5.- Using the player
====================
The player is hardware-independent: it modifies the Z80 registers AF,
BC, DE, HL and IX, but it's otherwise interruption and stack safe, as
it doesn't modify AF', BC', DE' or HL', or the interrupt status.
The player expects the user to provide some information:
* "chipnsfx" is the location of the player itself. It's required if
the code needs to relocate itself before the player starts running.
When no relocation is needed, the user only has to put the label
"chipnsfx" right before the player code.
* "writepsg" is a function that begins with PUSH BC, writes the value
of register A onto the sound chip register defined by C, then ends
with POP BC and RET. For example, a Spectrum 128 "writepsg" function
could be like this:
PUSH BC
PUSH AF
LD A,C
LD BC,$FFFD
OUT (C),A
POP AF
LD B,$BF
OUT (C),A
POP AF
POP BC
RET
* "chipnsfx_bss" points to a buffer; its required length is the
constant CHIPNSFX_TOTAL, whose value depends on the compile time flag.
* "CHIPNSFX_FLAG" is the compile time flag, a number whose bits set
the options of the player itself:
+1 : notes from Spectrum 128 and MSX1 rather than Amstrad CPC.
+2 : dual mode: each channel is divided in two (music and SFX)
and if the SFX half is active the music half stays active but
quiet, thus allowing for sound effects to temporarily override
the background music. The downside is that the player is doing
the work of six channels rather than three, thus requiring
twice as much buffer memory and CPU time.
+4 : extended mode: enables portamentos and tremolos, at the
cost of making the player longer and heavier.
+8 : no noise: disables noise support and makes the player
shorter and lighter.
+64 : linear amplitude: simulates linear amplitudes instead of
using on the exponential amplitudes from the sound chips.
+128 : precalculated octaves: the player becomes faster as
notes are no longer calculated on the fly, but grows heavier.
The player provides four functions:
* "chip_stop" resets the sound chip and all the playback parameters.
The user must use it at least once before playing anything at all, and
whenver he may need to stop the playback. Registers AF, BC, DE and HL
are modified by this function.
* "chip_song" sets all playback channels to point at the beginning of
a song. HL points at the song header, whose format is as follows:
DW channel_a-$-2
DW channel_b-$-2
DW channel_c-$-2
The macro CHIP_HDR can be used instead:
CHIP_HDR channel_a,channel_b,channel_c
If the player was compiled with the dual mode on, the Carry flag sets
whether the new song is background music (NC) or a sound effect (C).
AF, BC, DE and HL are modified.
* "chip_chan" sets a channel to point at the beginning of a track. DE
points at the track offset and A stands for the channel, ranging from
0 (channel A SFX) to 5 (channel C music) if dual mode is on, or from
0 (channel A) to 2 (channel C) if it's off. Registers AF, BC and HL
are modified.
* "chip_play" plays one tick of the current playback. It updates the
playback channels and the sound hardware accordingly. A 100 Hz song
requires this function to be called 100 times every second, a 50 Hz
song requires it to be called 50 times, and so on. Registers AF, BC,
DE, HL and IX are modified.
The playback parameters can be examined by the user on runtime. For
example, the user may need to know whether channels A and B are busy:
LD IX,chipnsfx_bss
LD A,(IX+CHIPNSFX_POS_L)
OR (IX+CHIPNSFX_POS_H)
JR NZ,channel_a_is_busy
; channel A is not busy
LD IX,chipnsfx_bss+CHIPNSFX_BYTES
LD A,(IX+CHIPNSFX_POS_L)
OR (IX+CHIPNSFX_POS_H)
JR NZ,channel_b_is_busy
; neither channel A or B are busy
CHIPNSFX.DSK is a jukebox, a very simple demo of the player at work.
The time spent by the player is shown as as a white stripe on a black
border. Press SPACE to stop the current song and play the next one.
A.- Version history
===================
2017-05-13: first public release.
-----------------------------------------------------------------------