DP Tool Club 12/CD_ASCQ_12_0294.iso/vrac/dmplay99.zip/DMPLAYER.HLP

OS/2 Help File | 1994-02-08 | 40KB | 771 lines

ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ

                              Digital Music Player
                             Copyright (c) 1994 Aria
                               All rights reserved

Digital Music Player is a multi-threaded MOD format music module player for
OS/2 2.x with the MMPM/2 multimedia extensions installed.  A digital capable
audio adapter is required.  DMPlayer has been designed to work well with you.
It is capable of playing songs in the background while you get real work done
with a minimum of interruption (aside from the wonderful music of course).  You
will be able to listen to your favorite modules and still have a responsive
system at your fingertips.  DMPlayer will play modules compressed with your
favorite archiver, such as zip, zoo or gzip.  Multi-file archives are not
supported.  You can create and save list of your favorite modules.  These
SongLists can be saved to be loaded at a later date.  DMPlayer even
(optionally) cooperates with the system sounds provided by MMPM/2.

Digital Music Player remembers a lot of things between sessions.  Such as which
windows were open and where they were positioned as well as all of the settings
and even the last SongList that was opened!  This makes using the program
easier each time you run it.  You even have the option of starting DMPlayer
minimized as well as automatically starting to play the loaded SongList.

Digital Music Player is currently capable of playing the following formats:

o 4 track, 31 and 15 instrument Protracker/Noisetracker modules
o 4 and 8 track Startrekker modules
o 6 and 8 track Fasttracker modules


ΓòÉΓòÉΓòÉ 2. Ariaware ΓòÉΓòÉΓòÉ

This software product is provided to you for the sole purpose of evaluation
prior to purchase.  DMPlayer is not free.  You are granted license to a trial
evaluation period of 30 days in which to determine if you wish to continue
using the program.  If you decide to use DMPlayer after the 30 day trial
period, you must pay the registration fee of $20  (US).  Any use beyond the 30
day trial period is prohibited by law.  Please go to Registration for more
information on how to register.

Digital Music Player is (c) 1994 Aria. All rights reserved.


ΓòÉΓòÉΓòÉ 2.1. Limitations ΓòÉΓòÉΓòÉ

If you have not registered DMPlayer, then you will have to face up to a few
limitations.  These limitations are critical, however, they do not interfere
with the evaluation of the program.

The current limitations are as follows:

 1. Inability to save settings between sessions.  Normally, DMPlayer would
    remember window positions, audio settings, playback settings and
    directories accessed.

 2. Inability to load or save SongLists.  All other aspects of the SongList
    window are fully functional.

I hope that you do not find that these limitations are too restrictive.  You
should still be able to determine whether or not you wish to use the program
even with these restrictions.

Due to these limitations, many people may quickly dub this software as
'Crippleware' or the like.  Be that as it may, I have made a serious investment
in the development of DMPlayer and I must protect that investment.  I have
tried to do so in the most benign manner possible.


ΓòÉΓòÉΓòÉ 2.2. Registration ΓòÉΓòÉΓòÉ

When you register DMPlayer, you will receive a keyfile unlocking the full
functionality of the program.  The one time registration fee will provide you
with free upgrades for the life of this program.  Both minor and major upgrades
will be made available via your favorite OS/2 shareware distribution site.  All
future versions of this program will automatically be unlocked by the keyfile
you will receive.

There are two ways to receive your keyfile:

 1. Slooooow, snail mail

 2. Faaaaast, electronic mail

The default action for me is to return your keyfile through the mail system.
You and I both would probably rather I returned your keyfile through email if
at all possible.  I will do this on the condition that I receive some form of
proof of address of the mailing address you send to me.  Here are some examples
of this proof:

 1. Personal check.  If you write me a check, then it probably has your address
    on it and that is proof enough for me.

 2. Address label (or photocopy) of some piece of mail addressed to you at the
    given address.  Such as a power bill or something.

 3. Photocopy of some ID card with your name and address on it.

 4. Several other things that I can't think of.  As long as your name and
    address appear on something official, it will do.

