═══ 1. Introduction ═══

First off, what is PMsndX?  PMsndX is the acronym that I created to mean 
Presentation Manager sound eXchange. PMsndX was written specifically for OS/2 
to provide the functionality of the SOX sound manipulation program.  The 
advantage to this program over the program is that it fully utilizes the 
presentation facilities of the OS/2 environment.  This program was written to 
provide all of the functionality of SOX while taking advantage the object 
oriented approach offered by C++. The advantage of writing this program from 
scratch is that it is easy to tailor it to OS/2 and C++.  The obvious 
diadvantage is that it does not benefit from the extensive testing that SOX has 
had. 

Obviously if I intended to have this program remain as simply a SOX port to the 
OS/2 environment, I would not have taken the time to rewrite it based on its 
functionality.  The intent of this venture (other than to give me something to 
do during this long icy winter) is to provide a platform for me to use some 
signal processing from my college days to enhance the functions of the program. 

Wow, you are still reading!  Well, now for some information on the user 
interface.  There is nothing more frustrating than trying to use a program with 
a difficult or complex user interface.  Twelve years ago I started programming 
a TI99/4A in assembly language and from the start I have put more effort into a 
clean user interface than anything.  It wasn't till I ran across JOEVIEW that I 
realized that OS/2 could had one of the most capable environments that I had 
seen in a while.  Presentation Manager programming has got to be one of the 
easiest environments use and is a breeze compared to Windows or the X 
environment. 

In any case, I spent more time on the user interface of this program than I 
ever thought possible.  It is designed around a single coordinating window 
populated by bitmaps.  Each bitmaps has some sort of image that might change 
when the button is pushed.  To make sure that the literate people out there (or 
the icon impaired) understand the buttons too, I put a bit of text on them too 
to describe the function. 

Now, I have used programs on a lot of platforms and I have my favorites and the 
more annoying ones too.  My pet peeves are the applications like Procomm for 
Windows which just assumes that you want the darn thing to fill up your screen. 
Or something like Microsoft Word which has so many menus and submenus that it 
is hard to remember where a function is.  So, taking this into account, I 
designed the interface such that the main functions of the program are 
accessible from the main pannel.  Pressing the button for the function will 
then bring up a dialog box which asks the user for the necessary information. 
Pushing the button again will remove the dialog box.  I prefer this interface 
because it provides a single point of control.  Well, you just need to play 
with it for a bit to get an understanding of what I am talking about here. 


═══ 2. Conventions ═══

Throughout the documentation provided with PMsndX a number of terms are used 
which may be common to Presentation Manager programs but uncommon to 
conversational English.  There are also terms which are specific to PMsndX 
which may be new to a user of this program.  The intent of this section is not 
to recreate the OS/2 documentation; rather, it is intended to identify some 
basic terms necessary to understand the language used in this documentation. 

Presentation Manager: 
   The Presentation Manager is the Graphical User Interface (GUI) for most OS/2 
   systems.  There are other GUIs available for OS/2 but this is the most 
   common and the one that comes with OS/2 out of the box.  In general mose 
   people refer to the Presentation Manager by the acronym PM. 

SYSTEM MENU: 
   Every PM program for OS/2 generally provides a SYSTEM MENU through an icon 
   in the upper left corner of the window interface to the user.  By default, 
   the system menu will contain the basic functions necessary to control the 
   window for on the OS/2 PM desktop. 

TITLE BAR: 
   In order for a window to be moved about the desktop with the mouse, a window 
   must have a titlebar.  This is the thick bar at the top of the window.  The 
   titlebar provides another function in that it allows the program to display 
   relevant messages to the user. 

MINIMIZE BUTTON: 
   A PM program may provide various control buttons for a window in the top 
   right corner of a window.  One of these buttons is the MINIMIZE button. When 
   the user selects this button, the window will be removed from the desktop 
   and replaced by a small icon somewhere on the screen.  In most cases, the 
   icon is placed at the bottom of the screen.  To restore the window the user 
   can double click on the icon or can use a mouse button to bring up a menu 
   and select Restore. 

MAIN CONTROL PANEL: 
   The main control panel for PMsndX is the window that is initially displayed 
   when the program is executed.  This window is the main point of control for 
   the program and provides access to all of the above mentioned controls as 
   well as access to all of the functions of the program. 


═══ 3. Mouse Pointer ═══

The mouse pointer is used as an indication to the state of the program.  When 
the program is processing, the mouse pointer will be changed to a small dial 
with 10 markers on the dial.  The percentage of work completed is then 
displayed as the work is done.  When the dial reaches the vertical position, 
the work will be complete. 

There is one exception to this operation.  When the echo effect is used, the 
dial on the pointer will rotate more than once. This is because the results of 
the echo effect change the length of the data depending on the markers and 
volumes such that the resulting length is unpredictable.  The dial will turn 
for twice as the samples increases to another multiple of the initial sample 
length. 


═══ 4. System Menu ═══

As with any OS/2 program written for the Presentation Manager, this PMsndX has 
an icon in the top left corner of the control window.  Pressing this icon will 
bring up a menu of system operations.  With the exception of the About menu 
item, each of the functions of the system menu may be performed without using 
the menu through some other means provided by this program.  However, the 
system menu has been provided to allow the program to be used without a mouse 
if necessary. 

The menu items provided in the system menu are: 

Restore   Restore the windows after being minimized 
Move      Move the control window 
Minimize  Minimize all of the windows of PMsndx to an icon 
Close     Close the all windows and exit 
About     Display information about the author and version 
Help      Bring up the help system 


═══ 4.1. Restore ═══

During the use of PMsndX, the user may select to Minimize the windows to an 
icon on the desktop.  To restore the window from the icon the user may either 
double click on the icon or may press a mouse button while the pointer is over 
the icon to bring up the system menu and select the restore item. 


═══ 4.2. Move ═══

PMsndX provides the standard controls for moving the windows around on the 
desktop.  It is generally easiest to use the mouse to select the titlebar of 
the window and drag the window to the new location.  If the user uses the 
system menu to move the window, the mouse will be centered in the control 
window and any movement of the mouse will move the window until a mouse button 
is pressed. 

Note:  The system menu is only provided on the control window an the Help 
       window.  None of the dialog boxes for the various buttons provide a 
       system menu since it would only have two options (i.e. move and close). 


═══ 4.3. Minimize ═══

All of the windows of PMsndX can be minimized quickly by either selecting the 
minimize button on the upper right corner of the control panel or by using the 
Minimize menu item of the system menu.  Either action performs the same 
function.  The minimize operation is only provided on the control window.  The 
dialogs cannot be individually minimized and are removed from the screen 
through either one of the dialog action items (i.e. Load, or Dismiss) or 
through the buttons of the main control panel. 


═══ 4.4. Close ═══

To exit PMsndX the user can select the Close menu item from the system menu. 
This is the default selection of the menu which enables the user to double 
click on the PMsndX icon in the top left corner of the control panel to exit 
the program.  The user may also use the Exit button on the control panel to 
perform the same function. 


═══ 4.5. About ═══

To find out the current version and other information about PMsndX the About 
menu item can be selected from the system menu. 

PMsndX is just one of the programs written by the Author for Intel based 
machines.  All programs developed under the WiSHware Inc. name have been 
developed solely by the author (duhh, the Author is the sole member of the 
company) and are copyrighted by US Copyright laws. 

Note:  This is the only item on the system menu for which there is no other 
       means to access. 


═══ 4.6. Help ═══

Selecting this option from the system menu performs the same function as 
pressing the Help button on the main control panel.  This brings up the only 
line help system for PMsndX. 


═══ 5. Buttons ═══

