home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
614a.lha
/
MultiPlayer_v1.17
/
Player.doc.pp
/
Player.doc
Wrap
Text File
|
1992-03-03
|
62KB
|
1,370 lines
MultiPlayer
Version 1.17
Copyright 1991 Bryan Ford
All Rights Reserved
Disclaimer
~~~~~~~~~~
This program is provided "as is" without warranty of any kind, either
expressed or implied, including, but not limited to, the implied warranty
of fitness for a particular purpose. The entire risk as to the results,
reliability and performance of this program is assumed by you.
Introduction
~~~~~~~~~~~~
Welcome to the most powerful, versatile, and user-friendly music player
ever created on the Amiga! As you will see, MultiPlayer has almost all the
features you've seen in other music players, plus a great number that have
never been implemented before in a music player.
If you want to get full benefit from MultiPlayer you should at least
scan through this whole documentation. However, it is very easy to use, so
feel free to take it for a test drive first. If you're upgrading from a
previous version of MultiPlayer, make sure you look at the History section
near the end of this document to see what's new.
One of the goals of MultiPlayer is to be as system-friendly as
possible. It multitasks well, it doesn't interfere with high-priority
interrupts such as serial port interrupts, and it properly allocates audio
channels so that the music doesn't conflict with other programs. It is
fully functional on Kickstart 2.0 and 1.3 (although it works much better
under 2.0), and isn't prone to "lose" notes on fast processors like most
other players are.
Another goal of MultiPlayer is to support a very diverse array of music
formats. MultiPlayer currently supports over twenty different common
module formats, plus some special ones. See 'Supported Formats' near the
end of this document for a list of the module types MultiPlayer can play.
(Not all of MultiPlayer's features are available with every module format,
but MultiPlayer will at least play each format on the list.)
The unregistered version of MultiPlayer is freely redistributable as
long as it and its documentation is not modified in any way, and the files
listed below are distributed with it. (See the end of this file for
details about registering MultiPlayer.) You may not charge more for
distributing it than a small fee to cover the disk copying expenses. The
MultiPlayer version 1.17 distribution must contain the following files:
Player.doc MultiPlayer documentation (this file)
Player The unregistered version of MultiPlayer
Player.info Icon for MultiPlayer
Programmers/Formats.doc Specification of GMOD module format
Programmers/GMOD.i Include file to help with GMOD's
Programmers/DW_GMOD.asm Example GMOD header
Programmers/DW_Convert.c Example program to write GMOD files
Programmers/DW_Convert Executable version of same
Programmers/LMKFile SAS/C makefile for DW_Convert
ChipMunch/ChipMunch Useful utility if you have >512K chip RAM
ChipMunch/ChipMunch.info Icon for ChipMunch
ChipMunch/ChipMunch.doc Documentation for ChipMunch
ChipMunch/src/chipmunch.c SAS/C source for ChipMunch
ChipMunch/src/makescript MakeScript for ChipMunch
ChipMunch/src/sascopts SAS/C options
Acknowledgments
~~~~~~~~~~~~~~~
Michael Sinz (CBM) for tips on the memory manager.
Darren Schebek for lots of suggestions and ideas.
(When's your player library coming out, anyway? :-) )
Janne Saarme for lots of players and other stuff.
Teijo Kinnunen for MED/OctaMED support and player code.
Barry McConnell for lots of testing, suggestions, and possibly
some new user interface code. (Hint, hint. :-) )
And most of all, to the talented people who create all the
wonderful music on the Amiga!
General Usage
~~~~~~~~~~~~~
To start MultiPlayer, just type 'player' from the CLI or click on the
icon from the Workbench and it will present the ASL or ARP filerequester to
select a module from, depending on which version of the operating system
you are using. (If you are running 1.3, you must have the arp.library
version 39 or higher installed to get the file requester - if you don't,
you won't be able to load modules from the window.) Under 2.0, you can
select multiple modules at a time (as many as you want). Under 1.3, you
will have to select them one at a time (although you can still build
programs). If you run MultiPlayer from the CLI, it automatically detaches
itself, so there is no need to Run it. You can also start modules playing
immediately when MultiPlayer starts up - see the section on 'Startup
Options' for more information on starting MultiPlayer.
While MultiPlayer is running there is normally a small window in the
title bar displaying the name of the module that is currently playing (or
just "MultiPlayer" if nothing is loaded). You can click the close gadget
to stop the music and terminate MultiPlayer. If you are running Kickstart
2.0, the MultiPlayer window will have a zoom gadget near its right end. If
you click it, you will see a control panel that allows you to load
different modules and gives access to some of MultiPlayer's more advanced
features. Since 1.3 doesn't know about zoom gadgets, you can get the
control panel under 1.3 by pressing the right mouse button while the
MultiPlayer window is active.
If you have the xpkmaster.library (a freeware compression "supervisor"
standard mostly by Dominik Mueller, Christian Schneider, and myself)
installed in your system, MultiPlayer can automatically unpack modules that
are packed using any format it can understand. (This includes PowerPacker
format, if you have the powerpacker.library installed as well.)
If you start getting shaky when you see MultiPlayer's size (>80K),
don't worry (be happy) - thanks to a custom memory management and overlay
system, MultiPlayer uses only the memory it needs to do its job. All of
the module players are loaded only when needed, and any players not
currently in use are unloaded on demand if the system runs out of memory.
The parts of the program used to control MultiPlayer's various windows are
also only loaded when they are needed (when the respective windows are
open) and are freed as necessary. Thus, generally only about 25K of
program code is usually loaded at any one time.
If you have tons of memory and don't want overlays, the registered
release comes with a separate version of MultiPlayer ("Player.nov") that
runs without overlays (like a normal program). It generally uses about 50K
more memory than the overlaid version does, but it can be compressed with
PowerPacker or Imploder if you're short on disk space. (Imploder *should*
be able to compress the overlaid version of MultiPlayer, but it won't - I
haven't figured out why.)
For all you hackers (used in the positive meaning) that like to rip out
every form of music imaginable, when you come across some obscure module
format that nothing understands, don't despair. There are several special
formats built into MultiPlayer that you can use to easily interface it to
any kind of module. All you need is the module, some player code for the
module (if the module doesn't already have embedded player code), and a
little assembly language programming. Details on all three formats are in
the separate file 'Formats.doc'. If you are the author of a music composer
program, you should also read this document and consider supporting the
GMOD embedded-player module format in your program. (It's not a music
storage standard - it's more like a music playing standard.)
Control Panel
~~~~~~~~~~~~~
The main MultiPlayer window normally sits quietly in the title bar. (If
you don't like it there, move it somewhere else and save the preferences -
it'll stay put wherever you want it.) However, if you click the zoom
gadget under 2.0 or click the right mouse button under 1.3, it will become
a small control panel. Under 2.0, if you have a 3-button mouse, the middle
button will act the same as the zoom gadget. This panel displays a few
pieces of information about the module currently playing, and has some
buttons you can use to control MultiPlayer.
When running under Workbench 2.0, the MultiPlayer control panel is an
AppWindow, so you can play modules by simply dropping their icons into the
MultiPlayer window. When you do, the new module (or several modules, if
you extended-select them) replaces the current program, and MultiPlayer
starts playing the first module immediately. This works basically like
selecting modules with the New button.
Module box
This box displays the filename of the module currently loaded
(essentially the same as what is displayed in the title bar). Any 'mod.'
prefixes for Soundtracker/Noisetracker modules will not be displayed.
Type box
Displays the type of the loaded module (as MultiPlayer sees it).
Simple enough?
Author box
Displays the name of the person who wrote this module, if MultiPlayer
can glean this information from the module. Most current module formats
don't have direct facilities for identifying the author - in this case, the
box will just display 'Unknown'. Soundtracker/Noisetracker modules often
have author names embedded in the instrument list - in this case,
MultiPlayer will try to make a good guess by searching for keywords such as
'by'. (If it screws up for some reason, you can always type the module in
hex to find out for sure.) MED modules have somewhat better support, but
they still don't have a convenient 'author' field - just a catch-all
'annotation' field, which MultiPlayer processes much the same way as with
Soundtracker modules. GMOD modules are the only types I know of that
directly support author identification, but they are at the moment few and
far between. (Let's get with it, OK? Don't all the wonderful musicians
want to be recognized?)
Song gadget
This gadget serves two purposes. First, it displays the name of the
currently loaded module or song as recorded in the module itself. For
example, with Soundtracker/Noisetracker modules this gadget will display
the song name as recorded in the first 20 bytes of the file. Many module
formats don't have built-in name fields - in this case, the box will just
display 'Unknown.'
For most types of modules, which support only one song per module, this
gadget will serve no purpose other than displaying the song name - clicking
on it will do nothing. However, some module formats such as (GMODs) allow
several independent songs to be contained in a single module (for example,
to save memory by using the same instruments on several songs). In that
case, this gadget will cycle through the available songs in the module.
You can also change songs using the left and right arrow keys.
Volume slider
This slider controls the volume of the currently playing module.
Minimum volume is all the way to the left; maximum is all the way to the
right. This feature doesn't work with all types of modules, but it works
with the most popular types.
The current master volume, balance, and speed settings are saved with
MultiPlayer's Preferences, so when MultiPlayer starts up they will be set
to whatever they were set to last time you saved MultiPlayer's preferences.
Balance slider
This slider adjusts the balance by scaling the left and right volumes
separately. When the slider is all the way to the left, only the left
channels will be played; when it is all the way to the right, only the
right channels will be played. Normally it's in the center, where both
sides play with equal volume. Like the volume control, this feature
doesn't work with every type of module MultiPlayer supports.
Speed slider
This slider adjusts the module's current playing speed. Move the knob
to the left to slow down the module; move it right to speed it up. The PAL
and NTSC buttons to the right of the slider set the speed to two common
presets. PAL (the default) sets the speed to 50Hz, which is what most
modules are written for. NTSC sets the speed to 60Hz, which simulates the
speed at which poorly-written music players and games play music written
for PAL mode.
New button
This button displays the file requester and lets you select any number
of modules. The new list of modules replaces the current program, if there
was one. The first module in the list (or a random module, if you have
selected random playing) will be started. The program will be created with
the order in which the modules were displayed in the file requester. (At
least this is how the current ASL file requester works - it may change.)
If you select a directory but don't select a file (leave the "File" string
gadget blank), MultiPlayer scans the directory and adds everything in that
directory to the program.
Play button
Starts or continues playing a module that was previously stopped but
not unloaded. If the module type supports the continue feature, the module
will continue playing where it left off. Otherwise it will start again
from the beginning. If you have selected the 'Fade...' checkbox in
Preferences, and the module type supports volume control, the music will
fade in gradually instead of just starting instantly.
Stop button
Stops the current module without unloading it. Audio channels and
interrupts are freed while a module is stopped, so you don't have to exit
MultiPlayer completely if you want to run some other program that needs the
audio hardware. If you have selected the 'Fade...' checkbox in
Preferences, and the module type supports volume control, the music will
fade out gradually instead of stopping instantly. If the module type
supports restart, you can restart it where it left off by pressing the Play
button.
Eject button
Stops and unloads the currently loaded module, and frees all memory and
other resources that the module was using.
Next button
Loads and plays the next module in the current program list. If you
have selected random play, this button simply loads another module in the
list, at random. This is the same as pressing the down arrow key in the
MultiPlayer window.
Prev button
Loads and plays the previous module in the program list. If you have
selected random play, this button does basically the same thing as the Next
button - picks another module at random. This button does the same thing
as pressing the up arrow key in the MultiPlayer window.
Program button
Opens the Program window, described below. Under 2.0, you can
also do this by clicking the right mouse button while the main MultiPlayer
window is active.
Prefs button
Opens MultiPlayer's Preferences window, described later.
Program Window
~~~~~~~~~~~~~~
The program window displays a list of all the modules in the current
module 'program'. You can select modules from the list to load and play
immediately by simply double-clicking on their names. You can also build
and rearrange your program using this window. You get this window by
pressing the 'Program' button on the main window's control panel, or by
pressing the Help or F1 keys in the MultiPlayer window, or, under 2.0, by simply
clicking the right mouse button while any of MultiPlayer's windows are
active. Note that this window doesn't cause the main control panel to
"freeze" - you can still watch and use it while this window is open. In
fact, all of MultiPlayer's windows (even the file requester) are this way.
If sequenced play is selected (the default), when one module is
finished, the next lower one on the list is loaded and played. (This only
applies on modules that can detect repeat - most do, but on those that
don't, unless you have set an end time in the Settings window, the module
will just play forever until you explicitly tell MultiPlayer to go to the
next module.) With random play, a different module will be randomly
chosen. There is no limit to the number of modules you can have in a
program, and modules in the program can be located in many different
directories - MultiPlayer will remember the location of each module.
When running under Workbench 2.0, the Program window is an AppWindow,
so you can add modules by simply dropping their icons into this window.
This window works slightly differently from the main Multiplayer window,
however. When you drop icons into this window, the behavior is the same as
if you had selected the modules with the 'Add' button: The new modules are
added to the end of the current program list (instead of replacing the
current program), and whatever is currently playing remains unaffected.
Besides the module listing, this window contains several buttons that
allow you to manipulate the module list. These are described below:
Top, Up, Down, and Bot buttons
These buttons allow you to rearrange the modules in the program. They
work on the currently selected module, and their meanings should be obvious.
Add button
This button works basically the same way as the 'New' button on the
main window - it brings up the file requester and allows you to select
modules. However, it doesn't cause the previous program to be cleared when
you finish, and it doesn't start playing a new module immediately. If you
select a directory without selecting a filename, MultiPlayer will scan that
directory and add all the files in it to the program.
Del button
This button deletes the currently selected module in the program list.
If this module is currently playing, it doesn't stop the module immediately
- the module continues playing until you select a different module.
Play button
This button does basically the same thing as double-clicking on a
module name in the program list: it loads and starts playing the currently
selected module.
Settings button
This button toggles the Settings window, described later. The F3 key
can also be used for this purpose.
Clear button
Clears the entire current program list. As with the 'Del' button, it
does not stop any currently playing module.
Sort button
Sorts the entire current program list alphabetically. Handy if you
like to use random play (and thus don't really care about the play order)
and you'd like a nice neat module listing.
Load button
Brings up the file requester so you can load a previously saved program
from disk. (This button will only work on the registered version of
MultiPlayer.) The newly loaded program will replace the current program.
Note that you can also load saved programs from the regular module
requester - programs are recognized just like modules, and programs
selected this way will automatically be loaded and run. (You could even
put the name of another program file at the bottom of the first one, and
chain programs together!)
Save button
Brings up the file requester and lets you save the current program to a
disk file. (Also only works on the registered version.) You can then load
it again later through the Load gadget or using any method normally used to
select modules - the file requester, Workbench extended-select when
starting MultiPlayer, or CLI arguments. (See the 'Startup' for details on
starting MultiPlayer.)
OK button
This button simply closes the Program window - the same thing as
clicking the close gadget.
If you want to create or modify module program files yourself, just
take a look at one of the files MultiPlayer generates - it's just a simple
text file. Lines starting with 'DIR' denote changes of directory - all
filenames after that until another 'DIR' keyword will be looked for in that
directory. Lines that start with a tab character (make sure they remain
tab characters, and don't get converted to spaces!) contain the settings
information for the module on the previous line. I won't explain the
format exactly, but it shouldn't be too hard for you to figure out if you
want to.
Preferences Window
~~~~~~~~~~~~~~~~~~
MultiPlayer's built-in Preferences window can be opened by clicking on
the 'Prefs' button in the main MultiPlayer window, or by pressing F2 in any
of MultiPlayer's windows. It contains a few options which you can use to
tailor MultiPlayer to your own preferences. The gadgets are described
below:
Play gadget
Use this to select between sequenced play, random play, and 'over and
over' mode. In sequenced play, the modules in the program list are played
one after another, from beginning to end, in the order they appear in the
program list. In random play, a module plays once and then another is
randomly selected. In 'once' mode, the song is played only once, then is
unloaded and MultiPlayer becomes idle. In 'over and over' mode, anything
you select is played forever until you tell MultiPlayer to start a
different module. (In these last two mode, you can still use the 'Next'
and 'Prev' buttons in the main window to change modules; MultiPlayer just
doesn't do it by itself.)
Show gadget
This cycle gadget allows you to select the type of display you want to
appear in the main window's title bar while a module is playing. In clock
mode, a clock appears displaying the amount of time this module has been
playing in minutes and seconds. In sequence mode (this has no relation to
the 'in sequence' mode in the 'Play' gadget), on NoiseTracker or similar
modules that play sequences of blocks, the current sequence number and the
number of sequences in the song is displayed. (On modules that don't
support this, the clock is displayed instead.) You can tell MultiPlayer to
display the current sequence number either starting from 0 and ending at
length-1, as most tracker programs display sequence numbers, or starting
from 1 and ending at (length), which is the more 'natural' way of counting.
Selecting the 'Nothing' option in this gadget will leave you with a simple,
clean, unadulterated title bar.
Spectrogram checkbox
Use this to turn the spectrogram window on or off. The F6 key also
serves this purpose.
Note Scroller checkbox
Use this to turn the note scroller window on or off. The F7 key also
serves this purpose.
StereoScope checkbox
Use this to turn the stereo scope window on or off. The F8 key also
serves this purpose.
QuadraScope checkbox
Use this to turn the four-channel scope window on or off. The F9 key
also serves this purpose.
Fade... checkbox
If this checkbox is activated, whenever you press the 'Play' or 'Stop'
gadgets in the main control panel (or press the spacebar), the music
gradually fades in and out rather than abruptly starting or stopping.
This will only happen on modules that support volume control.
Keep... checkbox
If this checkbox is activated, MultiPlayer does two things differently
than it normally does. First, when you save the preferences, not only are
the preferences saved as usual, but the currently loaded program is also
saved in ENV: and ENVARC: in a file called "MultiPlayerProgram". Second,
when MultiPlayer starts up, if it sees that you have this option set, and
you haven't specified any other modules or programs in the startup options,
it automatically loads this program (without starting it). This way, if
you generally only keep one program around, this option provides an easy
way to always load it automatically without worrying about any startup
options or anything. Even if you have this option selected, you can still
load and save other programs normally through the Program window.
Hot key string gadget
By default, this string gadget is empty and MultiPlayer behaves like a
normal application. However, you can enter a Commodities-style hotkey name
into this gadget. (Make sure you press return in the gadget after changing
the string!) MultiPlayer will then activate that key as a hot key which
you can use to open the main MultiPlayer control panel at any time. When a
hot key is active, clicking the control panel's close gadget closes all of
MultiPlayer's windows, but does not terminate MultiPlayer or stop playing
music. You can use this too keep MultiPlayer hidden in the background,
without using any screen space at all. This feature only works on 2.0.
Save button
Saves the current preferences to the disk file ENV:MultiPlayerPrefs, as
well as to the same file in ENVARC:. (With a preferences window as simple
as this, there's no real need for separate 'Save' and 'Save Default'
options.)
The preferences saved include, as well as the current settings of the
above two gadgets, the positions of the three main MultiPlayer windows. The
next time you run MultiPlayer, the windows will pop up wherever they were
when you saved the preferences.
OK button
Does exactly the same thing as the close gadget on the window does -
closes the Preferences window. It does NOT cause the new preferences to be
activated, because they are already activated: anything you select gets
activated the moment you select it. (None of those exclusive Macie dialog
boxes, please.) There is no 'Cancel' gadget because I figure it's not too
difficult to change back any buttons you accidentally hit, since there are
so few...
Settings Window
~~~~~~~~~~~~~~~
MultiPlayer's Settings window serves a function very similar to the
Preferences window. However, instead of storing settings that apply to
MultiPlayer as a whole, it is used to select options that pertain to
individual modules in the program list. To get it, click the 'Settings'
button in the program window, or press F3 in any of MultiPlayer's windows.
The Settings window contains a number of gadgets which control how the
currently selected module (not necessarily the currently playing module) is
to be played. MultiPlayer stores separate settings for each module on the
program list. When you save the program list, the settings for each module
are saved with it. Not all of the settings are applicable to every type of
module; on those modules, the appropriate settings gadgets will be disabled.
Module box
This text box displays the name of the currently selected module (the
same as the name displayed under the program list gadget in the Program
window). This is not necessarily the module that is currently playing -
you can edit the settings for one module while you play another (or while
you're not playing any module).
Volume, Balance, and Speed gadgets
The gadgets in these two rows complement the corresponding gadgets in
the control panel. While the controls in the main window control whatever
module is currently playing, these gadgets control the individual modules
in the program. For example, when you play a given module, the volume at
which it plays is determined by both the master volume setting on the main
control panel, and the volume setting for that specific module defined in
the Settings window. This allows you to set specific settings for
individual modules, while still being able to control the overall speed,
volume, and balance independently from the main control panel.
End text box and gadgets
These settings allow you to tell MultiPlayer when to stop a module that
normally doesn't stop by itself, or to make MultiPlayer stop playing the
module before it would normally end. The text box displays the amount of
time MultiPlayer will let the module play before stopping it, if you've set
an endpoint.
To set a module's endpoint, you must be currently playing the module
you want to change the setting for. (The Set button will only be activated
if this is the case.) When the music gets to the point where you would
like it to stop every time you play it, click the Set button. MultiPlayer
will record the endpoint and (since setting the endpoint implies that you
have reached it) the module will immediately end. Next time you play that
module, it will stop automatically at that point. To clear a module's
endpoint, just press the Clear button.
Note that the endpoint stored is only an amount of time to play -
MultiPlayer generally can't actually tell where in the module you are at
that time. Therefore, messing with the module's playing speed will throw
off the endpoint timer. Changing video frequencies (i.e. switching between
PAL and NTSC mode) while the module is being timed can also throw off the
timer. I may fix this problem in the future, if there is enough demand.
(If it's really important to you, tell me and I'll put it higher on my
list.)
Filter cycle gadget
This gadget determines how the low-pass filter (and the power LED) is
handled. Normally it's just set to 'controlled by module', so music
modules can turn it on or off as part of their effects. However, if a
particular module does things you don't like with the filter, you can force
the filter permanently on or off with this gadget, so the module can no
longer control it. Of course, this feature works only on module types that
allow MultiPlayer to control the filter.
Protracker tempo commands checkbox
This checkbox is only activated for standard ST/NT/PT modules. If it
is not set, the Protracker player interprets all speed commands in the
module as NoiseTracker and other older trackers did, and keeps the baseline
frequency at 50Hz (or whatever you set the speed to). If this checkbox is
set, the newer Protracker tempo commands are enabled. Basically, this
option is here because there is no reliable way to detect whether a module
is using NoiseTracker speed commands or Protracker tempo commands. While
most modules will work fine on either setting, some will only play at the
correct speed at one setting. If you play a module and it suddenly starts
going way too slow, or way too fast, or otherwise plays at an obviously
"wrong" speed, try flipping this checkbox and start the module again. In
general, older modules need this checkbox to be off, while newer Protracker
modules need it on.
Fade checkbox
If you select this checkbox, and the module supports volume control,
when the module ends, instead of stopping immediately it will continue for
a couple seconds longer (most likely repeating an earlier part of the
song), gradually fading out. This is nice for the many modules that just
repeat over and over, and never actually end. With this feature you can
make the ending seem a little more natural.
Current button
Pressing this button will set the currently selected module to the same
as the currently playing module. Thus, if you are listening to a module
and decide you want to change something about it, you don't have to hunt it
down in the program list - just press this button, and you will be
instantly at that module.
OK button
This button simply closes the Settings window. Like the OK button in
the Preferences window, it doesn't actually cause anything else to happen,
because whenever you change anything in the Settings window, the changes
take effect immediately.
Flashy Windows
~~~~~~~~~~~~~~
For your viewing pleasure, MultiPlayer contains some little gizmos that
you've probably seen before in Eurodemos and other players. The
Spectrogram window displays a bar graph of the frequencies currently
playing. The Note Scroller window shows a miniature tracker-like display
of the notes scrolling up the screen. (You can't read the notes, but if
you're using MultiPlayer you're probably wanting to listen to music, not
read it, right?) This works only on Protracker-type modules. The Stereo
Scope window shows an Oscilliscope-like view of the sound coming out of
each channel. The QuadraScope is basically the same thing as the Stereo
Scope, except it has a separate display for each of the four channels. (You
can have both the StereoScope and the QuardraScope active at the same time
if you want.)
All four windows can be toggled on and off from the Preferences window.
Each also has a function key that works from any of the windows. You can
toggle the Spectrogram window with F6, the Note Scroller with F7, the
StereoScope with F8, and the QuadraScope with F9.
All "flashy" window updating is done in a separate task with a priority
of -5, so turning on these windows should not generally degrade system
performance at all. However, this means that the windows will stop
updating temporarily when the system is heavily loaded.
Keyboard Shortcuts
~~~~~~~~~~~~~~~~~~
Several keyboard shortcuts are available from any MultiPlayer window
(except the file requester). Most of these have been mentioned before in
this document, but they are listed all together here. All of these are
available under 1.3 as well as 2.0. These keys are listed below:
ESC key
Terminates MultiPlayer immediately (a shortcut for the close gadget on
the main window.
F1 and Help keys
Toggles the Program window (opens it, or closes it if it was already open).
F2 key
Toggles the Preferences window.
F3 key
Toggles the Settings window.
F6 key
Toggles the Spectrogram window. (Also toggles the Spectogram item in
the Preferences window.)
F7 key
Toggles the Note Scroller window.
F8 key
Toggles the StereoScope window.
F9 key
Toggles the Note Scroller window.
Spacebar
If a module is currently playing, stops (or pauses) it without
unloading it, just like the 'Stop' button in the main window. If a module
is loaded but NOT playing, it continues or restarts it, just like the
'Play' button.
Delete key
Unloads ('ejects') the currently loaded module.
Up/down arrows
These switch to the previous or next modules in the program list,
respectively. In random play, these simply select another module at
random. (These are shortcuts for the 'Next' and 'Prev' buttons in the main
window.)
Left/right arrows
For modules that contain more than one song, these select the previous
or next song, respectively (shortcuts for the 'Song' cycle gadget).
Startup Options
~~~~~~~~~~~~~~~
When starting MultiPlayer from Workbench (either 1.3 or 2.0), you can
extended-select the icons of as many modules as you want when you start
MultiPlayer. It will add all of these modules to the program and
immediately start playing the first one (or a random selection, if you have
selected random play in your saved preferences). Additionally, you may set
certain default parameters in the ToolTypes field of MultiPlayer's
Workbench icon; these are described later in this section.
If you're running Kickstart 1.3, MultiPlayer will accept a single
argument from the CLI (don't use quotes, even if there are spaces in it).
If this argument ends in a ':' or '/', MultiPlayer will change to that
directory before displaying the ARP file requester. If it doesn't end in
one of these characters, MultiPlayer will try to load the specified file as
a module and start it playing rather than displaying the file requester
immediately. MultiPlayer doesn't have any extra command-line goodies under
1.3, so if you need any of these extra features, maybe it's time to
upgrade...
If you're running Kickstart 2.0, MultiPlayer supports a full set of
command-line options:
DIR=DIRECTORY,PLAY=MODULES/M,PROG=PROGRAM/M,
SCREEN/K,NOREQUEST/S,NOWINDOW/S,NOREXX/S
Following is a description of these arguments:
DIR (synonym: DIRECTORY)
The first argument on the command line (or the argument preceded by
the DIR keyword, if you use the keyword) tells MultiPlayer what directory
to go to the first time it displays the file requester. This is also where
it will look for modules you specify on the command line (see below) if you
don't specify full pathnames for them. Using this option to specify the
directory where everything else comes from can save you some typing if you
specify several modules that reside in the same directory on the command
line.
PLAY/M (synonym: MODULES/M)
The second argument (if you don't explicitly use the DIRECTORY or
PLAY/MODULES keywords) begins a list of modules to put into MultiPlayer's
program list on startup and start playing immediately. MultiPlayer imposes
no limitations on the number of modules you can specify using this keyword,
although AmigaDOS command lines are currently limited to 256 characters.
After MultiPlayer starts up, instead of showing the file requester
immediately, it will load and begin playing the first module in the program
list (or a randomly selected module, if you have selected random playing in
your saved Preferences). With the registered version of MultiPlayer,
program list files act the same way as modules, so you can specify a
program file to load and start initially instead of a list of modules.
PROG/K (synonym: PROGRAM/K)
You can use this keyword followed by the name of a program file as an
alternative to the PLAY option. If you use this option, MultiPlayer will
load the named program file on startup and just go idle, rather than
starting the first module immediately as it would if you used the PLAY
keyword. To start the program, just hit the "Next" or "Prev" gadgets in
the main window (or just hit the up or down arrow keys in any of the
MultiPlayer windows). This feature only works on the registered version.
Note that, apparently due to a bug in 2.04, if you specify the PROG
keyword without giving a directory name as the first option, the PROG
keyword and the program get put together and interpreted as a module name
for the MODULE keyword! Therefore, instead of "Player prog mus:blah", just
use "Player mus: prog blah".
SCREEN/K
You can use this parameter to tell MultiPlayer to open its windows on a
screen other than the Workbench (or default) screen. Just supply the name
of the public screen as this parameter, and MultiPlayer will try to use it
for all its windows. The named public screen must already be open.
NOREQUEST/S
If you specify the switch, MultiPlayer will not display the file
requester immediately after it loads, even if you don't specify any modules
to start playing. If you don't specify any modules, MultiPlayer will
simply sit idle until you tell it to do something.
NOWINDOW/S
This switch causes MultiPlayer to load and run without opening its main
window. If you specify modules to start playing, MultiPlayer will play
them as usual, but you won't see any visual indication that MultiPlayer is
running. If you have activated a hot key in MultiPlayer's saved
preferences, you can later open the control panel with it. You can also
open the window through MultiPlayer's ARexx port, assuming you haven't
turned that off as well.
NOREXX/S
If you specify this switch, MultiPlayer will not open its ARexx port.
(On the unregistered version, MultiPlayer doesn't have an ARexx port, so
this switch will do nothing.)
If you run MultiPlayer from the Workbench, it will search through the
ToolTypes array in its own icon for parameters which are roughly equivalent
to the CLI parameters described above.
DIR (synonym: DIRECTORY)
PROG (synonym: PROGRAM)
SCREEN
These ToolTypes act exactly like the corresponding CLI arguments.
Simply enter one of these ToolType labels, then an equals ('=') sign, then
the appropriate text. For example, to load the program "Mus:DefaultProg"
on startup, add the ToolType "PROG=Mus:DefaultProg".
REQUEST
WINDOW
REXX
These ToolTypes perform the same functions as the similarly named CLI
arguments, but instead of simply being flags,they are YES/NO ToolTypes. For
example, to prevent MultiPlayer from opening the main window on startup,
enter "WINDOW=NO" into the ToolTypes.
ARexx Port
~~~~~~~~~~
If you have ARexx, either as an independent program in 1.3 or as part
of the operating system in 2.0+, you can use it to control the registered
version of MultiPlayer. Whenever MultiPlayer is running, there is an ARexx
port available called "RXTRACKER" which you can send various commands to.
MultiPlayer's ARexx port is designed to be (mostly) compatible with the
program RxTracker by Dominic Giampaolo. In addition, it has several
extended features, and of course you can use it to play all the different
kinds of modules MultiPlayer understands.
If MultiPlayer runs into an error when trying to load or play a module,
it generally returns an error code of 10. When any error occurs, a
descriptive error string is saved and you can get it with the LASTERROR
command.
A listing of the ARexx commands MultiPlayer understands follows:
LOAD <filename>
Loads a module into memory from disk. It is generally a good idea to
supply a complete pathname, since MultiPlayer looks for the module starting
at whatever directory the file requester last happened to be looking at.
This command does not start the module playing. If you want to start
playing immediately, you don't have to use this command at all - you can
simply supply a filename on the PLAY command and it will load and start
playing immediately. Note that unless you tell MultiPlayer to load a
program file, this command won't affect the program list at all - the ARexx
port in general operates independently of the standard user interface. If
you explicitly tell MultiPlayer to load a program file using this command,
then the new program list will replace the old one.
PLAY [<filename>] [<songnumber>]
Starts playing a module. If you supply the filename, MultiPlayer stops
any module currently playing and tries to load the specified module from
disk, like the LOAD command. If you don't supply the filename, MultiPlayer
plays (or re-plays from the start) an already-loaded module. (If no module
is loaded and you don't specify a filename, MultiPlayer returns error code
5 and otherwise does nothing.) For modules with more than one song, you
can supply the song number to play. Songs are numbered starting at zero.
If you don't supply a song number, the first one (song zero) is assumed.
STOP
Stops playing any module that is currently playing without unloading
the module. You can then restart it later with PLAY or CONTINUE.
UNLOAD
Stops and unloads any currently loaded module.
CONTINUE
Tries to restart a stopped module at the position it was at before the
STOP command was given. If the module has never been started, it simply
starts from the beginning. If the module was already playing, it does
nothing. If the module type doesn't support restarting, MultiPlayer
returns error code 5 and does NOT start the module - you can then use PLAY
to start again from the beginning if you want, or else chew out the user
for playing weird module formats.
OPENWINDOW
Opens the main MultiPlayer window. It will be opened in the small
title-bar zoom state, and none of MultiPlayer's other windows will be
opened with it. If the window was already open, this command does nothing.
It returns an error if the window can't be opened. Remember that while the
window is open the user can use it to change modules and such, possibly
messing up your perfectly organized and timed ARexx-controlled playing
sequences.
CLOSEWINDOW
Closes the MultiPlayer window, if it was open. MultiPlayer remains
active, but impervious to user interface (through Intuition anyway). Now
only ARexx commands can affect MultiPlayer.
LASTERROR
Returns an error message describing the last error that occurred that
had to do with the ARexx port. (Errors that the user causes by
manipulating the window do not affect this.) You'll have to have 'options
results' turned on for this to work, and the error will appear in the
'RESULT' variable.
QUIT
Causes MultiPlayer to terminate immediately.
Messages
~~~~~~~~
This section lists most of the error or warning messages MultiPlayer
can produce. Look here if you have trouble deciphering the meaning of one.
"Not enough chip memory"
Tracker-style modules generally must be loaded into one big continuous
chunk of chip memory. Therefore, even if the Workbench (or some other
program) says you have enough memory, it may not have one big enough chunk.
Close some windows, exit some programs. If all else fails, reboot and try
fresh.
"Not enough memory"
You really are getting low. MultiPlayer doesn't normally need too much
non-chip memory, since modules are always loaded into chip memory. If you
get this message, it means you don't have much memory of ANY kind
available. Better free up something quick.
"Required memory occupied"
You will only get this message from non-relocatable AMOD or GMOD
modules. It means that the module has a specific address it must be loaded
into, but part or all of the required block of memory is already in use.
Free up as much memory as possible and try again. If most of your memory
is free and you still can't load it, chances are there's some little
allocated fragment that some program has forgotten about that's still
sitting in the required area. Your best bet is to reboot and try on a
fresh system. If you have more than 512K of chip memory, try running my
program 'ChipMunch' (included with MultiPlayer) just after you reboot to
keep programs out of the commonly used areas.
"Nothing selected"
Not an error, this simply means that you pressed Cancel in the file
requester without selecting any modules. MultiPlayer then happily goes on
doing whatever it was already doing.
"Unknown module type"
MultiPlayer doesn't recognize the file you selected as one of the
module types it knows. Either this isn't a music module, or it's one that
it doesn't know how to handle. If it is a music module that MultiPlayer
doesn't know about, send me the module and player/interface code, and it
should make it into the next version of MultiPlayer.
"Corrupt module"
MultiPlayer recognized the module, but it didn't look right for some
reason. Maybe it's a module written with an incompatible version of the
music program, or maybe the module itself got munched somehow.
"Error playing module"
A general catch-all. This error usually is displayed as a result of
error reports from initialization routines of individual players. It
generally means that the module loaded fine, but the player had trouble
playing it. Sometimes it means the same thing as "Corrupt module", or it
might mean that the player ran out of memory but was too stupid to tell
MultiPlayer about it specifically.
"Can't load module"
The requested file was not found, or there was a disk error while
reading it. If you get this message after selecting a file from the file
requester, chances are the disk is corrupt (in this case AmigaDOS should
have already given you a requester saying so), or the file may be open for
writing from some other program.
"Directory not found"
Somehow you managed to tell MultiPlayer to load something from a
directory that doesn't exist. Maybe you moved the directory somewhere
else, or forgot an Assign somewhere. This usually only happens with ARexx
commands or loaded program lists.
"Audio hardware in use"
MultiPlayer can't allocate the audio hardware through the audio.device.
This probably means that some other music editor or player is currently
running. Find the culprit program and close it. If all else fails, reboot
and try again.
"No CIAB timers available"
MultiPlayer generally uses one of the two timers on CIA (Complex
Interface Adapter) B for timing its music. However, other programs like to
use these also. In particular, (I believe) one of the timers may be in use
if the serial port is in operation. Other than that, music programs are
generally the biggest consumers of CIAB timers. Make sure no other music
player or composer programs are running, and try closing terminal programs
or other programs that use the serial port.
"Please decompress this module"
It is unlikely that you will ever get this message, but if you do, it
means that (a) the module MultiPlayer is trying to load is compressed
somehow (MultiPlayer had to use the xpkmaster.library to decompress it),
and (b) it is an AMOD or GMOD module that must load at an absolute address,
and (c) MultiPlayer would have to re-load the module rather than just
copying it to its final position because the memory the module occupied
initally overlapped the required module address. If you don't quite
follow, don't sweat - just decompress the module.
Supported Formats
~~~~~~~~~~~~~~~~~
MultiPlayer currently supports the following module types:
15-instrument SoundTracker modules (most anyway)
31-instrument SoundTracker/NoiseTracker 1.3D modules
Protracker 1.0-1.1B modules
NoiseTracker 1.3D packed modules (with or without the embedded player)
StarTrekker 1.2 AM/FM modules (Extra '.NT' file required)
MED 3.00-3.21 and OctaMED 1.00-1.00b modules
Modules (MMD0) only - not "Song&Samples" files.
(Thanks Mr. Kinnunen!)
Oktalyzer 4- and 8-channel modules
Uses my own 8-channel play engine. 8-channel modules will
be slightly higher quality on a 68020+ processor.
SoundFX V1.3 executable modules (Player V2.2)
Will probably ONLY work with this version, since it does
some run-time patching to make it play under MultiPlayer.
Future Composer 1.3 ('SMOD') and 1.4 ('FC14') modules
JamCrackerPro 1.0a modules
SoundMonitor 2.0 modules
SidMon 2.1 modules
Delta Music modules (two versions)
Mark II modules
Dave Whittaker modules
Face The Music modules (DO NOT COMPRESS!)
This is very kludgy at best - you must have "PlayFTM:" ASSIGNed
to the PlayFTM program file. (Didn't know you could ASSIGN
to a file? Now you do!) The procedure involves loading the
module, the external player, and then the module again. Ack!
Apologies to floppy users. I'm trying to contact the author(s)
of FTM to get some real player code, but no luck so far.
Generic embedded-player modules that start with something like
jmp init(pc)
jmp music(pc)
jmp end(pc)
(Such as NoiseTracker 1.3 packed w/player modules)
AudioMaster III sequenced 8SVX sounds (mono only)
'XMOD', 'AMOD', and 'GMOD' formats described in 'Formats.doc'
Some of the module types are marked as 'untested'. This means exactly
what it says - I found out the appropriate methods to play these and easily
added support into MultiPlayer, but I didn't have any modules to test it
on. So if I made a stupid mistake, one or more of these may not work at
all. If you try one of these formats and it doesn't work, send me a few
modules in the appropriate format to test with, and if you're the first to
do so, I'll register you for free and send you the new bug-fixed version of
MultiPlayer.
Although sequenced 8SVX sounds are technically only sampled sound
files, they have some music capability and look promising. Besides, the
player also plays non-sequenced 8SVX sounds, so you can also play your
movie clips and such with MultiPlayer. (I'm not sure if AudioMaster III is
the only program that currently supports sequenced 8SVX files, but it's the
only one I've seen so far.) Stereo is currently not supported - sorry, I'll
get to that eventually.
History
~~~~~~~
1.17 (28-Feb-92)
Fixed a serious bug in Guido (the user interface system) that sometimes
caused crashes under 2.0.
Fixed a tempo bug in the Protracker player.
Modules in the program list are now played by double-clicking them.
(lets you delete and do other things on them without playing them.)
Added Settings window. (Get to it from the Program window.)
Rearranged the function key assignments yet again.
(Sorry - they should stay the same for a while now.)
MultiPlayer can now read parameters from its ToolTypes for options when
started from Workbench.
Added volume control to Oktalyzer 8-channel player.
Added Commodities support under 2.0 - only one copy of MultiPlayer
gets run at once, and you can pop it up with a hot key.
Two of the ARexx port's command names have changed: OPENWINDOW and CLOSEWINDOW
are now OPENWINDOWS and CLOSEWINDOWS.
Added "Keep program with preferences" option (in the Preferences window).
Changed the random number generator, hopefully for the better.
Note: The 1.3 support in this version of MultiPlayer is very minimal. The
next version will probably not support 1.3 at all. Going, going...
1.16 (8-Feb-92)
Fixed a serious bug in the DeltaMusic player.
Save Prefs now snapshots both states of main window.
Flashy window updates now run in a separate low-priority task.
Upgraded MED 3.20 player to 3.21, and added Continue support.
(Thanks Mr. Kinnunen!)
Added (very kludgy) Face The Music support.
(See the "Supported Formats" section for how to use it.)
Added PROG keyword to command line options.
(Lets you load a program file without starting immediately.)
Fixed Mark II player.
Protracker player now supports CIA tempo commands.
Created Quadrascope and Note Scroller windows.
Right and middle mouse buttons now work in all windows.
LED (and filter) no longer get turned on at inappropriate times.
Added directory scanning feature to program list manager.
(If you "add" a directory to the program, MultiPlayer scans
it and adds its contents to the program.)
Added volume, balance, and speed controls to main window.
1.15 (17-Jan-92)
Upgraded MED 3.11 player to MED 3.20.
(The MED player also now supports multiple songs).
Added OctaMED 1.00 support.
Fixed a small bug in author search routine.
Fixed SidMon player bug.
Added Spectrogram and Scope windows.
Created non-overlaid version (Player.nov) for registered release.
1.14 (6-Jan-92)
Internal pseudo-release.
1.13 (1-Jan-92)
Added Oktalyzer 8-channel support using my own 8-channel audio engine.
(Never did find a real Oktalyzer 8-channel play routine.)
1.12 (29-Dec-91)
Protracker support added by replacing the NoiseTracker player with the
(similarly modified) Protracker 1.1B player. I haven't detected
any backward incompatibilities with NoiseTracker modules, but
tell me if you find any.
Oktalyzer 4-channel player finally tested and fixed.
(Yep, it didn't work at all. Sorry...)
1.11b (19-Dec-91)
Control panel clock/sequence display now always matches title color under 2.0.
Fixed minor event-handling bug.
1.11a (12-Dec-91)
Fixed bug in 8SVX player.
Window positions are now saved with preferences.
1.11 (10-Dec-91)
Repeat detection bug in ST/NT player fixed.
Program and preferences windows now save their positions while closed.
Enhanced author name detection.
Added middle-mouse-button zoom feature.
Added 'Nothing' option to the show mode in preferences.
Improved Delta Music module recognition.
1.10 (18-Nov-91)
Right mouse button in the main window has changed functions:
Under 1.3, it zooms the window (since there's no zoom gadget)
Under 2.0, it shows the program window (like the Help or F1 key)
File requester is now asynchronous (other windows remain active).
Control panels are now fully 1.3 compatible.
(Although they still don't look as nice as in 2.0...)
Keyboard shortcuts now supported in all control panels.
Added public screen support.
Added "play once" feature.
DMA delays now use scanline waits instead of delay loops.
Re-opening sub windows now closes them rather than bringing them to the front.
Added AppWindow support for 2.0.
1.01 (8-Nov-91)
Added 'Sort' button in program window.
Fixed a serious bug in GMOD player. (Only serious if you have GMOD modules...)
Enhanced author name recognition for ST/NT modules.
1.00 (5-Nov-91)
This is basically a rewrite of most of the program.
(I'm not listing all the additions - there are way too many.)
Major changes and additions to Formats.doc.
Music no longer cuts off when file requester is displayed.
Removed built-in code compression. (Maybe I'll put it back in later.)
Audio device now allocated while playing music.
Fixed SoundFX player bug which caused crashing on advanced processors.
Players now use longer DMA delays (normally 300) only on fast processors.
(Wouldn't want to bog down you poor ol' 68000 users would we?)
Major rewrite of player selection code.
CIAB interrupts now defer to software interrupts to avoid hogging
CPU time in a high-priority interrupt.
0.95a (6-Sep-91)
Fixed bug where song position appeared when no module was playing.
Fixed ST/NT player bug for modules with negative song repeat positions.
0.95 (27-Jul-91)
Added song position indicator for ST/NT and MED modules.
Added code to turn low-pass filter off by default (will soon be selectable).
Added Messages section to the documentation.
Fixed window position so it snuggles right up next to the screen gadgets.
0.94a (26-Jul-91)
Fixed player window height on pre-2.0 operating systems.
Increased delay loop (ugh!) in NoiseTracker player for faster processors.
Fixed song repeat bug in NoiseTracker player.
Hacked NoiseTracker player to play old 15-instrument modules.
Fixed memory trashing bug in NoiseTracker player.
(I hate cleaning up someone else's code!)
0.94 (23-Jul-91)
Uses one of the CIAB timers for timing rather than the VBlank interrupt.
Finally uses Workbench 2.0 ASL file requester if available.
Added MED 3.xx modules, removed MED 2.xx songs.
0.93 (3-Jul-91)
Workbench 2.0 compatible (although some modules may not be).
0.92 (7-Jun-91)
Added 'AMOD' absolute loading module format described in 'Formats.doc'.
Added 'GMOD' general module format described in 'Formats.doc'.
Added NoiseTracker 1.3D packed (with player) modules.
Added StarTrekker 1.2 AM synthesized modules.
Updated the SoundTracker/NoiseTracker player.
(New player comes from NoiseTracker 1.3D)
0.91 (29-Apr-91)
Added 'XMOD' format described in 'Formats.doc'.
Removed "unknown" module formats (turned those modules into XMOD's)
0.90 (27-Apr-91)
First preliminary release. Nothing fantastic.
Registration
~~~~~~~~~~~~
MultiPlayer is Shareware. For the small price of $15 you will get the
registered version of MultiPlayer which allows loading and saving of
programs (module lists), as well as the full-featured ARexx port described
earlier in this document (useful for playing modules with AmigaVision and
the like). Of course, you also gain my favor - suggestions for
improvements will be taken much more seriously from registered users.
I'm planning to release the source code to MultiPlayer eventually.
However, it uses many of my library routines that I have not released yet
(though I'm planning to when I have the chance), so it will have to wait a
while. The source code will probably be available with a $30 registration
fee (or an additional $15 for users who have already paid the $15
registration fee). How hard I work on getting my library routines cleaned
up and released, and therefore how soon I get MultiPlayer's source code
released, depends a great deal on how much support I get for MultiPlayer.
Contact Address
~~~~~~~~~~~~~~~
I tend to move around a great deal, so mail sent directly to me
sometimes has a hard time catching up. If you want mail to reach me (it
may take a while, but it WILL reach me), send it to this address:
Bryan Ford
8749 Alta Hills Circle
Sandy, UT 84093
I can be reached more quickly (for the time being anyway) on the phone
or through one of the electronic mail addresses below:
(801) 585-4619
bryan.ford@m.cc.utah.edu
baf0863@cc.utah.edu
baf0863@utahcca.bitnet
If you want to get something to me through the mail more quickly, FIRST
call or E-mail me to make sure I'm still here, then send it to this
address:
Bryan Ford
27104 Ballif Hall
University of Utah
Salt Lake City, UT 84112