Pretty simple, eh?  If you provide one of the above, then I will get the
keyfile emailed out to you the day I receive your registration.  If you don't,
then I'll put the keyfile on a disk and mail it to you as soon as I can.  You
just can't beat that!

Print the REGISTRATION FORM to order your copy of Digital Music Player.


ΓòÉΓòÉΓòÉ 2.3. REGISTRATION FORM ΓòÉΓòÉΓòÉ

Send this form to:

     Aria
     P.O. Box 1889
     Corvallis, OR  97339-1889

Price             $ 20.00 (US)

Free upgrades for the life of the program!

 o  Please send a Check or Money Order to the address above.
 o  Make Checks and Money Orders out to Aria.
 o  Credit cards are not accepted at this time.
 o  Please do not send cash.
 o  All orders must be in US Dollars.
 o  No COD's.

The following information will be encoded in the keyfile sent to you.
Please print or type. Failure to provide complete and accurate information
will result in your order being delayed or possibly not processed.

Name   ________________________________________


Mailing  ________________________________________
Address
     ________________________________________

     ________________________________________

     ________________________________________

     ________________________________________


Email   ________________________________________


Phone   ________________________________________
(Optional. May help if there is a problem.)

Disk   ___ 3.5"  ___ 5.25"

Comments:


ΓòÉΓòÉΓòÉ 2.4. Support ΓòÉΓòÉΓòÉ

DMPlayer is an evolving product.  Support for other module formats may become
available in the future.  More functionality may be added at some later date.
All of which is free to registered users.  Support is made available via the
internet.

Mail questions and/or comments to:

  [e-mail]
  [e-mail]

You can always find the newest version of Digital Music Player on the ftp site:

ftp.cdrom.com


ΓòÉΓòÉΓòÉ 2.5. Distribution ΓòÉΓòÉΓòÉ

Digital Music Player may be freely distributed provided that the entire archive
remains intact.  Shareware distributors may not charge more than $5 (including
shipping) for this software package.


ΓòÉΓòÉΓòÉ 2.6. Warranty ΓòÉΓòÉΓòÉ

No warranty of any kind is implicitly or explicitly granted through use of this
program.  Aria will not be held liable for any damages resulting form the use
of this product.


ΓòÉΓòÉΓòÉ 3. Installation ΓòÉΓòÉΓòÉ

Digital Music Player needs no special setup.  Simply copy the program file
'DMPlayer.EXE' into a directory and create a program object if you desire.  You
should copy the help file 'DMPlayer.HLP' into a directory that is in your help
path.  DMPlayer can be placed anywhere.  It will search for, or create any
files that it needs in the directory where the executable is.  This will allow
DMPlayer to be run from the command line without cluttering your file system
with DMPlayer.INI files.

When you register you will receive the keyfile 'DMPlayer.KEY'.  This file
should be placed in the same directory as 'DMPlayer.EXE'.


ΓòÉΓòÉΓòÉ 4. Running DMPlayer ΓòÉΓòÉΓòÉ

DMPlayer will accept MOD files from the command line.  DMPlayer understands the
standard OS/2 wildcard system for selecting files.  You can specify as many
files as you like on the command line:

      DMPlayer CoolSong.mod
      DMPlayer mod.* *.mod

DMPlayer will create a new songlist containing all the files specified on the
command line.

DMPlayer may also be associated with all of your MOD files for even better
integration with the WPS.


ΓòÉΓòÉΓòÉ 5. Using DMPlayer ΓòÉΓòÉΓòÉ

The functionality of Digital Music Player is spread throughout several
different dialogs and windows.  This allows DMPlayer to take up as little or as
much screen space as you desire.

                                 The Main Dialog
                              The Settings Notebook
                               The SongList Window
                                The Mixer Dialog
                              The Song Info Dialog


ΓòÉΓòÉΓòÉ 5.1. The Main Dialog ΓòÉΓòÉΓòÉ

Select a control on the DMPlayer main dialog and Double-Click (or press Enter)
to see more information about that control.