The main control panel provides the user with access to all tools and functions 
trough a set of buttons.  Each button contains an icon and a single word which 
describes the function of the button. The buttons have been designed as toggle 
type push buttons.  To select a particular button, the mouse must be positioned 
over the button and the first mouse button pressed.  This will depress the 
button and activate a dialog for the desired function.  The dialogs will 
present information to the user about the desired operation and request input 
from the user to complete the operation. 

The control panel is the main point of control for both activating and 
deactivating a particular function.  The dialog boxes can be removed from the 
screen by positioning the mouse over a depressed button and pressing the first 
mouse button.  The dialog box will be removed and the button will return to the 
non-depressed position. It is important to note that when a dialog box is 
removed through this means, any information in the dialog is ignored and the 
function is canceled.  For each dialog box, the user must enter all of the 
information required and then select the appropriate action on the push buttons 
at the bottom of the dialog box. The dialog boxes do not have system menus so 
that user cannot close the box from a menu as can be done with the main control 
panel.  Dialog boxes may also be removed once valid information has been 
obtained from the user or when the user dismisses or cancels the operation of 
the box. 

Now for the buttons.  There are six buttons on the main control pannel.  These 
are listed below with a brief explanation of their function. 

Open      Opens and reads a new sample file 
Save      Saves the current sample to a file 
Help      Displays general help about PMsndX 
Tools     Displays a notebook of tools 
Settings  Displays options to save between sessions 
MMPM      Use MMPM to manipulate a sample 
Exit      Exit PMsndX 


═══ 5.1. Open ═══

The dialog box for opening a file and reading the sample into memory is 
accessed from the OPEN button on the main control panel.  When reading in a 
file, PMsndX will attempt to open the file as the type indicated by the 
extension on the filename.  However, in the event that the file cannot be 
loaded by the extension, PMsndX will automatically try to determine the type of 
the file as it reads it.  If the sample header does not match any of the known 
header types, PMsndX will refuse to load the file.  If the extension specified 
for the file does not match any of the known extensions, PMsndX will 
automatically try to determine the file type by reading the header. 

This dialog box requests the user to provide a  Filename, Drive, File Type, 
Directory, Files, and Save Directory.  Additionally, the user may select Load, 
Dismiss, or Help to manage the dialog box. 


═══ 5.1.1. Open Filename ═══

This is a text input field in which the user may type the name of the file to 
be opened.  The user may specify a full path or just the file name. If a full 
path is specified, the other user input fields will automatically be updated 
accordingly if the path is valid.  If a file name is entered without a 
qualified path, the path displayed in the other input windows will be used for 
the file.  This window is case insensitive and will automatically convert all 
input to upper case. 


═══ 5.1.2. Drive ═══

To change the drive to be displayed for the various user input fields the user 
may use the DRIVE pulldown field.  The current drive (with volume label) is 
automatically displayed in this field.  If the "file Open path" has been 
selected in the Settings dialog box, then this will be set to the last drive 
used.  To change the default drive, the user can use the pushbutton at the end 
of the drive field to display a list of available drives.  Once the user has 
selected a new drive, the system will automatically update the other input 
fields to reflect the contents of the drive. 


═══ 5.1.3. File Type ═══

The user may specify a filter for the types of files displayed in the Files 
input field.  The file types are accessed through a pulldown field.  By default 
all files are displayed.  Once a new file type filter has been selected, the 
Files display is updated with the list automatically. 


═══ 5.1.4. Directory ═══

By default the last directory used to open a file will be displayed in this 
entry field.  The user may select a new directory by positioning the mouse over 
the desired directory and either double clicking the mouse.  If the "file Open 
path" has been selected in the Settings dislog box, this field will display the 
path used at the last session.  If no previous file path has been saved, then 
this will display the current directory. 


═══ 5.1.5. Files ═══

To select a file from the list of files displayed in the FILES entry field, the 
user can position the mouse pointer over the desired file name and double click 
on the first mouse button.  The Open Filename field is then automatically 
updated to reflect the new file name. 


═══ 5.1.6. Save Directory ═══

This is a checkbox to allow the user to save the current open path between 
sessions without having to open the Settings dialog box.  When this box is 
selected, if the Load button is selected, the specified directory path will be 
saved when the program has been exited.  If the Save Directory is deselected 
before the program is terminated, the path will not be saved.  All file paths 
are remembered during each session and the SAVE DIRECTORY box allows the user 
to store this path between session. 

Note:  The file path is not saved until the program has been terminated. 


═══ 5.1.7. Load ═══

Once the necessary information has been entered by the user to specify a valid 
file name and path, the user may select the LOAD button to load the file into 
memory.  If the dialog box is dismissed in any way other than through the LOAD 
button, the file will not be loaded into memory. 


═══ 5.1.8. Dismiss ═══

At any time when the OPEN dialog box is displayed the user may select the 
DISMISS button to cancel the Open operation.  When this button is selected, the 
operation is canceled and the file is not loaded, but the information in the 
windows is maintained.  If the Save Directory button has been checked, the 
specified directory is NOT saved between sessions. 


═══ 5.1.9. Help ═══

To display help specifically for the OPEN dialog box, select the HELP button. 
The help page for the box will be displayed. 


═══ 5.2. Save ═══

The dialog box for saving a file to disk is accessed from the SAVE button on 
the main control panel.  When saving a file, the extension of the file will 
automatically determine the type of output to write for the file (e.g. if the 
extension entered by the user is .wav, then the file will be saved in WAVE 
format.) or the user may override the file type by selecting one of the buttons 
for the type of file. 

This dialog box requests the user to provide a Filename, Drive, File Type, 
Directory, Files, Format, and Save Directory.  The dialog box also provides OK, 
Cancel, and Help buttons to control the dialog box. 


═══ 5.2.1. Save Filename ═══

This is a text input field in which the user may type the name of the file to 
be saved.  The user may specify a full path or just the file name. If a full 
path is specified, the other user input fields will automatically be updated 
accordingly if the path is valid.  if a file name is entered without a 
qualidifed path, the path displayed in the other input windows will used for 
the file.  This window is case insensitive and will automatically be converted 
to upper case. 


═══ 5.2.2. Drive ═══

To change the drive to be displayed for the various user input fields the user 
may use the DRIVE pulldown field.  The current drive (with volume label) is 
automatically displayed in this field.  If the "file Save path" has been 
selected in the Settings dialog box or the Save Directory button has been 
selected in this dialog box, then this will be set to the drive used.  To 
change the default drive, the user can use the pushbutton at the end of the 
drive field to display a list of available drives.  Once the user has selected 
a new drive, the system will automatically update the other input fields to 
reflect the contents of the drive. 


═══ 5.2.3. File Type ═══

The user may specify a filter for the types of files displayed in the Files 
input field.  The file types are accessed through a pulldown field.  By 
default, all files are displayed.  Once a new file type filter has been 
selected, the Files display is updated with the list automatically. 


═══ 5.2.4. Directory ═══

By default, the last directory used to save a file will be displayed in this 
entry field.  The user may select a new directory by by positioning the mouse 
over the desired directory and double clicking the mouse.  If the "file Save 
path" of the Settings dialog box or the SAVE DIRECTORY box has been selected, 
this field will display the path used at the last session.  If no previous file 
path has been saved, then this will display the current directory. 


═══ 5.2.5. Files ═══

To select a file from the list of files displayed in the FILES entry field, the 
user can position the mouse pointer over the desired file name and double click 
on the first mouse button.  The Save Filename field is then automatically 
updated to reflect the new file name. 


═══ 5.2.6. Format ═══

When saving a file, the extension of the file normally determines the format to 
save the file in.  The forseen primary usage of this program will be to convert 
sound samples from one format to another and so this is the default operation 
of this program.  However, the user may specify that the information is stored 
in a particular format regardless of the file extension.  In the event that no 
extension is specified for the file, the PMsndX will automatically save the 
file under the specified name under the format currently selected in the FORMAT 
field.  The available formats for file operations are listed below. If the file 
type of Undefined is selected, then the extension of the file will be used to 
determine the file type. 

