----------------------------------------------------------------------- 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. The tracker will try using a sound card to play songs unless told not to. The player is written for the Z80 assembler AS80, although modifying it for other assemblers such as MAXAM shouldn't be difficult. 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: generate song with short calls. By default, songs are generated with long calls: they're heavier but compatible. If a song is small enough, short calls can save further space. Songs too big for short calls will cause overflow errors when assembling their INCLUDE files. * -b1, -b2, -b3: like -b, but for just one channel (A, B or C), if one or two channels are short enough to benefit from -b but the others are too long for -b to work correctly. * -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 WAVE file target. * -W: export song loop into a WAVE file target. * -y: export full song into a YM3b file target. * -Y: export song loop into a YM3b file target. * -F: set playback quality to 48000 Hz rather than the default 44100. * -L: use linear amplitude rather than the default exponential. It can be useful in songs requiring very gradual crescendos. See below "Using the player", compile time CHIPNSFX_FLAG value +64. 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 the perviously seen options -F and -L plus the following ones: * -p: start playing the song after loading it. * -m: mute mode, don't use the sound card at all. * -P: cursor follows playback. * -k STR: set custom key map. By default, the tracker assumes a QWERTY keyboard, i.e. "-k zsxdcvgbhnjmq2w3er5t6y7ui9o0pl1." * -k1: set QWERTZ key map, a shortcut to the longer and cumbersome "-k ysxdcvgbhnjmq2w3er5t6z7ui9o0pl1." that switches Y and Z. * -k2: set AZERTY key map. 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 all 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. 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-D detects whether the current instrument is used or not (instrument panel) or whether the current pattern is a duplicate of another one (pattern and order list panels). Control-Shift rather than just Control erases the current instrument (if unused) or turns the current pattern into a link to another one (if a duplicate). * Control-E is the opposite operation of Control-D and checks whether the current pattern is a link. Control-Shift rather than just Control turns the link into a new pattern with equivalent contents. * Control-W applies the current pattern's transposition to its notes, then sets the transposition value to zero. Links to this pattern are carefully adjusted in the order list to ensure consistency. * 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 or silence, 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 5F makes the amplitude rise as time goes on (01: slowly; 5F: quickly), the range 60 to 7F makes the amplitude drop or rise once (60: weak rise; 6F: strong rise; 70: strong drop; 7F: weak drop), the range 80 to 9F sets a simple tremolo effect, i.e. amplitude drops and rises in a loop (80: weak rise+drop; 8F: strong rise+drop; 90: strong drop+rise; 9F: weak drop+rise) and the range A0 to FF makes the amplitude drop as time goes on (A0: 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 value F is a special case: it stands for -12 and, if used as Y, also stops the arpeggio; for example, XY=0F stands for the arpeggio +0 +0 -12 -12 -12 -12 -12 -12 -12... while XY=FC stands for +0 -12 +12 0 -12 +12 0 -12 +12... + 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 the default 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 whenever 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. The source code of the jukebox is the file CHIPNSFX.S80. A.- Version history =================== 2017-05-13: first public release. 2017-05-23: second public release. New command line options -F (48000 Hz) and -L (linear amplitude). A blue bar makes the active items stand out. Minor changes in the documentation file. 2017-06-02: third public release. New command line options -P (cursor follows playback), -k1, -k2 and -k STR (set QWERTZ, AZERTY or custom keyboard map), following a suggestion from Beb. 2017-06-07: fourth public release. New command Control-D tells whether the current instrument is unused or the current pattern is a duplicate (Shift: erase unused instrument, turn current pattern into a link to the pattern it is a duplicate of). Minor bugfixes: inconsistencies in -P mode and in channel toggling, better compression when generating INCLUDE files, etc. Minor changes in several songs. New DESPERA1.CHP. 2017-06-16: fifth public release. Fixed a file dialog bug reported by Garvalf (who also wrote CHIPNSFX's first new song from scratch), as well as minor internal consistency bugs. Pattern panel allows using Control-D. New ATOMINO3.CHP and DESPERA2.CHP. 2017-07-07: sixth public release. New command line options -y and -Y (generate YM3 file, either full song or song loop), commands Control-W (apply transposition to current pattern), Control-D (detect duplicates and optionally erase them), Control-E (check for duplicates and optionally create them). Minor changes in CHIPNSFX.I80 extended mode vibratos, in the file dialog and the INCLUDE file compression. New DEFLEKTR.CHP, GRANGEHL.CHP, PHANTIS1.CHP, PHANTIS2.CHP, THINGBBK.CHP and TIMETRAX.CHP. 2017-07-19: seventh public release. New extended tremolos (60-9F) lead to several changes in the amplitude effect byte: old 60-6F become 5F, old 80 becomes 9E, old 81-8F become 61-6F, old 90-9F become A0; 70-7F stay the same. New command line options -b1, -b2 and -b3. Minor tweaks in CHIPNSFX.I80. New CATABALL.CHP, FREDDY_H.CHP, HYDROFOL.CHP and SCOR3020.CHP. 2017-07-24: eighth public release. Fixed a serious bug in the noise generator: playback and WAVE output randomly skipped pure noise notes. New ATEAM.CHP, BURNINR1.CHP, BURNINR4.CHP, SOLOMON2.CHP, UNDERWTR.CHP, WESTBNK1.CHP, WESTBNK2.CHP and WINGSOD4.CHP: 32 sample songs. 2017-07-31: ninth public release. New special case for arpeggios: the nibble F stands for -12 and changes the loop behavior. Sound playback is now wavelength-based rather than frequency-based, and thus closer to the hardware. Minor bugfixes in the keyboard map handling. Added CHUBBYGR.CHP, CHUBBYGS.CHP, MEGAPHNX.CHP and MEGAPHNY.CHP. -----------------------------------------------------------------------