Digital Music Player has been designed to be as useful as possible and yet to
be as unobtrusive as possible at the same time.  Needless to say, it was also
designed with good looks in mind.  The main dialog, pictured above, displays a
lot of information about what is happening at any time.  The dialog was
designed to somewhat resemble a CD player just so you would be vaguely familiar
with the interface from the start.  The controls will act very similarly to
their real-world counterparts.  You should be set to go!

If you have not done so yet, you may want to take the time to double-click on
all the controls on the dialog shown above.  You will see control specific
information in a window with more details about what is happening and why it
may be happening.


ΓòÉΓòÉΓòÉ 5.2. The Settings Notebook ΓòÉΓòÉΓòÉ

The Settings Notebook contains all of the options relative to the loading and
playing of music modules.  The notebook is an elegant way to combine multiple,
diverse settings in one, simple and easy to use control.

There are 4 pages in the notebook:

 1. The Audio Quality page has settings relating to the quality of the playback
    of the module.

 2. The Load Control page has settings relating to keeping the system
    responsive while still providing flawless, continuous playback.

 3. The Decompression Methods page has settings relating to the decompression
    of compressed module files.

 4. The System Integration page has settings relating to how DMPlayer acts.


ΓòÉΓòÉΓòÉ 5.2.1. Page 1 - Audio Quality ΓòÉΓòÉΓòÉ

There are three settings that directly affect the quality of the audio data
that is played:

Frequency

This slider controls the output frequency of the audio.  Values range from
11025hz up to CD quality 44100hz.  Some audio adapters may not be able to
handle some frequency values.  DMPlayer will notify you if you attempt to play
a song at a frequency that is not supported by your audio adapter.  The higher
the frequency is set, the better the song will sound as higher frequencies can
be reproduced.  Also, the higher the frequency, the more processor time
DMPlayer needs to create the data.  So there is a tradeoff to be made between
the quality of the sound and the responsiveness of the system.

Bits per sample

You can select either 8 or 16 bits per sample playback.  16 bits per sample
will result in better output quality.  8 bits per sample will result in poorer
output quality due to the scaling required to adjust the audio data to 8 bit.
This setting will have a negligible effect on the processor load.

Note:  Not all audio adapters support 16 bits per sample.

Number of channels

You can select either mono or stereo playback.  Stereo playback sounds vastly
better than mono playback.  This setting will have a negligible effect on the
processor load.

Note:  Not all audio adapters support stereo playback.


ΓòÉΓòÉΓòÉ 5.2.2. Page 2 - Load Control ΓòÉΓòÉΓòÉ

Thresholds

Digital Music Player uses a dynamic priority adjustment scheme to integrate
smoothly with other running applications.  The Play thread of DMPlayer normally
runs at the default OS/2 priority.  That means that it's execution is no more
important than any other application running at the same time.  This means that
other applications are free to work and respond as if DMPlayer does not exist.
If there are other applications running with a higher priority, then DMPlayer's
Play thread will begin to slow down as OS/2 gives more and more processor time
to the higher priority task.  DMPlayer will allow this to happen only until it
reaches a user-definable point, called the Lower Threshold.  Once this point is
reached, DMPlayer will raise the priority of the Play thread in order to allow
it to catch back up.  As DMPlayer receives more of the processor time, the Play
thread will eventually reach another user-definable point, called the Upper
Threshold.  At this point, DMPlayer will once again lower the priority of the
Play thread back to the OS/2 default.  This process allows DMPlayer to keep
playing uninterrupted music while your other, often more important tasks, get
the processor time to do what they must.

The Upper Threshold is labeled Raise priority at on the notebook page.  This
value represents a percentage of the buffer that must remain filled with data
ready to be played.  If the buffer drops below this level, then the priority of
the play thread will be raised to attempt to refill the buffer.

The Lower Threshold is labeled Lower priority at on the notebook page.  This
value represents a percentage of the buffer that must be reached before the
priority of the play thread will be lowered again.

Number of buffers