APPLE (.aif)   Not implemented 
SUN (.au)      Sun/DEC/NeXT 8 or 16 bit signed data samples or 8 bit ULaw 
               samples. 
MAC (.hcm)     Not implemented 
RAW (.raw)     Not implemented 
RAW (.ub)      Not implemented 
RAW (.sb)      Not implemented 
RAW (.uw)      Not implemented 
RAW (.sw)      Not implemented 
RAW (.ul)      Not implemented 
IRACAM (.sf)   Not implemented 
PC (.voc)      Creative Voice file format, 8 bit unsigned samples 
SAMP (.smp)    Not implemented 
PC (.wav)      Windows or OS/2 8, 16, or 32 bit unsigned data samples 
Undefined      This field cannot be selected by the user.  It is only selected 
               when there is no file in memory at the time that the SAVE dialog 
               box is activated. 


═══ 5.2.7. Save Directory ═══

This is a checkbox to allow the user to save the current save path between 
sessions without having to open the Settings dialog box.  when this box is 
selected, if the OK button is selected, the specified directory path will be 
saved when the program has is terminated. If the SAVE DIRECTORY is deselected 
before the program is terminated, the path will not be saved.  All file paths 
are remembered during each session and the SAVE DIRECTORY box allows the user 
to store this path between sessions. 

Note:  The file path is not saved until the program has been terminated. 


═══ 5.2.8. OK ═══

To save the file to disk, the user must select the OK button.  Exiting the 
dialog box in any other way will not save the file to disk. 


═══ 5.2.9. Cancel ═══

To cancel the save operation without writing the file to disk the the CANCEL 
button is used.  If this button is selected, the current path will not be saved 
when the program is terminated. 


═══ 5.2.10. Help ═══

To display help specifically for the SAVE dialog box, select teh HELP button. 
The help page for the box will be displayed. 


═══ 5.3. Help ═══

PMsndX is equipped with extensive on line help that can be accessed by pressing 
the HELP button from the main control panel.  When this button is selected a 
window will appear which will display the table of contents for the system. 

Links to other text is displayed in a blue-green color and can be selected to 
jump to that description in the text. 


═══ 5.4. Tools ═══

The heart of manipulating the samples is accessed from the TOOLS notebook. 
This method of presentation provides a logical an concise method of accessing 
the different types of manipulations that can be performed on a sound sample. 
some of the pages of the notebook provide information while others let the user 
apply a particular effect on the current sound sample.  A third class of pages 
are used to launch dialog boxes for particular functions which require more 
than the notebook can provide.  The TOOLS notebook can be dismissed by pressing 
the TOOLS button on the main control panel.  The tabs on the notebook provide 
access to the Info, Type, Average, Duplicate, Echo, Band Pass, Low Pass, Rate, 
Speed, Reverse, Vibro, and Volume functions for manipulating the samples. 

Using a notebook to display the TOOLS has some unique presentation advantages. 
Primarily the notebook allows the effects to be displayed in a single dialog 
window.  Since each effect is mutually exclusive of any other tool this 
approach displays the maximum information that the user can utilize at any 
time.  Another approach would have been to develop a dialog box for each tool. 
This approach has the disadvantage that it would require a second control panel 
to select the specific tools.  This would violate the approach of providing a 
single control panel for the user and would necessitate managing a number of 
different windows which could potentially clutter the screen.  The notebook is 
a clean and aesthetically pleasing means for managing the tools. 

The notebook may be navigated by either selecting the tab on the right of the 
book for the desired function or by using the small Plus and Minus buttons at 
the bottom of the notebook.  Using the Plus and Minus buttongs will move 
through the notebook a single page at a time.  The information for each 
function are divided into the following categories. 

The notebook can be displayed regardless of the presense of sample data in 
memory.  When no sample is present, the pages of the notebook will be 
invalidated but can still be viewed. 


═══ 5.4.1. Info ═══

The Info page displays all of the relevant information about the samples 
currently in memory.  This includes the following categories: 

Load Format     One of the formats which the program can save or open (see 
                FORMAT under the Save Dialog). 
Data Type       The default extension for this file format. 
Data Style      SIGNED, UNSIGNED, ULAW, or ALAW 
Channels        Number of channels in the sample 
Sampling Rate   The number of samples taken each second 
Data Size       BYTE (8 bits), WORD (16 bits), LONG (32 bits) 
Samples         The number of samples that make the file 
Comments        Some sample files may contain comments.  Any comments found are 
                displayed in this window 
Byte Order      The natural order of the bytes in each sample.  This field can 
                display either Big Endian or Little Endian 


═══ 5.4.2. Type ═══

The type of the file is determined by the header written to the beginning of 
the file.  See Save for information how the file type is determined when a file 
is saved to disk.  Additionally, the user may use the this tool to change the 
Load Format in the Info page of the tools notebook.  When the file is saved, 
the file format will automatically be set to whatever has been chosen on this 
page of the notebook. 

Each file format utilizes different sample formats for the actual data.  By 
selecting one of the standard formats on this page the info page will show the 
user how the samples will be save.  The fields that are most likely to change 
are the Load Format, Data Type, Data Style, and Data Size. 

Do not be too concerned with trying to use this page as the file format and 
related information will automatically be determined when the file is saved. 


═══ 5.4.3. Average ═══

A sample with an even number of channels may be averaged to produce a sample 
with half the initial number of channels. For example, a sample with four 
channels can be averaged to produce a sample with two channels and a sample 
with two samples can be averaged to produce a sample with one channel. 

Channels may be averaged in three ways.  The simplest is to take the left or 
right channel data as the final data.  A more complex method is to average the 
samples of the left and right to produce a center sample. The results of these 
operations are significantly different and can result in very different output 
samples. 

When a sample contains four channels, it is composed of four sound sources at 
45 degrees in each quadrant.  This corresponds to the Front Left, Front Right, 
Rear Left, or Rear Right.  To average these into two channels the user can 
select to use any of the four channels or to average based on the left or 
right. Each of these results in very different output samples.  The individual 
control of the four channel sound samples is an enhancement to SOX but is 
provided to allow a source sample to be broken into its individual components. 
Have you looked at the page for this effect?  If you have, then you might be 
confused.  The question is, how do you provide the ability to average channels 
from any combination of four possible sources to either one or two possible 
outputs.  The answer that I have implemented is simply a column of check boxes 
for each output channel.  To select or average any combination of the channels 
into either of the output channels, check the box for the channels from the 
source sample.  To aid in this, two radio buttons have been provided which 
enable or disable the selection of check boxes in the second channel depending 
on the number of output channels selected. 

To guide the user, when a radio button is selected the check boxes are 
automatically set to produce the same results as SOX. 


═══ 5.4.4. Dupe ═══

This function will duplicate channels. 

Note:  Not implemented yet. 


═══ 5.4.5. Reverse ═══

This effect allows the user to reverse a section (or all) of a sample. 

To select the entire sample, select the Entire Sample button on the notebook 
page for the reverse effect.  To select a portion of the sample, the user may 
either enter the timemarks for the start and end of the effect or may use the 
mouse pointer in the graphical display to select the start and end. 

If the button for Select Part is pressed, the Start and End fields will be 
enabled. The timemarks must be entered using the format mm:ss.ssss where mm is 
the number of minutes into the sample, and ss.ssss is the number of seconds 
into the sample.  When the entry field is selected with the mouse, the current 
marker will be displayed.  When a new value is entered and another dialog item 
is selected, the display will be updated. 

