MUSIC SEQUENCE MAKER Program Documentation Version 1.0 May 1989 (c) 1989 Paul Gauthier Introduction --------------------------------------------------------- The Music Sequence Maker is a IIgs utility for programmers who want to add musical scores to their programs. With it, a programmer can convert any Music Studio song file to a "Sequence" file in a format that can be played directly by the IIgs Note Sequencer tool set under interrupt control. This lets a program start a complex multi-instrument musical piece, then go off and do whatever the program has to do while the music plays in the background. The Music Sequence Maker needs a IIgs with 768K and a mouse. The Note Sequencer (tool set 26) is a set of tools that plays a sequence - a data structure that contains information about notes to play. The notes are actually played by the Note Synthesizer toolset with assistance from the Sound Manager toolset. The beauty of the Note Sequencer is that it handles all the details of reading through a sequence and making the appropriate calls to the Note Synthesizer IN THE BACKGROUND with no assistance from your program other than to start the sequence with a call to StartSeq with a pointer to the memory area containing the sequence. This frees your program to do other things while a musical piece plays in the background. You can pause and continue a sequence and change it's tempo. You can even single step the music if you want. One feature lacking from the Note Sequencer is the ability to create sequence data sets. That's where The Music Sequence Maker comes in. You can use a full-featured music entry program, like Music Studio, to enter the music you want to play, or download one of the many public domain songs from Applelink or from other networks, then convert the Music Studio song file to a sequence file. All that's left is for your program to load the sequence file into memory and start it up when you want it to play. You can learn all the intricate details of the Note Sequencer calls and data structures from chapter 13 of the Apple IIgs Toolbox Reference Update (currently available only from APDA) and figure out how to write code to control the Note Sequencer. Or, you can just use the source code from the accompanying program PlaySeq. PlaySeq contains a desktop application that can load any sequence file from disk, play it, pause and continue it, and change its tempo. The source code is provided in APW C and TML Pascal (both the APW version and the stand-alone version.) The APW C version is compatible with ORCA/C. At the end of this documentation you'll find out how to get the source code for the PlaySeq program. How To Use the Sequence Maker Program -------------------------------- Step 1. Start the Music Sequence Maker program and load a song file from disk. Any Music Studio song file can be loaded. You can play the song file to make sure it's the one you want. Step 2. Convert the song file to a sequence. The sequence is placed in memory. You can play the sequence before saving it to disk. Step 3. Save the sequence to disk. Three files are saved: YourFileName.SEQ - The sequence file with the notes. YourFileName.INS - The instrument definition file. YourFileName.WVE - The sound waveforms file. Other Features of the Music Sequence Maker --------------------------- - Load and play sequence files directly without converting. - Load and play digitized sound files. Vary playback rate & vol. - Utility functions: delete/rename/copy files. - File Type Changer function. Anatomy of a Sequence ------------------------------------------------ As mentioned above, when you save a sequence the program outputs three files that contain all the information needed to play the song from your program and make it sound just like Music Studio. The sequence file (.SEQ) contains the notes (semitone, instrument number, velocity or volume, and duration) along with the name of the file containing the instrument definitions. The instrument file (.INS) contains the instrument data structure that the Note Sequencer tool set needs to play the notes. The instrument numbers in the sequence file correspond to instrument definitions in the instrument file. Things like vibrato depth and speed, envelope, and pointers to sounds in the waveform file are included in the instrument file. The waveform file (.WVE) contains a straight copy of what needs to be in the DOC RAM when the song file is playing. The instrument waveforms are stored in this file and are referenced by pointers in the instrument file. The data formats for all three files are described in the text file "Seq.File.Format" in this package. Also, the three files can be loaded and played by the PlaySeq program (see below for source code offers.) Warning About Repeat Sections ---------------------------------------- Version 1.0 of the Music Sequence Maker takes a simple minded approach to repeat sections in a song. It simply replicates the section for each repeat. This is ok but leads to a large sequence file if there are many repeats in the song. If the song you want to turn into a sequence has a lot of repeat sections, or if the whole song is within a repeat section, you may want to limit the number of repeat loops or eliminate them altogether to conserve memory when the sequence is run. Future versions of the program will take a more intelligent approach to repeat sections and use the ability of phrases to have multiple pointers to the same note pattern. Reference Section Menu Functions ------------------------------------- FILE menu: QUIT: Exit the program. EDIT menu: UNDO/CUT/COPY/PASTE/CLEAR: These are here for the convienience of desk accessories. SONGS menu: LOAD ANY SONG: Use this function to load a song file from disk into memory in preparation for converting it to a sequence. The standard file dialog box is shown to let you select the file. After selecting the song file, it's loaded into memory along with the wave bank file containing the sound wave forms. Make sure the wavebank file used by the song is either in the same directory as the song file or in directory */WAVES off the boot volume (this is where they are on the Music Studio disk.) PLAY SONG: After a song is loaded into memory it can be played to check that it's the song you want. CONVERT TO SEQUENCE: Use this function to convert the song in memory to a sequence. A box will appear with an indicator showing the progress of the conversion. When done, the sequence will be in memory ready to play or to save to disk. SEQUENCES: LOAD ANY SEQUENCE: This option loads a sequence file of your choice from disk into memory so you can play it. The three files (-.SEQ, -.INS, -.WVE) created when the sequence was saved are read in and prepared for playing. If the program can't find the -.INS (instrument definition) file needed by the sequence, then you will be prompted to "open" the instrument file to show the program where it is. SAVE SEQUENCE: This option saves the sequence in memory to a set of disk files: YourFileName.SEQ - The sequence file with the notes. YourFileName.INS - The instrument definition file. YourFileName.WVE - The sound waveforms file. The reason three files are saved is to allow different instrument sets to be used to play the same note sequence. When you select this option you are presented with a standard file dialog box. Go to the directory you want to save the sequence files in and type in your choice for the sequence file name. Type only the base name, like "MYSONG". The program will then save the sequence as three files named MYSONG.SEQ, MYSONG.INS, and MYSONG.WVE. It's ok to name the sequence the same as the song file since the full filename will be different. LOAD INSTRUMENT FILE: This option lets you try different instrument files (-.INS files) with your sequence. The dialog box shows only -.INS files. Just pick one and it will be loaded and prepared for playing. To hear the sequence played with the new instruments, use the PLAY SEQUENCE option. PLAY SEQUENCE: With this option you can play a sequence that has been loaded into memory or created by converting a song file. A dialog box is presented with six buttons, a scroll bar to control tempo, and a sequence position indicator that shows the progress of the sequence being played. The buttons are: START: Start the sequence playing. The sequence will play to completion or until STOP, STEP, or PAUSE is pressed. STOP: Stop the sequence. PAUSE: Pause the sequence. It can be continued from where it left off by pressing the CONTINUE button. The sequence can be restarted by pressing START. CONTINUE: Continue the sequence after a pause STEP: Single step the sequence. If the sequence is playing it will pause. If the sequence is not playing it will start but will be paused immediately. Each time you press STEP the Note Sequencer advances one "tick" (not neccessarily one note). For most sequences you will need many presses of STEP to move to the next note in the sequence. CANCEL: Leave the Play Sequence dialog box. If the sequence is playing it will continue to play in the background. You can vary the tempo of the sequence by using the scroll bar. The number displayed to the right of the bar shows the current value of the "increment", the number of interrupts making up a tick (different note durations are made up of different numbers of ticks.) If you change the increment value with the scroll bar, then save the sequence to disk, the sequence will be saved with the new increment value. STOP SEQUENCE: Stop the current sequence if it is playing. This has the same effect as the STOP button in the Play Sequence dialog box. CHANGE SEQUENCE PARAMETERS: This option lets you change two parameters used by the Note Sequencer tool set: the "Update Rate" and the "Increment Value". The Increment value is the same parameter changed by the scroll bar and is the number of interrupts that go into a tick. The Update Rate is a number that determines how many interrupts per second will be sent to the Note Sequencer. If the Update Rate is 300 then 120 interrupts per second will be generated (one interrupt every 41 msec). If the Increment Value is 5, say, then a tick will last 5 * 41 msec or 205 msec or about 5 ticks per second. SOUNDS: LOAD ANY SOUND: This option lets you load any digitized sound file into memory in preparation for playing it. It's fun to load and play the -.WVE files created when sequences are saved. You can hear the digitized sounds used as the basis for the instruments. PLAY SOUND: Play the digitized sound file previously loaded. You will see a dialog box with two scroll bars for controlling volume and playback frequency, START and STOP buttons and an AUTO-REPEAT button to cause the sound to continuously repeat. CAUTION: Attempting to play files that are not true digitized sound files or that imbedded zeros can crash the GS. UTILITIES: RENAME FILE: Rename any file on any volume. DELETE FILE: Delete any file on any volume. COPY FILE: Copy a file from one directory to another. Or, make a duplicate of a file in the same directory. Use the standard file dialog box to select the file to copy and the destination directory. CHANGE FILE TYPE: This option lets you change the file type of any file. Just select the file and you will see a dialog box with a selection of common file types. Select from one of these or enter the HEX value of any file type. HELP: WHAT TO DO: This option shows a screen of text that summarizes the steps needed to turn a song file into a set of sequence files. ABOUT SEQUENCES: Gives a brief explanation of sequences and the contents of the various sequence files. How To Get the Source Code For the PlaySeq Program ------------------- The PlaySeq program shows you how to use sequences in your own programs to play music in the background. It contains routines to load sequence files from disk into memory, start the sequence, pause and continue the sequence, and keep track of where the sequence is. It also shows how to write a Filter Proc for a dialog box that updates an indicator showing the current position of the sequence, and how to set up a scroll bar to control the music's tempo. To get the source code for the PlaySeq program just send in the shareware fee of $20 ($18 if you enclose a 3.5" disk). Besides the latest version of the Music Sequence Maker program and the documentation, you will receive the APW C and TML Pascal source code for PlaySeq. The APW C version is compatible with ORCA/C and the TML Pascal version works for both the stand alone TML Pascal compiler and the APW version of TML Pascal. As a registered owner of The Music Sequence Maker, you will have the right to use any part of the PlaySeq source code in your own programs, commercial or otherwise. How To Get the Source Code For the Music Sequence Maker -------------- To get the source code for both the PlaySeq program and the Music Sequence Maker, send $35 ($33 if you enclose a 3.5" disk) to the address shown below. The Music Sequence Maker is written in TML Pascal and contains quite a large collection of useful routines. Here's a brief list of some of the things you can do with code from Music Sequence Maker: - Load, read, and play Music Studio song files. - Load the DOC RAM and set up instruments that can be played with calls to the Note Synthesizer's "NoteOn" routine. - Play sequence files: load/play/save sequence files. Start pause, and continue sequences. Full use of Note Sequencer. - Setup and use scroll bars to control volume and tempo. - Create Dialog Filter Procs to give real time feedback and graphics displays while sitting in a dialog box. - Load and play digitized sound samples with the Free Form Sound tools. Control volume and playback frequency with scroll bars. - Add general purpose utilities to your programs: Rename file, Delete file, Copy file, Change File Type, all controlled using the Standard File desktop routines. - Many useful routines included: Disable/enable interrupts Alert boxes Get file length Get file type Load a file Allocate memory Save a file to disk Get a prefix Get the root dir Get information from the user (integer/longint/string) By purchasing the source code for the Music Sequence Maker you will have the right to use any part of the source code in your own programs, commercial or otherwise. Shareware Details and Source Code Offer ------------------------------ This program is offered as "Shareware with a BONUS". Try the program out for 10 days. If it's not of any earthly use to you, pass it along to someone else. If you want to use it, send $20 ($18 if you enclose a 3.5" disk) to the address shown below. For your fee, you will become a registered owner of the Music Sequence Maker and are entitled to the latest version of the program, updated documentation, and the source code for the PlaySeq program (see above for details.) Future versions of the Music Sequence Maker may provide support for music programs other than Music Studio. Plans are in the works to allow conversion of Standard MIDI files to sequences. Support for DiversiTune is also something I'd like to do depending on time and response to this program. As a registered owner you will be entitled to any new version either for free or for a small upgrade fee. Summary: Shareware fee to get new version of Music Sequence Maker and source code for the PlaySeq program (C and TML Pascal): $20 Shareware fee to get source code for latest version of Music Sequence Maker (TML Pascal) and the PlaySeq program (C and TML Pascal): $35 Note: reduce above pricing by $2 if you send a 3.5" disk. Paul Gauthier 67 Sleigh Rd. Westford, MA 01886 978-692-4706