💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Music.and.Sound › SEQMAKER.DO… captured on 2024-06-16 at 14:08:02.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
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
508-692-4706
AppleLink: PGauthier
BCS Apple/Boston: PAULG