To select the begin or end of the reverse effect using the display, either 
select the desired marker and drag it to the desired position or simply click 
the new position for the marker.  Mouse button 1 selects the Start an Mouse 
button 2 is used to select the end. It may be necessary to zoom out on the 
sample to view both markers.  The display indicates the current timemarker at 
the left of the display, the current timemark for the position of the mouse, 
and the zoom factor for the display.  The vertical scroll bar to the right of 
the display is used to adjust the zoom factor for the display.  When the mouse 
is used to select part of a sample, the Select Part button is automatically 
selected. 


═══ 5.4.6. Echo ═══

The echo effect will modify a sample to provide attenuation at specific points 
in a sample.  The operator must specify the points where the echo effects are 
to start and an attenuation or Volume for the echo.  The attenuation determines 
the length of time that it takes for the echo to die away.  If the Attenuation 
specified for all of the echo points is greater than 1, then the echo will 
"melt" rather than fading away.  If an attenuation is set to 0 or less, the 
Echo point is ignored.  I found it very difficult to figure out exactly what 
SOX was trying to do here, but the results of the effect seem to be similar. 
When playing with SOX to figure out what it was doing, I found that the echo 
effect was one of the most difficult to get to work because of the complex user 
interface.  Hopefully the echo notebook page will overcome this limitation and 
make this effect simple and understandable. 

The echo effect presents an interesting challenge to the user interface.  How 
do you provide the user with an intuitive method to set the echo locations and 
the strength of the echo from a dialog box?  Well, look at the ECHO notebook 
page and follow along in the explanation of the operation.  This notebook page 
includes a graphical display of the current sample, a text entry field for 
editing (e.g. adding or deleting) time marks, and a volume control for setting 
the strength of the echo. 


═══ 5.4.6.1. Echo Graphical Display ═══

The ECHO notebook is centered around the graph at the top of the page.  This 
display is the primary point of control. However, to allow for a bit more 
direct control, the user may use the entry fields to add and delete echo points 
too. To explain it all, I will start with the graphical display first and then 
lead to the secondary controls. 

Once a sample has been loaded into memory, the graphical display will become 
active.  The display is controlled through two slider bars for the position in 
the sample and for the magnification. The sample is normalized so that the 
largest sample value will hit the limit of the display.  This makes the display 
volume independent but gives maximum clarity of the actual waveform in memory. 
Markers may be added or moved to set the echo points in the waveform.  To aid 
the operator in locating the desired echo point, the display contains a status 
bar for the starting timemark for the sample in the window, the current 
timemark under the mouse, and the magnification factor. 


═══ 5.4.6.1.1. Echo Display Scrolling ═══

To move to the right or left in the display, the horizontal slider bar may be 
used.  Pressing the end arrows moves the display one displayed sample to the 
left or right.  When the slider bar is pressed, the display will move one half 
screen to the right or left.  The user may move the display to a region quickly 
by selecting the slider button and dragging it to the appropriate position. 
The display is immediately updated to display the current position. 

The display area at the bottom of the graph provides a timemark indicator for 
the first sample appearing at the left of the graph.  This provides a reference 
for moving through the data.  The time marker is displayed in the form of 
m:ss.ssss where m is the number of minutes into the sample and ss.ssss is the 
number of seconds into the sample. 


═══ 5.4.6.1.2. Echo Display Zoom ═══

Even the smallest sample contains more data than can fit on the graphical 
display.  For this reason the vertical slider to the right of the graphical 
display is used to adjust the viewing magnification of the samples.  The 
maximum magnification of the samples is determined by the length of the sample 
and is calculated by dividing the total sample length by the largest number of 
data points which may be scrolled through on the display.  The display is 
limited to the maximum size of an signed 16 bit value due to the limitations of 
the signals for the horizontal slider bar. This results in a maximum of 32767 
data points which can be displayed and scolled through. 

Initially, the magnification is set for the maximum displayable.  To decrease 
the magnification (i.e. zoom out) on the sample, move the slider down the bar. 
The arrows on the ends of the bar can be used to increase or decrease the 
magnification in increments of 1.  Selecting between the button and the arrows 
doubles or halves the magnification. If the button is selected, the 
magnification can be set immediately to a value.  Markers are displayed for the 
nearest point in the zoom.  However, markers can only be set on exact multiples 
of the zoom.  Therefore, when trying to move a marker, if it is set at a 
different magnification, it may not be possible to move the marker without 
returning to that zoom.  Essentially, the marker is displayed but cannot be 
selected because that exact sample point is not visible. I considered making 
the mouse select the nearest marker, but this is a point of confusion if many 
markers are displayed at the same location for a specific magnification. 

The current magnification is displayed in the status area of the display in the 
form of "x1/nnnnn" where "nnnnn" is replaced by the current magnification 
number (i.e. number of points represented by a single point on the display). 
If the display says that the zoom is x1/2, then the magnification of the 
display is halved.  If this sounds confusing, then just play with the notebook 
page for a bit to get a feel for the operation of the zoom. 


═══ 5.4.6.1.3. Echo Display Status Bar ═══

Before going on, another area of the display needs to be described.  The center 
number on the status area of the display indicates the timemark for the current 
(or last) mouse position. Whenever the mouse is moved into the display area, 
this number will be updated to indicate the time offset for that particular 
point.  This takes into account the magnification. 


═══ 5.4.6.1.4. Echo Adding Echo Points ═══

Now for the fun part.  To add an echo point to the sample, move the mouse to 
the place where you desire the echo.  The status display will provide a 
reference for the timemark. When the proper position has been selected, click 
the mouse and a blue marker will be placed.  If the mouse is released, the 
marker will be set at that location in the sample.  If the mouse is not 
released, the marker may be dragged across the display. This marker may be 
moved later if necessary by other means too. 

Note:  If at any time the mouse pointer is moved outside of the display before 
       the mouse button is released, the marker will not be set and the blue 
       mark will be erased from the display. 


═══ 5.4.6.1.5. Echo Moving Echo Points ═══

A echo marker may be moved by positioning the mouse pointer over the marker and 
pressing the mouse button.  If the marker is on a multiple of the zoom level, 
it will be selected and will follow the mouse as long as the button is pressed. 
When the button is released, the marker will be placed at that position. 

A marker may be moved to another time delay by entering the desired delay 
directly through the Time Mark entry field. 

Note:  If the mouse is moved off the display area, the marker will be restored 
       to its original position. 


═══ 5.4.6.2. Echo Time Mark entry field ═══

For each marker displayed, the timemark is stored in a Combo Box.  This box is 
like an entry field in that the user can edit the time directly; however, it 
also has a drop down box that can scroll vertically through all of the 
different markers.  This type of box provides a great deal of flexibility for 
the user. 

To add a marker at a specific time, position the cursor in the Timemark box and 
edit the time index.  The format is the same as that used to display the time 
marks in the main display.  Enter the number of minutes followed by the 
seconds.  The granularity of the seonds is on the order of 1/10000 of a second. 
For example, entering 6:54.4253 would accept a time mark at 6 minutes, 54.4253 
seconds.  If a value is entered with is beyond the maximum sample of the file 
or less than 0, then the data is ignored. 

Once the desired time mark has been entered, the user may press the Add button 
to place the marker in the current database.  All timemarks added to the 
display use the volume specified for the last timemark, or 0 if no volume has 
been set yet. 

When the listbox is pulled down for the timemarks, each of the timemarks that 
have been entered are displayed in a vertically and horizontally scrollable 
window.  Up to 32 markers may be placed in the file and any markers which are 
unused are displayed with the word "EMPTY".  The markers are placed in the 
database in the order that they are entered unless a free slot is open (from 
being deleted).  The user may select any of the time marks using the combo box. 
If the selected timemark is not empty, the the display will be updated to 
display the selected timemark in the center of the graph.  In the event that 
the timemark is too close to the end or beginning of the sample to display in 
the center of the graph, the timemark will be displayed without being centered. 
Once a timemark has been selected, the Del button may be pressed to delete the 
marker from the database.  The entry field is not cleared in order to allow the 
user to directly edit the timemark which was deleted and add it later. 