The number of buffers selected will determine just how much create-ahead buffer
space there is.  The more buffers there are, then the more space there is for
error.  If your system will allow it, then a higher setting is better. This
will allow a greater range when DMPlayer doesn't care just how full the buffer
is.  If your system has little memory, then fewer buffers may be selected to
help a little.  Lower numbers of buffers are more likely to encounter skipping
problems when under a heavy system load.

The amount of memory used by the selected number of buffers is also displayed.


ΓòÉΓòÉΓòÉ 5.2.3. Page 3 - Decompression Methods ΓòÉΓòÉΓòÉ

Digital Music Player supports the reading of music modules from a single-entry
compressed file.  It does not support more than one file in an archive file.
This means that you can use zip or gzip or whatever your favorite archiver is
to compress all your modules and possibly save a significant amount of disk
space.  Modules will typically compress by about 33% from my experience with
both zip and gzip.  The decompression is transparent to the user, DMPlayer just
matches a method with a mask.  DMPlayer supports up to 6 user-definable
decompression methods.

Extension

Simply enter the extension that you wish DMPlayer to match with the method
given in the Execute command field.

.gz

Execute command

Here is where you enter the command you wish to be executed if DMPlayer matches
the extension specified.

gzip -d -c

The command must conform to the following specifications:

o It must emit the decompressed module to standard output (stdout).
o It must not output any header of any kind.

Shell

You need to enter the command shell you wish DMPlayer to use when executing the
decompression commands.  Some shells will introduce unwanted control characters
to standard output.  4OS/2 will do this if the StdColors command is used in the
4OS2.INI file. It is recommended to set this field to:

[BOOTDRIVE]:\OS2\CMD.EXE


ΓòÉΓòÉΓòÉ 5.2.4. Page 4 - System Integration ΓòÉΓòÉΓòÉ

Share audio device

Note:  These settings only take effect when DMPlayer is started.

If this item is checked, then DMPlayer will share the audio device with other
applications.  This will allow you still hear system sounds when DMPlayer is
running.  Whenever another application, such as the WPS (for system sounds),
requests the device, then DMPlayer will halt playing until the device is handed
back.  This behavior may not be desirable for every configuration, so it is
optional.

Startup minimized

If this item is checked, then DMPlayer will start up minimized.  This option is
especially useful when used in conjunction with the next option.

Startup playing

If this item is checked, then DMPlayer will begin playing the first song from
the playlist with it first loads up.


ΓòÉΓòÉΓòÉ 5.3. The SongList Window ΓòÉΓòÉΓòÉ

If you have used a folder on the WPS, then you will feel right at home using
the SongList container.  The SongList allows you to view the list of modules in
any of the standard formats:  Icon, Text, Name, or Details view.  This way, you
can see what you want to, the way you want to.

Drag and drop is also fully supported.  Both as a means of re-arranging the
order of the list and adding files to the list.  You can drag files from any
WPS folder and drop them in the list where you want them.  DMPlayer will allow
you to drop ANY type of file, but I do not suggest exploiting that capability.

The order of the list is completely left up to you.  If you start dragging a
file (or files), then there are several places you can drop them:

 1. Directly on another item.  This will result in the items being inserted
    before the target item.

 2. Between other items in the Text, Name or Details view.  This will result in
    the items being inserted between the target items.  This is not an option
    in the Icon view.

 3. On the container itself.  This will result in the items being inserted at
    the end of the list.

It's really simple.  Just play with it and you will soon understand.

There are three different popup menus available.  Each one will appear with you
press the context menu button on your mouse.  This defaults to the right mouse
button.

