.TH ie 1P local "Silicon Graphics, Inc."
.SH NAME
ie \- instrument editor for Nintendo 64 audio
.SH SYNOPSIS
\f3ie\f1 [-b <.inst file>] [-c <.cnfg file>] [-v]
.SH DESCRIPTION
These pages describe the initial release version of this tool.
As an initial release, there are known problems and bugs with
this version so use with caution.  Please refer to the known bug
list below to help prevent any loss of work.
.PP
The
.I ie
tool provides three primary uses. First, it allows realtime
editing and auditioning of bank components contained in .inst
files. Second, it allows realtime editing and auditioning of
effects. Third, it allows external MIDI devices to playback
MIDI on the Nintendo 64 and profiles the system and Audio Library
resources that are being used.
.PP
Command line options are:
.RS 5
.TP 12
.B -b <.inst file>
specifies the .inst file to be edited.  If this option is not
used, then the editor opens with a new .inst file.
.TP
.B -c <.cnfg file>
specifies an .cnfg file.  A .cnfg file contains configuration
information that is used to configure the Nintendo 64's Audio
Library resources (eg. output rate, virtual voices, etc.).  It
also can contain a description of an effect that will be loaded
into the editor for editing and into the Nintendo 64 for auditioning.
.TP
.B -v
turns on verbose mode. This is mainly used for debugging.
.SS Editor
The editor portion of the 
.I ie 
tool is a simple application for editing .inst files as well
as effects.  A Nintendo 64 development board does not have to be
present to open and edit files.  However, you will not be able
to audition your changes without the Nintendo 64 so editing certain
parameters, such as effects parameters, becomes difficult.
.SS Bank Editing
.I ie
can read, write, and edit .inst files.  .inst files contain a
description of a Nintendo 64 bank which can be compiled into an
actual Nintendo 64 bank files with
.I ic,
the instrument compiler tool.  The .inst bank description
is made up of several components such as instruments, sounds,
envelopes, etc.  Each of these bank components, or assets,
have one or more parameters associated with it.  Bank assets also
reference each other in a sort of parent-child relationship.  For
instance, bank assets reference instruments assets so instruments
are children of a bank parent.  Similarly, instrument assets
reference sounds assets so sounds are children of an instrument.
Furthermore, if a child asset is never referenced by
another asset, it is called an orphan.  So if an envelope asset is
never used by a sound asset, the envelope is an orphan and can be
deleted from the .inst file without affecting the bank.
.SS Viewing Assets
The editor displays all these bank assets and supports
viewing and editing the parent-child relationships within a bank.
The editor's view contains several folders for each type of bank
asset.  Each folder contains a list of all the assets of the given
type.  For example, to view a bank's instruments, simply select
the instrument's folder tab to open up the instrument folder.
The folder contains a list of all the names of the instruments as
well as columns for each of an instrument's parameters, such as volume,
pan, priority, and bend range.  Each asset also contains an icon
column which helps identify the type of asset.
.SS Editing Assets
To edit the value of an asset's parameters, simply click on the
corresponding column to activate the default editing for the
parameter.  Names are always text edited.  Numbers can be scrolled
up or down to increase or decrease their value.  References to
other child assets are edited with popup menus.  However, all assets
can be text edited by clicking on them with the "Alt" key held down.
This pops up a text edit field which can be moved around from field
to field using the arrow keys and the "Alt" key.  (Without the Alt
key, the arrow keys move the cursor within the text field.)
Values won't be accepted if the value is out of range or is illegal.
Use the "ESC" key to cancel any text editing.  Note that some fields
cannot be edited (eg. a wavetable's sample rate) and only display
information.  Icon fields are used for a variety of purposes such
as asset selection, asset audition, and others.  Integer fields can
be double-clicked to quickly set the value to a preset default value.
.SS Viewing and Editing Children
Some of the assets contain a "#" column.  This column displays the
number of children that the asset has.  If the asset has one or more
children, double-clicking on the "#" column will open up the parent and
display its children.  Since the children have different parameters
than the parent, only the common fields such as the name field are
displayed for children.  Double-clicking the "#" column again will close
the asset.  The "#" field can be edited by clicking on the field.  This
will bring up a popup menu showing a list of assets that are currently
not children of the selected asset.  Choosing one of these assets will
add it to parent's list of children.  Double-clicking on the icon of
a child, will automatically open of the children's folder for editing
of their parameters.  For example, double-clicking an instrument's sound
will open up the sound folder for editing.  Likewise, double-clicking
a sound's envelope will open up the envelope folder for editing.
.SS Auditioning Assets
In order to audition assets, the current bank being edited must be
"valid" and must be "online" on the Nintendo 64.  For a description of what
it means for a bank to be valid and online, see the Nintendo 64 Playback
section. When a bank is online, bank assets can be auditioned by
clicking on their icon.  Pressing the button down sends
a MIDI note on event.  Releasing the button sends a MIDI note off
event.  This makes it easy to audition the sustain portion of
a sound.  Currently, auditioning instrument assets will always play
a C4 note.  Auditioning sounds, keymaps, envelopes, and wavetables
will play the asset's parent instrument at the sound's key base.
Note that if the keymaps for an instrument's sounds are not specified
and ordered properly, an auditioned asset may not get mapped to the 
correct sound.  This is a potential source of confusion when auditioning
non-instrument assets.
.SS The File Menu
The file menu contains commands for opening, closing, and saving .inst
files.  The "Open" command brings up a dialog for selecting
a .inst file to edit.  Only one .inst file can be open at a time so
choosing "Open" while another .inst file is currently open will
first close the file before opening a new one.  The "Close" command
removes all bank assets and allows a new file to be edited.
The "Save" and "Save As" command write the file to disk.
.SS The Edit Menu
The edit commands are currently not supported.
.SS The Asset Menu
The Asset menu contains commands for inserting and deleting assets.
Selecting the insert command will create a new asset and place it at
the end of the list.  The asset will automatically have default
parameter values.  To insert an asset in the middle of the list,
select the asset where you want the asset to appear and select the
insert command.  The selected asset will appear below the newly created
one.  To delete assets, simply select one or more assets and select
the delete command. A short cut for creating an asset and adding it
to a parent is provided by the "Insert Child" command.  This command
will insert a new child asset to the selected parent.  The "Remove
Child" command removes the selected child(ren) from the parent,
but does NOT delete them.  Choose the "Delete" command to remove and
delete them.  Finally, the "Import" command allows importing of 
other .inst files as well as .aiff-c files.  This is currently the
only way to create wavetable assets.
.SS The Select Menu
The select menu contains useful commands for selecting certain types
of assets.  The "Select Parents" command will select all the parents
of the currently selected asset.  This command works only if exactly
one asset is selected.  For example, if a keymap is selected, the 
"Select Parents" command will select all the sound assets that use
the given keymap and will automatically display the sound folder.
The "Select Orphans" commands will select all the folder's assets
that do not have any parents.  This is useful for determining which
assets aren't being used anywhere and which can be deleted.
.SS Effects
.I ie
supports creating, editing, and auditioning effects on the Nintendo 64.
Since effects are tightly coupled to the N64 Audio Library, they will
only appear for editing if an N64 development system is present.
Otherwise, only bank components can be edited.  If an N64 development
system is present,
.I ie
will automatically create five built-in effects for auditioning
and editing.  These effects are small room, big room, chorus, flange,
and echo.  In addition to the built-in effects, custom effects can
be created from scratch.
.SS Effects Viewing
Similar to banks, effects are made up of two components, the effect
asset and the effect section asset.  Simple effects may contain only
one or two sections, while more complicated effects may contain
eight or more sections.  Similar to banks, effects are parents to
effect section children.  As a result, effects can be viewed just
like bank assets can be viewed.  All effects parameter values are
displayed in their raw data format (the kind that the N64 wants them in)
except for the delay fields (length, input, and output).  The delay
parameters are displayed in msecs. and must be converted to samples
and aligned to an 8 sample boundary before being used to configure a game.
(ie does this automatically.)
.SS Effects Editing
Effects and effects sections can be edited just like bank assets.  Their
parameter values can be editing either by scrolling or by text editing. 
New effect assets can be inserted and unwanted effect assets can be deleted.
However, there are some special considerations for editing effects.
.PP
First, the delay parameters (length, input, output) are displayed and
editing in msecs.  The N64 requires that these values occur at 8 sample
boundaries and that the length is greater than input/output delays by 160 samples.
.I ie
automatically enforces the 8 sample boundary rule when it loads the effect
on the N64, however it does not enforce the 160 sample rule.  Be careful
when editing input/output delays so that it does not approach within 160 samples
of the delay line's length.  (See the N64 Developer's Manual for a discussion
of why this 160 sample restriction exists.)
.PP
Secondly, when an effect is "online" (ie. it is loaded into the N64),
the effect's length parameter cannot be edited.  In addition, you cannot
insert or delete sections to an online effect. In order to make these changes
to an online effect, you must offline the effect first.
.PP
Thirdly, effect sections can only have one parent.  Once it is being used
by a parent effect, it will not be available for other effects to use it.
.PP
Finally, to use chorus or the low pass filter, you must make sure that the
respective parameters are non-zero before loading the effect.  The Audio
Library will not allocate the required memory to implement chorus or the
low pass filter if the parameters are initially zero (this saves unneeded memory).
.SS Effects Auditioning
Initially, no effects are loaded onto the N64.  In order to load an effect
and make it "online", double-click the desired effect's icon.  To offline
the effect, double-click it again or double-click another effect.  When
an effect is placed online, the N64 must be fully reconfigured since the
Audio Library must be initialized with an effect.  This may take a few seconds
since it must reload the entire bank to the N64.  Once the effect is online,
its icon should appear in red to indicate that it is online.  From now
on, auditioning bank assets will be played through the effect.  Note that the
wet/dry amount can be controlled for each MIDI channel by sending an FX1
control message to the channel.
.SS Effects Saving and Restoring
Currently, effect assets can not be saved to disk.  This is because there
is no standard ".fx" file like there is an ".inst" file for bank assets.
However, effects can be restored from disk with a configuration (.cnfg) file.
(See the section on the N64 Menu for a description of the configuration file.)
Since the Audio Library treats effects as part the the configuration data
you can edit the configuration file to include a custom effect.  An effect is
indicated with the keyword "REVERB_PARAMS" and is followed by a bracketed
{...} set of parameters describing the effect and its sections.  (Delay
values are in msecs.)  For an example of an effect definition, refer to the file
/$ROOT/usr/src/PR/assets/banks/ie.cnfg which defines a custom effect.
.SS Nintendo 64
When
.I ie
is launched, it automatically looks for an N64 development board and
if it finds one, it will boot it up with MIDI playback code and 
profiling code.  If it can't find the N64 board or if it fails to
boot it up, it will report an error and
.I ie
will not be able to audition any instruments or edit effects.  In
addition,
.I ie
will also boot up the
.I gload
tool which acts as a print server for any error or debugging messages.
This is useful for catching when an audio library resource has been
exceeded.  If another
.I gload
is running at the time that
.I ie
is launched,
.I ie
will fail to run.
.SS Nintendo 64 Configuration
The Nintendo 64 Audio Library is configured using default configuration
information.  This default configuration can be edited either by
using the configuration dialog or by specifying a configuration file
on the command line when the tool is run.  For information on how
to use the configuration dialog see the section on the Nintendo 64 Menu.
To configure the tool using a configuration file, simply specify
the file on the command line.  The configuration file should contain
reserved words that specify the values of certain configuration parameters,
such as output rate or the number of available virtual voices.
For an example of a .cnfg file and its reserved words, refer to the
file /$ROOT/usr/src/PR/assets/banks/ie.cnfg.
.SS Nintendo 64 MIDI Playback
Once it is up and running, the Nintendo 64 waits for incoming MIDI
messages.  MIDI messages can be sent from an external MIDI device
or from the
.I ie
tool itself.  In order for the Nintendo 64 code to respond to the 
MIDI messages, it needs to have a valid bank downloaded to it by
.I ie.
When 
.I ie
is launched with a new file, there is no bank in the editor and 
the Nintendo 64 will be "offline" which means it does not have a 
bank installed.  The profiling screen on the Nintendo 64 monitor
indicates the state of the bank at the top of the screen. As soon as
.I ie
has a valid bank in the editor, it will download the bank data
and the Nintendo 64 will then be "online" and it will be able to
respond to MIDI events.  As the bank is edited, it continually
checks to see whether the bank is still "valid" and as soon as the
bank fails to be valid, it will take the bank offline.  The reason
for this is simply that the Audio Library requires complete
and correct bank data in order to work properly.  A bank is
determined to be valid if the following conditions are met:
.RS 5
.PP
1) a bank asset exists
.PP
2) the bank contains at least one instrument
.PP
3) the bank's instruments contain at least one sound
.PP
4) the bank's sounds must all have keymaps, envelopes, and wavetables
.RE
.PP
When a bank is online, bank assets can be auditioned from the editor
by clicking on their icon.  MIDI messages can also be sent from
external devices.  To use external devices, a MIDI interface must
be properly attached to one of the host computer's serial ports
and it must be properly configured using the
.I startmidi
tool.
.SS Nintendo 64 Profiling
The Nintendo 64 screen displays current readings for various system
resources.  These readings are useful to monitor when playing
back a sequence targeted for the Nintendo 64 from an external MIDI
sequencer.  The readings will measure how much of each resource
is used in order to playback the sequence.
The profiler keeps track of the following resources:
.RS 5
.PP
1) cmds: the number of audio commands used to synthesize a
frame of samples.  Displays both current and maximum values.
.PP
2) syn upds: the number of parameter update blocks used by the
synthesis driver to store changes in control parameters.  The
number of available update blocks is specified during the Audio
Library configuration.  Displays both current and maximum values.
.PP
3) seq evts: the number of event message blocks used by the
sequence player.  The number of available message blocks is
specified during the Audio Library configuration.  Displays both
current and maximum values.
.PP
4) DMAs: the number of DMA requests made during an audio frame.
Displays both current and maximum values.
.PP
5) DMA bufs: the number of DMA buffers needed during an audio frame.
The number of availabe DMA buffers is specified during the Audio
Library configuration.  Displays both current and maximum values.
.PP
6) vcs: this profiles virtual voice usage during playback. Each
pixel represents one used virtual voice.  The number of available
virtual voices is specified during the Audio Library configuration.
The maximum number of virtual voices used is displayed in the corner
of the voice graph.
.PP
7) RSP: this graph profiles the percentage of a frame period used to
execute the audio synthesis microcode on the RSP.
.PP
8) CPU: this profiles the percentage of a frame period used by the
during the call to alAudioFrame.
.PP
9) L/R: this profiles the peak output levels of the final output
samples that are sent to the audio DACs.  The scale is in dBs with
the top of the meter at 0 dB and then decreasing in 3 dB increments
per LED.  Signal levels above -3 dB are indicated by a yellow caution
LED. Signal presence is indicated by the bottom LED being turned on
(ie. any non-zero sample will turn on the bottom LED).  Signal clipping
is indicated by a red LED that appears above the meter.  Note that
the clip detector does not detect true clipping, rather it detects
when a sample magnitude value of 0x7fff appears.  This could be a
legitimate value from a normalized sound or it could be a limited
value caused by overflow.  
.RE
.PP
Be aware that the resource demands for audio synthesis varies
on a frame by frame basis.  This is because it must share the
processing resources with the other parts of the system.  This
means that the profile values will vary each time a given 
sequence is played.  Therefore, the readings should be used
as an approximation, not as an accurate measurement of resource usage.
Also note that the CPU measurements can be affected by any debugging
messages produced by the audio library.  Also the N64 code was not
optimized by
.I gcord
and so is not displaying best case performance.
.SS The Nintendo 64 Menu
If the N64 development board is available, an N64 menu will appear
in the editor.  This menu provides control over some of the N64
functionality.  The "Clear Profile Values" item resets the MIDI player
and causes all the maximum values to be reset to zero.
The "Configure Hardware" menu brings up a dialog which can be used to
set some of the Audio Library configuration parameters.  A description
of the various configuration parameters is listed below.  After setting
the configuration parameters, press the okay or apply button to make
the changes take affect.  Reconfiguration may take a few seconds since
any open bank file must be fully reloaded to the N64.  Configurations
can be saved and reloaded at a later time using the "Save Configuration..."
and "Load Configuration..." commands.  These commands ask you to name
the configuration file you want to save or load before proceeding.
Finally, the "Reset Hardware" command resets the entire N64 hardware
forcing the N64 code to be reloaded and the audio reconfigured.  Use this
command to try to recover the N64 if it crashes for any reason.
.PP
Here is a description of each of the configuration parameters:
.RS 5
.SS Audio Frame Preferences
output rate: the requested sampling rate of the audio interface in Hz.
.PP
samples per frame: the requested number of samples to be synthesized per
audio frame.  For maximum efficiency use a value that is a multiple of
160 samples (eg. 640).  A larger number means a slower frame rate while a smaller
number means a faster frame rate.  This number, along with the output rate
can be used to simulate a game running at 60 Hz or 30 Hz.  For example,
at an output rate of 44100 Hz, setting this value to be 735 will produce
an frame rate of 60 Hz.
.PP
max commands per frame: the maximum number of ABI commands that can be
executed per audio frame.  This directly corresponds to the size of the
audio command list buffer that stores the ABI commands.
.SS Audio DMA Preferences
Note that since audio sample DMA is implemented by the game application,
the following configuration parameters may not be applicable to your
game.  Keep this in mind when setting these parameters.
.PP
DMA buffers: the number of available buffers for performing DMA requests.
.PP
DMA buffer size: the size of each DMA buffer.  Smaller buffer sizes normally
require more DMA requests while larger buffer sizes normally require
fewer DMA requests.
.PP
max DMA requests: the maximum number of DMA requests that can be made.
This value directly affects the size of the DMA message queue setup by
the N64 code.
.PP
# frames to hold DMA buffers: the number of frames that must elapse before
the N64 code will free a DMA buffer for reuse.  While the buffer is being
"held", its samples remain available for other requests that may ask for 
the same samples.  In some cases, the same samples may be used over and
over again so holding them in memory is faster than performing a DMA from
ROM.
.SS Synthesizer Preferences
max virtual voices: the maximum number of virtual voices available to
both the sythesis driver and the MIDI player.
.PP
max physical voices: the maximum number of physical voices available.
If this is less than virtual voices then voice stealing is enabled.
.PP
max control updates: the maximum number of control updates each physical
voice is able to store.  Control updates store data such as volume
changes, pitch changes, etc.  This value directly affects the memory
allocated for control data.
.SS MIDI Player Preferences
max channels: the maximum number of channels available for MIDI messages.
Normal MIDI systems support 16 channels.  This affects how much memory
is allocated to store channel information.
.PP
max events: the maximum number of event updates that the synthesizer
is able to store.  Event updates store sequence data such as start
commands, MIDI commands, etc.  This value directly affects the memory
allocated for event data.
.RE
.SH BUGS
The following is list of the currently known bugs or problems.
.RS 5
.PP
- if the Nintendo 64 crashes for any reason, then if the
.I ie
tool tries to communicate with it, it will hang waiting for a reply.
The only way to recover from this is to kill the tool.  If you
see that the Nintendo 64 has crashed (the processor bars on the Nintendo
64 monitor have stopped moving) then try the "Reset Hardware" command
from the N64 menu.  If this fails, save your work immediately
and relaunch the tool to reestablish communication.
.PP
- when editing files with many assets, the popup menus may get too
big to display all the assets.  To work around this problem,
Alt-click the asset to text edit instead of using the popup menu edit.
.PP
- each time an asset is created, either by opening, importing, or
inserting assets, memory on the Nintendo 64 is used up that cannot
be released.  To avoid running out of memory (which is difficult
to do), use the Close command to remove all assets from the editor
and from the Nintendo 64 memory space.
.PP
- when naming assets, only use letters, numbers, and an underscore.
Periods or other symbols are not recognized by
.I ic
so they are not recognized by
.I ie
as well.
.PP
- when importing assets,
.I ie
will recognize soundfiles only by the file suffix which can either
be .aiff or .aifc.  Any other suffix will cause the file to be opened
as a .inst file.  Be sure your soundfiles are suffixed properly.
.PP
- keymaps are not sorted before being downloaded to a bank which
may cause seemingly improper sound mapping when auditioning.  It is
up to the user to ensure that an instrument's keymaps are sorted
properly for auditioning.  Note, that
.I ic
will properly sort the keymaps (unless overriden with the -n option)
so it is not necessary to have them sorted for compiling banks.
.PP
- sometimes the column widths do not get adjusted properly to 
fit in the field's value.  Try editing the field or for a temporary
fix, edit the column edges by clicking the middle button on the edge
while holding the shift key down.
.PP
- if two or more instruments share the same sound asset and the
instruments are opened so that the same sound appears more than once
in the display, the editor may be confused over which sound instance
should be operated on.  Be careful when the same sound is being shared.
.PP
- when
.I ie
is initially launched with a new file, a harmless warning
from XbaeMatrix (the list item) may appear. 
.RE
.SH "SEE ALSO"
.IR ic (1P),
.IR startmidi (1)