═══ 5.4.6.3. Echo Volume Entry Field ═══

The volume for each timemark may be set by specifying a value in the volume 
entry field.  This is a simple entry field in which the user can type or delete 
numbers.  Since the volume (attenuation) for each timemark may range from 0 to 
infinity, the only method for entering the volume is through the keyboard. 
Sorry, no sliders here.  As each character is typed, it is stored.  The user 
does not have to press enter or any key to accept the value. 

I have not found a big use for numbers greater than 1, but I could not find any 
reason to limit the user to a specific range of numbers.  Anyone who has 
experience with this effect and knows of a reason for a limitation should 
contact the author and I will be happy to set up something to make entry of the 
Volume easier. 

Note:  The most common mistake for the echo effect is in forgetting to enter a 
       value in the Volume field.  Remember that you must provide an 
       attenuation for the echo in the Volume entry field to make the echo 
       point valid. 


═══ 5.4.7. Band Pass ═══

This tool provides the ability to apply a band-pass filter to a sample. The 
frequency response for the filter is designed to drop logarithmically around a 
center frequency.  The slope of the drop at the desired start (Wp) and end (Ws) 
of the filter varies with the distance between the Wp and Ws.  This width is 
used to determine the slope of the dropoff at the edges of the filter.  The 
frequencies at Wp and Ws will be approximately half of their original 
amplitudes and all frequencies outside of the Center - Wp and the Center + Ws 
will be eliminated.  The bandpass filter can be mode oriented to pitched 
signals (i.e. voice, singing, or instrumental music) or can be modified by 
adding noise to the filter so that un-pitched signals can be effectively 
processed. 

Note:  SOX limits the use of the bandpass filter such that the center frequency 
       must be less than or equal to half the sampling rate for the wave. 
       Although PMsndX does not enforce this limitation, the results of 
       filtering beyond this limit prevents the filter from having much effect. 
       To aid the user in locating the maximum effective center frequency, a 
       light blue vertical bar is placed at half the sampling rate for the 
       data. 

The transormation for the Bandpass filter was taken from a a program called 
MUSIC56K (as documented in the MUSIC56K source code) and implemented in C++ for 
this program. 


═══ 5.4.7.1. Filter Display ═══

Operation of the bandpass filter tool is probably one of the most complex 
interfaces in the toolbox.  It is based on a simple principle.  The entire 
display of the filter represents the frequency response of the filter and is 
operated like a slider.  However, since the Start frequency and the Stop 
frequency are independent, the sliding bar is divided into identical controls 
for each filter edge. Before getting into the operation of the controls the 
display needs to be explained to establish the terms that will be used. 

As mentioned, the display is designed to illustrate the frequency response of 
the bandpass filter (independent of any added noise).  The center of the Start 
(Wp) and End (Ws) of the filter are marked by vertical BLUE bars.  The Center 
(Wc) of the filter is marked by a vertical RED bar.  These three markers 
provide the means for the user to modify the filter.  The region to the left of 
the RED center frequency is always the start of the filter.  The user may click 
the mouse to the left of Wp to decrease Wp by 1000 Hz.  Clicking between Wp and 
Wc increases Wp by 1000 Hz.  Likewise, clicking between Wc and Ws decreases Ws 
by 1000 Hz and clicking to the right of Ws increases Ws by 1000 Hz.  The user 
may also click the mouse near Ws or Wp to drag the respective ends of the 
filter quickly. 

To provide fine control of the filter, Right and Left arrows are provided for 
both Wp and Ws.  Clicking on either the right or left arrow will increase the 
indicated filter edge by 1 Hz.  To increase or decrease the filter edges by 10 
Hz, the user may select the plus or minus corresponding to the filter edges. 
The left set of controls affects Wp and the right set of controls affects Ws. 


═══ 5.4.7.2. Entry Fields ═══

As the mouse is used to adjust Wp and Ws, the exact frequencies for Wp, Ws, Wc, 
and the filter Width are updated in the text input fields.  The user can use 
the mouse to select one of the input fields and modify it directly.  To accept 
a value in the entry field and recalculated the dependant frequencies select 
another window or click on another item which moves the focus from the 
notebook.  The rules for the fields are as follows: 

 1. If the Center frequency is modified, new values for Wp and Ws are 
    immediately calculated using the current Width. If Wp or Ws are outside of 
    the possible ranges, then Wp or Ws are set to the limit of the acceptable 
    range and the Width and Center are recalculated. 
 2. If the Width of the filter is modified, new values for Wp and Ws are 
    immediately calculated using the current Center frequency.  If Wp or Ws are 
    then outside of the acceptable ranges, Wp or Ws is then set to its limit 
    and the Center and Width are recalculated. 
 3. If Wp is changed, the Width and Center are automatically recalculated to 
    reflect the new start of the filter. 
 4. If Ws is changed, the Width and Center are automatically recalculated to 
    reflect the new end of the filter. 


═══ 5.4.7.3. Noise ═══

The bandpass filter has been selected because of the desirable effect on 
typical sounds that will be processed by PMsndX such as voice or music. 
However, if other types of noise are to be filtered, noise can be added to the 
filter which results in a sharper peak of the filter.  To add this noise, 
select the checkbox for "Add filter noise". Selecting the checkbox again will 
disable the filter noise. 

Note:  The display of the frequency response for the filter does not reflect 
       added noise. 


═══ 5.4.8. Low Pass ═══

A Low Pass filter can be applied to a sample to eliminate high frequencies. 
Filtering is accomplished in the digital domain through the use of a very 
simple second order digital Fourier transform.  Future implementation may have 
a more complex Fourier transform; however, the chosen function is desirable 
because it provides a smooth dropoff without significant ringing. The 
performance of the filter is determined by the cutoff frequency and the rate of 
drop.  If the dropoff is made too quickly, the filter will exhibit a ringing 
effect at the begin and end of the dropoff.  If the dropoff is performed too 
slowly, the filter will supress more frequencies toward the end of the desired 
range.  The more orders of the filter (more stages), the better the frequency 
response; however, more orders increase the time for filtering significantly. A 
two order filter works adaquately. 


═══ 5.4.8.1. Gain ═══

When performing the digital convolution of the sample with the step function a 
Gain factor is used to normalize the output data.  This acts as a Volume 
control for the sample to prevent losses due to numerical overflow.  Values for 
the gain range from 0 to 1 in increments of 0.01.  A slider bar is used to set 
the gain of the low pass filter.  When the low pass filter is first brought up, 
the Gain will default to a value of 0.8.  If this is changed, it will remain at 
the new setting until the session is terminated. 


═══ 5.4.8.2. Frequency ═══

The Frequency response of the low pass filter is determined by a the 
centerpoint of the dropoff at the end of the step function.  When performing a 
digital filter, it is not possible to prevent the gradual drop at the end of 
the step function due to the convolution of the samples used in the 
transformation.  This is true for analog components also. The centerpoint of 
the dropoff can be set in three ways. The user may enter the specific fruquency 
in the text entry box in the lower right corner or may use the filter display 
like a sliding bar.  As is typical of a sliding bar, the mouse may be used to 
capture the cutoff frequency by pressing the mouse button while the mouse is 
near the cutoff frequency.  By holding the button down, the user may drag the 
frequency to the desired range.  Additionally, the user may click to the right 
or the left of the frequency cutoff to increase or decrease the frequency by 
1000 Hz. The right and left arros in the corners of the display may be used to 
increase or decrease the frequency by 1 Hz. The plus and minus buttons in the 
corners of the display may be used to increase or decrease the frequency by 10 
Hz. The frequency response curve illustrates the dropoff that occurs at the end 
of the step function. 


═══ 5.4.9. Rate ═══

Once a sample has been loaded into memory, the current rate information is 
displayed on the RATE page of the notebook. The user can change the rate of the 
sample using this page of the tools notebook. 