o SongList Main Menu

  This menu will popup over the SongList itself.  It contains all of the
  commands relevant to the entire SongList.

   - New

     Start a new SongList from scratch.

   - Open

     Open a SongList.  This will bring up the standard file dialog to select a
     SongList to load.

   - Save

     Save the current SongList.

   - Save as

     Save the current SongList with a new name.

   - Add songs

     Add songs to the current SongList.  This will bring up the standard file
     dialog where you can select multiple files to add to the list.

   - View

     There are several ways in which to view the contents of the SongList. Each
     view shows the song title, not the file name.

      o Icon

        Select the Icon view.

      o Text

        Select the Text view.  If the Flowed menu item is checked, then the
        view will be Flowed Text.

      o Name

        Select the Name view.  If the Flowed menu item is checked, then the
        view will be Flowed Name.

      o Details

        Select the Details view.  This view also shows the following
        information abou the song file:

         - Full pathname of the song file.

         - Size of the file in bytes.

         - Creation date.

         - Creation time.

      o Flowed

        Check this menu item if you wish the Text and Name views to be flowed.

   - Select

      o Select all

        Select all the items in the SongList.

      o Deselect all

        Deselect all the items in the SongList.

   - Sort

     The items in the SongList can be sorted several different ways.  This menu
     item is a conditional cascade.  To reorder the list using the previously
     selected sort method, simply select 'Sort'.  To change the sort method,
     cascade the menu and select a new method.  The selected method is saved
     between sessions.

      o Name

        Sort by the title of the song.

      o Size

        Sort by the size of the file.

      o Date

        Sort by the creation date of the file.

      o Random

        Randomize the order of the list.  If this method is selected, then the
        SongList will automatically be randomized whenever it is loaded.

o Single Item Menu

  This menu will popup when only one item is selected.

   - Play

     Play this song.  A song may also be played simply by double-clicking on it
     in the list.

   - Remove

     Remove this song from the list.

   - Delete file

     Delete this song from the disk as well as removing it from the list. You
     will be asked to confirm.

o Multiple Items Menu

  This menu will popup when several items are selected.

   - Remove

     Remove these songs from the list.

   - Delete file

     Delete these songs from the disk as well as removing it from the list. You
     will be asked to confirm.


ΓòÉΓòÉΓòÉ 5.4. The Mixer Dialog ΓòÉΓòÉΓòÉ

This dialog allows you to adjust a few of the mixer settings for your audio
card.  Some audio cards do not support the modification of these settings, see
Hardware issues for more information.  The settings will not be disabled if
even if your audio adapter does not have a software settable mixer.  This is
due to a limitation in the MMPM/2 API.  These settings only affects DMPlayer's
output.

You can adjust the Volume, Balance, Bass and Treble if your card supports the
setting of these values by software.


ΓòÉΓòÉΓòÉ 5.5. The Song Info Dialog ΓòÉΓòÉΓòÉ

This dialog displays more detailed information about the song currently loaded.
It displays the song title, type of the song, number of channels (tracks), the
actual file name, and a list of the samples contained in the file.


ΓòÉΓòÉΓòÉ 6. What is a MOD file? ΓòÉΓòÉΓòÉ

A MOD file is a digital song file.  The format was developed on the Amiga
family of computers to take advantage of that machines 4 DACs (Digital to
Analog Converters).  The file contains blocks of commands for each track.  Each
command tells what instrument to play and at what note to play it.  Special
effects are also specified by the commands.  The instruments are stored as
samples at the end of the track information.  Hence the rather large size of
MOD files.  The format originally consisted of only 4 tracks and 15
instruments.  It has since evolved to anywhere from 4 to 8 tracks and 31
instruments.  A 'standard' MOD file now has 4 tracks and 31 instruments.  Some
trackers produce 6 and 8 track MOD files with 31 instruments.

One of the best places to find MOD files is at an Aminet site.  There is an
Aminet mirror at:

ftp.cdrom.com

Relevant directories are:

aminet/mods/misc
aminet/mods/pro


ΓòÉΓòÉΓòÉ 7. Hardware issues ΓòÉΓòÉΓòÉ

One might think that the advent of MMPM/2 introduces the age of pure hardware
independence.  While MMPM/2 goes a LONG way in doing that, there will still be
problems rising from the fact that SOMEONE has to write device drivers for each
audio adapter out there.  And while these drivers do exist, there remains a lot
to be desired.  So, while DMPlayer SHOULD work just fine with any MMPM/2
supported audio adapter, there may still be some things to look out for.

