Inside Antic Music Processor
Do-it-yourself music programming
--all about AMP file structure
By Steven Lashower with Pravin Wagh
Antic Music Processor (AMP) is one of the most powerful music composition tools available for the Atari 8-bit computers. There are some things AMP can't do, however, that could be easily done by BASIC programs using AMP file data. The following article explains the AMP file structure for programmers, who might then write various AMP enhancer programs--for example, a music scoring program that could print out sheet music. Included also is AMP Analyzer, a powerful AMP music file decoder written in Atari BASIC that you can use in your own programs. The latest version of AMP appeared as Antic's July 1989 Super Disk Bonus. At least 48K memory is required to run AMP.
If you've been involved with the Atari 800/XL/XE computers for a few years, you've probably seen music player programs for songs created with Lee Actor's Advanced Music System, or AMS. As AMS plays songs, it shows the notes being played by highlighting the appropriate keys on a piano keyboard onscreen. As interesting as this piano metaphor is, there's still room for improvement.
Having authored several AMS songs, I made up a wish list of features that I would include if I ever wrote my own music program. From day one, I knew I'd have to improve on AMS to get people to take me seriously. I felt that the user interface, the way users interact with the program, must be enhanced. The note entry commands needed to make more sense, as did the player. It also needed to be much faster than AMS. Finally, my music processor would allow something missing from even the most current version of AMS--Iyrics! To accommodate this new visual addition, the piano display would have to go.
The first results of my programming efforts appeared on the December 1988 Antic Disk as Antic Music Processor (AMP). This first release, Version 1.2, had been in the works for more than a year. While the player portion of the program worked as I had planned, the music editor still lacked a way to enter Iyrics. However, six months later AMP 2.0 was released with an editor for Iyric entry.
AMP 2.0 and accompanying article appeared in the June 1989 Antic magazine and disk. A very slightly altered version with a minor bug fix, AMP 2.1, appeared on the August 1989 disk withoutaccompanying instructions.
The beauty of the Atari 8-bit computers lies in their simplicity, and I tried to keep AMP's file structure equally simple. Each data file is divided into four sections: a header, the music data, a trailer, and text for Iyrics. Once you know its structure, the data isn't hard to interpret, or even manipulate.
In the June/July 1990 Antic, Joe Cabuk describes how he cracked the AMP code on his own to create the "Antic Music Transposer and Shifter" programs which ran in that issue. Now you don't need to struggle to interpret all the odd numbers in AMP files. The following tutorial explains exactly how the data is organized within the files. And the AMP Analyzer program demonstrates techniques for reading and interpreting AMP data in your own BASIC programs.
Getting Started
Type in magazine Listing 1, ANALYZE.BAS, check it with TYPO II, and SAVE a copy to disk. If you have trouble typing the special characters in lines 130 and 250, don't type these lines. Instead, type in Listing 2, check it with TYPO II, and SAVE a copy before you run it.
When RUN, this program creates these hard-to-type lines and stores them in a file called LINES.LST. To merge the two programs, type NEW, then LOAD "D:ANALYZE.BAS" and then ENTER "D:LINES.LST". Be sure to SAVE the completed version of the program.
Before you actually RUN the program, you need to put the name of an AMP song file to analyze in line 330, replacing the filename "D:SAMPLE.AMP". AMP Analyzer simply reads the AMP file specified in line 330, translates the data it finds, and gives you some information on the music.
The analyzer doesn't actually do anything to the song--it's up to you to use the various data-reading and translating routines in your own programs. Lots of comments were included to make it easy to see how the program works with the AMP file structures and data.
Headers and Pointers
Every AMP song file starts with a 13-byte header. The first three bytes identify the song, containing either the letters AMP or AMT. Here AMP indicates that the file was originally an AMS I or II song which was converted over to Antic Music Processor format. An AM1 identifier signals that the song has been edited in AMP and may contain Iyric data. All songs saved by Antic Music Processor are given the AM1 identifier, even those that originally had AMP identification bytes.
Bytes four through nine contain three pointers that indicate where the data for each of the Atari's four voices is located. Music for voice 1 starts at the first byte of the music section (the 14th byte of the file). Music data for the second voice follows at the end of all the data for voice 1. Voices 3 and 4 follow in turn. Bytes four through five form a 16-bit number that points to the beginning of the data for voice 2. Bytes six through seven point to data for voice three, and bytes eight and nine do the same for voice 4. Bytes 10-11 point to the beginning of the trailer bytes.
Pointers are also used elsewhere in AMP files, so it's useful to know a little about the way they work. A pointer is simply a number held in two bytes. If you're not used to pointers, the way in which these numbers are arranged can be confusing. In AMP, all points are saved with the low byte first (standard 6502 numeric convention). To figure out the value of a pointer, take the second byte of the pointer and multiply it by 256, then add the result to the value of the first byte. The sum is the pointer value, indicating the number of the byte at which a certain chunk of data begins. In the case of a voice-data pointer, the value tells you at what byte a voice begins, counting from the beginning of the file's music data section--not from the beginning of the file itself.
The last two bytes (12-13) of the header do nothing at present, but that may not always be true. They served as pointers during AMP's early development, and they may be used again in future versions of AMP. To be safe, don't use these bytes for anything.
Music Data
As noted above, the music section of an AMP file has four parts, one for each voice. Everything in the music data works in threes. Each command or note requires three bytes. The data for each voice begins with the hexadecimal numbers $56, $01, $00 and ends with $FF, $FF, $FF.
AMP 2.0 supports six commands. Of the three bytes that make up the command, the first byte is the command itself, and the other two are parameters for the command. The commands are as follows:
Begin New Measure ($56): This command begins a new measure, and the two bytes that follow indicate the measure number (using pointer format). The data for every voice always begins with $56, $01, $00, which simply means "measure #1".
End Voice Data ($FF): The $FF command lets AMP know that it's reached the end of a particular voice. The command repeats twice more just for emphasis, since no additional parameters are needed.
Song Tempo Change ($58): AMP measures tempo arbitrarily, allowing 255 settings from 35 to 290. This setting occupies the byte immediately following the $58. (The third byte of this command is currently unused.) When entering music in the music editor, the lowest tempo allowed is 35, which is stored as $00 in the actual song data. $58, $0F, $00 indicates a tempo of 35 plus $0F, or 35 + 15 = 50 in decimal numbers.
Lyric Advance ($59): This command causes AMP to move to the next marked syllable in the Iyrics. The two bytes that follow are currently not used, but eventually they will probably be used as pointers. (See the Iyric data section for more information on the use of this command.)
Rest ($54): The second byte indicates the duration of the rest (a pause in the music). AMP recognizes any duration from 1 to 255 clocks. Byte three is currently unused.
Notes
Any value in the range from $00 to $41 represents a musical note. The note is followed by two parameters. Both parameters are always used. The first indicates note duration, using the same values as for rests, above.
The second byte defines the note envelope and volume, and is a little trickier to decode:
Bits 0-3 indicate the note volume. Four bits allow a total of 15 volume settings, one being the quietest.
Bits 4-5 define the sound envelope. If both bits are zero, then the default envelope is used. Setting only bit 4 gives a staccato sound, with a fast decay rate. Setting only bit 5 results in a slightly slower decay, and setting both bits results in a tie (no decay).
Bit 6 is currently unused, though in future versions of AMP it might be used to increase the number of envelopes, or even to synchronize graphics with music.
Bit 7 is used for the NOTE X,Y,Z command that was added in AMP 2.0. If bit 7 is set, then the bytes have different meanings. The first byte then represents the distortion (Y) of the note command, and parameter byte 1 represents the pitch (X). By "stripping" off bit 7 from parameter byte 2 (subtracting 128 from whatever value was in that byte) we get the duration value for the note command.
Trailer Bytes
A ten-byte "trailer" follows the end of the music data. Byte 1 holds the song's initial tempo, stored here in the same fashion as in the change tempo command ($58). Bytes 2-3 represent the song's key signature. Byte 3 can be either a 1 or 0, respectively indicating a flat (b) or a sharp (#). Byte 2 holds values from 0 to 7, representing the number of sharps or flats. Bytes 4-5 contain the octave and duration (in clocks) of the last note entered into the editor.
Used once in AMP's paleozoic days, bytes 6-7 are no longer of any importance. Byte 8 can contain one of the following characters: #, F, or a "null character" representing the accidental (sharp, flat, or natural) of the last note entered. Bytes 9-10 form a pointer which contains the length of the fourth section of the music file, the Iyric data. Byte 11 is reserved for future expansion.
Lyric Data
Directly following the header is the fourth section of the AMP data file, the section containing Iyric data. This section is divided into individual lines, each line containing exactly twenty characters. The Lyric Advance command ($59) is used to display Iyrics. Lower case or inverse characters are used to separate each Iyric line into syllables. (Actually, any character with an ASCII code greater than 96 can be used.) The $59 command causes the next syllable in line to be highlighted. Once all the syllables in a line have been highlighted, AMP displays the next line of Iyrics and the whole process repeats.
Important Note: Due to the way the AMP Music Editor was set up, the length (in bytes) of the Iyrics must be a number that divides evenly by three. Remember, everything in AMP is done in groups of three! If necessary, this section is padded with the $FF command, added after the Iyrics to adhere to this "rule of three."
Analyzer Program
If some of this information seems hard to understand, don't despair! This file structure grew as AMP developed and it is rather compressed and complicated. Fortunately, the AMP Analyzer can read all this data for you, and display the translated data onscreen. If you're at all familiar with BASIC, you should be able to follow the program and see how it works--how to read the right bytes in the right order, and so on. All you need to do then is use the various routines in your own program.
If you're trying to analyze very large files, you're going to run out of memory. As written, the program reads in all four voices before starting to analyze them. One way to get around the memory limit would be to modify the program to read in only one voice at a time. If you only need a little more memory, using ICD's BASIC XL with DOS XL would give you an extra 8K of programming space.
Steven Lashower studies Communications and Computer Science at California State University, Fullerton and works at Disneyland.
Pravin Wagh has a B.S. in Biology and is currently studying Computer Science at the University of California, Los Angeles. Pravin and Steven have been programming together for over five years.
Listing 1 8bit/ANALYZE.BAS Download
Listing 2 LINES.BAS (not needed)