The rate information page is dividied into groups of buttons and slider bars. 
These are for Standard Rates, Non-Standard Rates, Quality, Do It, and Help. 

Note:  Changing the sampling rate may degrade the quality of the sound. 


═══ 5.4.9.1. Standard Rates ═══

The user may select from a set of standard sampling rates for common computer 
formats or may specify a specific rate. OS/2 and Windows use standard rates 
which are multiples of 11025 Hz.  Sun, DEC, and NeXT computers commonly use a 
sampling rate of 8000 Hz.  Standard rates of 8000, 11025, 22050, and 44100 Hz 
have been provided for the user to select. 


═══ 5.4.9.2. Non-Standard Rates ═══

If the user wishes to use a sampling rate which is not one of these, the button 
for Non-Standard should be pressed.  This will activate the slider bar and user 
input windows to allow the user to specify the rate.  The slider bar can be 
used to quickly change the rate in the input window or the user may select the 
input window and type in the desired rate. 


═══ 5.4.9.3. Quality ═══

When changing the sampling rate, each new sample point must be interpolated 
from the current set of samples.  This can be done in a number of ways.  PMsndX 
allows the user to specify the quality of this interpolation between samples. 
Choosing a value of 1 will use linear interpolation which is quick, but causes 
distortion.  Choosing a higher value will take longer to perform, but will 
create a better approximation to the original waveform. 


═══ 5.4.9.4. Do It ═══

If the rate specified by the user is the same as the sampling rate for the data 
currently in memory, the DO IT button is disabled.  If the sampling rate is 
changed, the DO IT button will be activated.  Pressing this button will convert 
the change the data in memory to reflect the information specified by the user. 


═══ 5.4.9.5. Help ═══

To open the HELP engine with for information on the Rate page, select the HELP 
button. 


═══ 5.4.10. Speed ═══

This function will change the playback speed of a sample. This is the same 
thing as setting a phonograph to a different speed such that the sound is 
played too fast or too slow.  The controls for this effect simply specify the 
new playback speed.  Once a new speed is selected, the sample is resampled to 
interpolate the new playback points. As a result, a sample is still played at 
the same rate, but the data is modified to play at the new rate.  This allows 
the sample to be stored in a file which is of a standard rate. 

The user may select any of the standard rates including 8000 Hz, 11025 Hz, 
22050 Hz, and 44100 Hz.  Additionally, the user may specify the playback speed 
to be either double (x2) or half (x1/2) or may specify a specify playback speed 
by selecting the User button.  If a speed other than the current speed is 
specified, the DOIT button will be activated which will allow the user to 
perform the change. 


═══ 5.4.11. Vibro ═══

This function is in SOX and has been added to PMsndX to maintain compatibility 
with the functions of SOX.  This function performs the "world-famous" Fender 
Vibro-Champ sound effect to a sound sample by using a sine wave as the 
amplitude of the volume at each sample.  This tool requires that the user set 
the Speed, and the Depth of the sine wave. 

The code for this effect was taken directly from source code from Lance Norskog 
and Sundry and converted to C++ for this program. 


═══ 5.4.11.1. Speed ═══

The speed setting gives the frequency of the sine wave in Hertz.  The range of 
values for the slider are from 0 to 30 in increments of 1 Hertz.  A value of 0 
would be useless for a frequency so this is automatically changed to 0.001.  By 
default, the speed is initially set to 0.001. 


═══ 5.4.11.2. Depth ═══

The depth setting gives the the amount by which the volume will be cut into by 
the sine wave.  The range of values for the slider are from 0.0 to 1.0 in 
increments of 0.01.  The initial value of the slider is 0.5. 


═══ 5.4.12. Volume ═══

Most anyone who has received a sound sample from different sources has had the 
problem that the recorded volume is inconsistent between different samples. 
After all, there is no standard recording level for the different machines that 
sound can be recorded from.  To allow the user to adjust the volume of a 
sample, PMsndX provides a tool to adjust the volume.  Volume can be adjusted by 
either specifying the Maximum or by simply multiplying by a fixed value. 


═══ 5.4.12.1. Maximum Volume ═══

By specifying a maximum value for the sound sample, all sound samples can be 
set to have a similar maximum.  The obvious use for this function is to allow a 
library of sounds to be set at the same volume.  The value used for the maximum 
volume is based on a percentage of the maximum data that can be held in a 
single sample.  As an example, a value of 100% for the volume represents a 
value of 127 for a signed byte sample. 

When the button for the Maximum is selected, the slider bar directly beneath 
the button is activated.  Initially, this will be set to the current volume in 
terms of the percentage of the maximum value for the sample.  The volume may be 
adjusted by setting the slider to a value between 0 and 100 percent of the 
maximum. 

Since the value is based on a percentage of the maximum value of the data that 
can be stored in a sample, clipping is not possible. 


═══ 5.4.12.2. Fixed Volume ═══

When the button for the Fixed value is selected, the slider bar directly 
beneath the button is activated as well as the checkbox for clipping.  The 
fixed bar provides the means to multiply all sound samples by a fixed value 
between 0 and 2 in increments of 0.1. A value of 1 makes no change.  Any value 
greater than 1 increases the volume and any value less than 1 decreases the 
volume.  A value of 2 doubles the volume of the sample. 

When using fixed sampling it is possible to exceed the maximum data that may be 
stored for a sample.  The checkbox for clipping may be selected to prevent this 
clipping.  If the checkbox is set, if the fixed multiple will result in 
clipping, then the maximum multiple will be set to the maximum value that will 
not result in clipping.  If the clipping box is not set, data may exceed the 
maximum that may be stored for the sample. 


═══ 5.5. Settings ═══

The window positions and file paths are maintained as long as PMsndX is 
running.  When PMsndX is terminated, it will not save the current positions and 
paths for file operations unless the boxes are checked in the SETTINGS dialog 
box.  Selecting these buttons has no effect on remembering the current window 
positions during a single session; rather, they only affect saving the 
information between sessions. 

From the SETTINGS dialog box the user may select to save the current window 
positions, open file path, save file path, maximum memory and enable MMPM/2 
Support requirements of the program. 

The SETTINGS information is stored in the file pmsndx??.ini in the directory 
where PMsndX was started.  The question marks in the file name represent the 
version number for the program.  This is intended to allow future versions of 
the program to avoid conflicts in the event that the initialization file format 
changes. 

Note:  The information in the SETTINGS dialog box is only saved when the 
       program is terminated.  If the SAVE CURRENT items are deselected, then 
       the information will not be saved between sessions. 


═══ 5.5.1. Window Positions ═══

During a session, the user can move any of the dialog boxes around on the 
screen.  If the WINDOW POSITIONS box is checked, these window positions will be 
saved when the program is terminated.  If this button is deselected before the 
program is terminated, the next session will revert to the previous window 
positions saved by the program.  By default, if no window position has been 
saved for a particular window, the window will be opened in the lower left 
corner of the desktop. 


═══ 5.5.2. file Open path ═══

The file path for loading samples into memory may be saved between sessions by 
selecting the FILE OPEN PATH button.  If this button is selected, the last file 
open path will be saved when PMsndX is terminated.  If this button is 
deselected before the program is terminated, the next session will revert to 
the path from the previous session. If no information is saved for the program 
at any time, the current path will become the default path for open operations. 

Note:  This box may be selected from either the SETTINGS dialog box or from the 
       SAVE DIRECTORY button on the OPEN dialog box. 


═══ 5.5.3. file Save path ═══

The file path for saving samples to a file may be saved between sessions by 
selecting the FILE SAVE PATH button.  If this button is selected, the last file 
save path will be saved when PMsndX is terminated.  If this button is 
deselected before the program is terminated, the next session will rever to the 
path from the previous session. If no information has not been saved between 
sessions, the current path will become the default path for save operations. 