o Pro Audio Spectrum (Studio) 16
o Sound Blaster family


ΓòÉΓòÉΓòÉ 7.1. Pro-Audio Spectrum (Studio) 16 ΓòÉΓòÉΓòÉ

In order to listen to 16 bit audio, you may need to set the DMA channel 5 or
above. All lower channels only support 8 bit (at a time) DMA and seem to cause
problems when doing 16 bit audio under MMPM/2.


ΓòÉΓòÉΓòÉ 7.2. SoundBlaster family ΓòÉΓòÉΓòÉ

There don't seem to be any specific problems with this card, but there have
been many reports of seeming 'random' crashes that are impossible to track
down.  My only hope is that Creative Labs will better support these cards in
the future.

If you are having terrible problems with your SoundBlaster you may want to make
the following change to the device driver statement in CONFIG.SYS:

DEVICE=SB16D2.SYS 1 5 5 220 8 "$SBAud1"

The 8 should be replaced with a 2.


ΓòÉΓòÉΓòÉ 8. Thanks ΓòÉΓòÉΓòÉ

Thanks go out to the following people for doing some serious late night bug
hunting:

   Adrian Idzik
   Linden deCarmo
   Dave Killian
   Chance Geurin

Special thanks to Linden deCarmo for all his support and answered questions
about the innermost workings of MMPM/2.  You guys did a great job with MMPM/2
Linden!  Thanks for all the help and answered questions and bug reports and
moral support and etc...

Thanks to my other early beta testers. You all helped out!

Thanks also goes out to Kathleen Panov, Larry Salomon (aka Q) and Arthur Panov
for their work on the wonderful 'The Art of OS/2 2.1 C Programming'. It is an
absolutely GREAT book and a MUST-HAVE for any OS/2 programmer.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Press this button to start playing the currently loaded song.  If no song is
loaded, then DMPlayer acts as if you pressed the Next button.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Press this button to pause the playback of the song.  If the song is currently
paused, then DMPlayer acts as if you pressed the Play button.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Press this button to stop the playback of the song.  The song remains loaded
into memory at this point.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Press this button to move 1 track back in the song.  There will be a slight
delay before the change takes effect.  Rapid pressing of this button will have
no further effect.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Press this button to move 1 track forward in the song.  There will be a slight
delay before the change takes effect.  Rapid pressing of this button will have
no further effect.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Press this button to load the previous song from the SongList.  If the SongList
has changed, or a new SongList has been loaded, then the song DMPlayer loads
may be just about anything in the list.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Press this button to load the next song from the SongList.  If the SongList has
changed, or a new SongList has been loaded, then the song DMPlayer loads may be
just about anything in the list.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The name of the currently loaded SongList is displayed here.  This is also
where messages from the SongList window will appear.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

The name of the currently loaded song is displayed here.  The song will remain
loaded in memory even if it is deleted from the disk.  Status and error
messages related to the loading and playing of the song will also be displayed
in this window.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

This control displays a percentage that represents the amount of the total
buffer space that has been preloaded with song data.  The percentage shown here
directly relates to the percentages set in the Load Control page of the
Settings Notebook.  This control will turn red if it has dropped below the
Lower Threshold.  It will turn green once it reaches the Upper Threshold again.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

This control displays the currently playing track.  The display is not acutely
accurate.  It will be close enough for our interests however.  The only
inaccuracy is a slight time delay between when the track actually changes and
when the message is sent through MMPM/2 to DMPlayer to get updated.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

This control displays the total number of tracks to be played in the duration
of the song.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

This control displays the total elapsed time that the song has been playing.
The time displayed is unaffected by pressing the Fast Forward or Rewind
buttons.  Therefore, this display may not accurately show the time offset into
the song if the user has skipped around a bit.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Digital Music Player has several threads concurrently running, taking full
advantage of the multitasking nature of OS/2.  The Play thread is the main data
creation thread.  It basically does all of the work of interpreting the song
data and rendering it in an audible form to the buffer for MMPM/2 to read.