═══ 5.5.4. Maximum Sample Memory ═══

PMsndX takes advantage of OS/2's advanced memory management facilities.  When 
the program is started, it only takes up the memory required for the executable 
to load.  PMsndX then reserves the amount of memory specified by the SETTINGS 
box from OS/2 but does not commit this memory.  This means that the program has 
requested that OS/2 allocate the necessary resources to manage the amount of 
memory specified.  Until the memory is actually committed it is not taken from 
the system's memory pool.  When a sound sample is loaded into memory, PMsndX 
then requests that OS/2 commit the necessary memory before it loads the sample. 
When a new sample is loaded, the previous memory is decommitted and the 
procedure is repeated. 

Although this minimizes the actual amount of physical memory required by 
PMsndX, it still provides the potential to cause OS/2 to have to commit more 
memory than is available on the system.  To avoid this problem, PMsndX provides 
the user with the ability to limit the amount of memory which can be committed 
by OS/2.  The user may either specify that the program automatically determine 
the maximum or that it set the maximum at a specific value. 

Memory is primarily used to hold samples for operations; however, whenever the 
sound is manipulated in such a way that either the output has a different 
number of samples or the operation requires the samples to remain in tact 
during the entire operation, additional memory is used to hold the new data. 
Once the operation has been completed, the memory is freed.  When setting the 
maximum memory, the user must take into account the size of the data in memory 
as well as the size of the results of any operations. With the exception of 
Sampling Rate changes, the maximum memory requirements will not exceed twice 
the size of a sample.  When changing rate, the size is dependent on the new 
sampling rate.  If the new rate is higher than the current rate, the memory 
requirements will increase.  If the new rate is lower than the original rate, 
the memory requirements will shrink. 


═══ 5.5.4.1. Auto ═══

If the user selects the AUTO mode for memory (the default), PMsndX will limit 
the memory usage to 32 megabytes.  This is generally more memory than most 
systems have but allows for a very large sample file to be loaded. 


═══ 5.5.4.2. Value ═══

Since the minimum OS/2 memory block size is 4096 (4k) bytes, the user may 
specify the number of 4k pages for the limit.  The user may either use the up 
and down arrows to increment or decrement the amount of memory or may place the 
cursor in the window and type the specific value. 


═══ 5.5.5. MMPM ═══

PMsndX supports playing samples from memory directly to the MMPM digital audio 
device of OS/2.  This allows samples to be played without having to save the 
sample to disk in the native .WAV format.  The settings dialog box provides 
controls for disabling or enabling MMPM support and for controlling the actions 
taken when a file is loaded (e.g. Play sample on load, convert to a standard 
rate when loaded, and exit after play from the command line).  Additionally, 
the digital audio device  may be specified. 


═══ 5.5.5.1. Enable MMPM/2 Support ═══

If the MMPM/2 capabilities of the program are not needed or if MMPM support is 
not installed on a particular system, the MMPM may be disabled from the 
settings dialog box.  By disabling the MMPM/2 support, the button on the main 
control panel for MMPM is disabled.  By default the program will disable MMPM 
support; however, if the MMPM button is selected, a message is displayed to the 
user to indicate that the setting should be turned on from the settings box. 

The controls for MMPM and the ability to play the "playlist" using MMPM utilize 
the files SW.DLL and MDM.DLL.  These are part of the standard MMPM distribution 
and must be present in the DLL path for the MMPM portion of this program to 
operate.  The MMPM support is not linked into the executable of this program. 
Rather, it is only loaded when the user enables it.  This allows the program to 
run on machines which do not have MMPM installed. 

The MMPM/2 functionality of PMsndX has been implemented to share the audio 
device with other programs on the system. By disabling the MMPM/2 support, the 
audio device is freed up completely and all of the tasks (six in total) are 
released. 


═══ 5.5.5.2. Play sample on load ═══

If this box is selected, a sample is immediately played when it is loaded into 
memory.  To provide control during playback, the MMPM dialog box is opened 
after the file has been loaded.  When this feature is used in conjunction with 
the exit after play feature, PMsndX provides the ability to play any supported 
sample file format from the command line and have the program exit when it is 
finished. 

If this parameter is not specified, the sample will still be loaded from the 
command line; however, it will not be played until the user accesses the MMPM 
dialog. 

Note:   When a filename is specified on the command line, the control panel and 
       the dialog boxes are not opened.  The intention of this operation is to 
       allow the program to play without being intrusive. 


═══ 5.5.5.3. Standard rate on load ═══

Not implemented yet! 

If a sample is sampled at a rate other than one supported by the MMPM/2 module 
of OS/2, this feature will allow the program to resample the file at the 
nearest supported rate as it loads the file.  If this option is not selected, 
the file will simply refuse to play if it is at a different sampling rate than 
supported by OS/2. 


═══ 5.5.5.4. Exit after Command line play ═══

This option provides the ability for PMsndX to exit after playing the sample 
when the file is loaded from the command line.  This is primarily intended to 
provide a means to play any of the supported formats from the command line. 


═══ 5.5.5.5. Device ═══

Obviously not every machine has the same digital audio device.  PMsndX provides 
a means to use a different audio device than the default digital audio 
interface.  By default the device name is Waveaudio01.  Any Waveaudio device 
may be selected by entering the device name in the Device entry field. 


═══ 5.5.6. Do It ═══

After the user has set all of the information in the SETTINGS dialog box can be 
applied by pushing the DO IT button.  When this button is pressed, the dialog 
box is inactivated and the settings are applied. 

Note:  If a sample is currently loaded into memory and the Maximum Sample 
       Memory is changed, the sample data will be flushed from memory.  To warn 
       the user of this, a warning box will be displayed. 


═══ 5.5.7. Oops ═══

To dismiss the SETTINGS box without using the values set by the user, the OOPS 
button can be used.  This has the same effect as pushing the SETTINGS button on 
the main control panel when the SETTINGS box is displayed.  All information 
entered by the user is cleared and the SETTINGS remain unchanged. 


═══ 5.5.8. Help ═══

Pressing the HELP button displays help on teh SETTINGS dialog box. 


═══ 5.6. MMPM ═══

So, you are interested in playing some samples from my little program?  Good. 

The ability to play a sample is not intended to provide the full capabilities 
of the digital audio player.  It is intended to allow samples to be played 
without having to save them to disk.  Additionally, this feature allows the 
user to play a file of any format currently supported by PMsndX.  The sample 
rates are limited to those supported by the MMPM device and if a sample is 
loaded with an odd sample rate which is not supported, it must be converted to 
a useable sample rate before it can be played. 

If you don't have MMPM/2 installed with your OS/2, don't worry.  If you disable 
the MMPM support from the settings dialog box, it will not attempt to open the 
audio device. 

The controls for the MMPM player are basically the same as those used on the 
digital audio player so no additional explanation is provided. 

O.K., let's face it.  MMPM is pretty cool and it is not extremely difficult to 
program.  However, to take advantage of the advanced features of the system, a 
great deal needs to be done.  I was not able to find a good reference book for 
programming MMPM code, so I winged it and got something going.  No doubt this 
will be a problem in the future.  The current implementation is very simple and 
uses about 6 tasks to handle the queueing of data and running the little 
buttons to look like the IBM buttons for the digital audio player. 

Note:  Recording has not been implemented at this time. 


═══ 5.7. Exit ═══

When the EXIT button is pressed, the program terminates.  If the Settings box 
or the SAVE DIRECTORY from the Open or Save dialog boxes have been set to save 
information, the data will be saved to the initialization file before the 
program exits.  all windows of PMsndX including any dialog boxes are removed 
from the screen when the program terminates. 


═══ 6. Technical Issues ═══

Memory Usage: I have worked with means for storing and converting from one 
format to another efficiently.  Initially I tried to store things in a data 
structure which was a union of all of the types of data that are used by the 
sound types.  However, converting from one format to another was difficult and 
each effect had to be able to understand the initial and final format.  This 
became unwildly considering that there can be either signed or unsigned samples 
of sizes byte or word.  As new effects were added, it became unmanagable.  At a 
sacrafice to memory efficiency, I have changed it to store all data as a signed 
SHORT (2 byte) sample.  The effects then operate genericly on the samples and 
the only time that the type of data is important is when reading or writing the 
samples.  The savings in complexity justified the memory requirements.  As a 
result, if a sample is 1k of bytes (.wav format), then in memory it will take 
up 2k.  Currently the program will only read and write 8 and 16 bit samples. 
Since I don't know of any sound cards that can sample at greater bit sizes, 
this is the limit.  In the future, this approach to memory usage can be easily 
extended to 32 bits without rewriting every part of the program.  In fact, to 
change the storage sizes, two definitions have to be changed and then the 
proper input/output routines written.  Simple? I think so. 

Additional known faults: 

 1. Currently, the Quality setting in the Rate only supports a linear 
    approximation.  This appears to be the same that SOX supports as they 
    result in similar output. 
 2. The buttons for Play and Record have no function at this time.  This 
    functionality will be added later. 
 3. There is no drag and drop capability yet. 
 4. A file must be loaded through the Open button.  PMsndX ignores any 
    additional parameters on the command line. 
 5. There is currently no means to override the load file type. 
 6. Volume changes affect both channels equally.  If one channel is sampled at 
    a higher volume, there is no method currently available to mormalize the 
    two channels. 


═══ 7. About the Author ═══

My name is William Scott Hiles but I usually go by the name Scott.  I have a 
masters degree in signal processing and satellite communications. 
Unfortunately, my occupation utilizes very little of my formal education and 
takes more advantage of my less formally learned talents.  I work as an 
electrical engineer for the Navy in the area of LAN and WAN research. My job is 
centered around promoting open systems in networking within the Navy and I am a 
Navy expert on fiber optic networking.  I have worked with the ANSI X3 
committees for the past 5 years and currently (1993-1994) am the chairman of 
the FDDI Repeater specification.  Enough of that dribble...the point is that I 
don't use my education in my job. 

Which leads me into the purpose of this program.  I am an electrical engineer, 
and my heart lies in hardware design and programming.  Well, with this program 
I can at least satisfy my need to create software.  So, this program came about 
because I was playing with sampling and recreating sound with my Sound Blaster 
16 when I had the need to convert from the .wav format to the Sun .au format. 
SOX is the only thing that I was able to find that could do what I needed. 
However, I quickly realized that SOX is great for the general case, but not so 
great in more specific cases such as changing the sampling rate of a file. SOX 
is good enough for the human ear, but not good enough for the computer.  So, 
rather than live with SOX or just write a resampling program, I wrote PMsndX to 
provide the functionality of SOX but enhance it to provide the capabilities I 
needed. 

My resources are modest.  I am 29 (1993) and have programmed everything from a 
PC to a 286 for the past 10 years.  I dumped my 286 in February of 1993 and got 
me a nice 486.  I decked the thing out and got OS/2.  I had been playing with 
OS/2 since 1.3 on machines that I did not own, but this was the first time I 
had it at home to play with as I pleased. Programming under OS/2 provided a 
unique challenge with unlimited creative abilities.  The company called 
WiSHware which is listed in the About box was formed as a shareware/freeware 
incorporated name for anything I write.  I have a significant library of 
programs for DOS and even a couple for Windows.  PMsndX is the second program 
for OS/2 that I have written.  The first one was not well received as it did 
not provide a significant function to the community.  Big deal.  I use it at 
home and I don't care. 

So that is my history and my qualification.  I am a bit surprised that you read 
this far.  Congratulations. By the way, did you wonder why I chose a little 
blue motorcycle for the icon? I can easily be reached by my current email 
address (whiles@relay.nswc.navy.mil) or through US mail at: 

Scott Hiles 
4421 Savannah St. 
King George, VA 22485 


═══ 8. Shareware ═══

During the development stages of PMsndX (i.e. until version 1.0 is available) 
PMsndX is free to all for distribution. After version 1.0 is finished, the 
program will then be distributed as shareware. 

I have put a lot of effort into making this program robust and very pleasing. 
In actuality, 90 percent of the work on the program has been around the user 
interface because the code for doing the actual effects is only about 500 lines 
compared with roughly 10,000 lines of code for the user interface.  It has 
taken me more than three months to get this program to where it is now, and I 
would hope that if you like the program and use it, you will appreciate it 
enough to send me a little cash to help fund future work.  I don't expect much. 
I think a round number like $25.00 would be nice, but you can do whatever you 
feel like.  Just don't insult me by sending me a penny or something like that. 
With my current financial status (i.e. poor) I cannot afford a optimizing 
compiler.  With a few donations the program could benefit nicely.  (hint, hint) 
The section describing the Author provides my email and US postal mail 
addresses. 

Note:   If you tested the program during the development stages, you will get a 
       FREE copy of the final program. 


═══ 9. Future Work ═══

The scope and goals for PMsndX are growing day by day. Currently I plan to have 
all of the functions of SOX as well as a few others listed below. 

 1. Drag, Drop, Cut, and Paste operations 
 2. Add a scripting language for automating operations 
 3. Command line overrides/initialization 
 4. Playback, Recording, and Cut/Paste editing 
 5. Normalization across channels 
 6. Add other filters such as Butterworth, Chebyshev and others. 
 7. Add High pass filtering 
 8. Add a Band Stop filter 


═══ 10. Tradeoffs ═══

Although SOX has a difficult command line, it is very effective for large 
samples because it processes the samples in managable blocks.  As a result, SOX 
does not require much memory to operate.  PMsndX provides the user with a 
simpler interface at the expense of reqources on the host computer. This can be 
a significant factor when manipulating large files on a system that is limited 
in memory resources.  This should be taken into consideration.  PMsndX is 
useless if it does not have the resources necessary to operate.  When OS/2 uses 
its swap file to provide more memory, the performance of PMsndX as well as any 
other programs on the system will suffer significantly. 


═══ <hidden>  ═══

SOX originated on Unix and provides a means to convert sound from one format to 
another and to add effects to sound samples.  The interface to this program is 
the command line with various options and flags. 


═══ <hidden>  ═══

Unix is a registered trademark of ATT laboratories. 


═══ <hidden>  ═══

JoeView is an excellent program written by Joe Burkley.  If you ever need to 
view a graphics image of virtually any format, this is the program for you!!! 


═══ <hidden>  ═══

Now, here is where my creativity is somewhat lacking.  Unlike the makers of 
BMW, I don't have the resources to hire a company to find the best icons for a 
the buttons, so I did it the easy way.  I just made a stab at it and figured 
that if anyone had any complaints or comments, they would let me know and I 
would change them.  Come on, one of the easiest things to do to a program is to 
recompile the resource bitmaps.  If you have suggestions, just let me know and 
maybe you might influence me to change them. 


═══ <hidden>  ═══

The bits in a word are stored such that the leftmost bit is stored first in the 
first byte and the rightmost bit is stored last in the last byte.  If a word is 
composed of 16 bits, the word would be written to a file starting with bit 16 
and ending in bit 0. 

The number 0x1234 (0001 0010 0011 0100) is actually stored as 0001 0010 0011 
0100. 


═══ <hidden>  ═══

The bits in a word are stored such that the leftmost bit is stored first in the 
last byte and the rightmost bit is stored last in the first byte.  If a word is 
composed of 16 bits, the word would be written to a file starting with bit 7 
and ending in bit 8. 

The number 0x1234 (0001 0010 0011 0100) is actually stored as 0011 0100 0001 
0010.