Functions as the audio instrument editor for Nintendo 64 audio
ie [ -b <.inst file> ] [ -c <.cnfg file> ] [ -v ]
The following information describes the initial release of this tool. Because it is an initial release, there are known problems and bugs, so use it with caution. Please refer to the known bug list at the end of this article to help you prevent any loss of work.
The ie tool has three primary uses:
Command Line Options
The editor portion of the 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.
The ie tool can read, write, and edit .inst files. The .inst files contain a description of a Nintendo 64 bank that can be compiled into an actual Nintendo 64 bank file by using the ic tool (the instrument compiler).
The .inst bank description is made up of several components such as instruments, sounds, envelopes, and so on. 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 example, bank assets reference instrument assets, so instruments are children of a bank parent. Similarly, instrument assets reference sound 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.
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.
To edit the value of an asset's parameters, simply click 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 pop-up 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 that can be moved around from field to field by using the arrow keys and the Alt key. (If you don't hold the Alt key down, 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. Press the Esc key to cancel any text editing. Note that some fields (such as a wavetable's sample rate) cannot be edited; they 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 set the value to a preset default value.
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 the # column opens up the parent and display its children.
Because 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 closes the asset. The # field can be edited by clicking the field. This brings up a pop-up menu showing a list of assets that are currently not children of the selected asset. Choosing one of these assets adds it to parent's list of children. Double-clicking the icon of a child automatically opens up the children's folder so you can edit their parameters. For example, double-clicking an instrument's sound opens up the sound folder for editing. Likewise, double-clicking a sound's envelope opens up the envelope folder for editing.
Before you can 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 section 18.5.2.2 "Nintendo 64 MIDI Playback" section of this article. When a bank is online, bank assets can be auditioned by clicking 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 always plays a C4 note. Auditioning sounds, keymaps, envelopes, and wavetables plays 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. Please confirm if the keymap of the sound is properly set before auditioning.
The File menu contains commands for opening, closing, and saving .inst files. The Open command on the File menu brings up a dialog for selecting an .inst file to edit. Only one .inst file can be open at a time. The Close command removes all bank assets and allows a new file to be edited. The Save and Save As commands write the file to disk.
The Edit menu commands are currently not supported.
The Asset menu contains commands for inserting and deleting assets. The Insert command creates a new asset and places it at the end of the list. The asset automatically has default parameter values. To insert an asset in the middle of the list, select the asset located where you want the new asset to appear, and then choose the Insert command from the Asset menu. The selected asset will appear below the newly created one. To delete assets, select one or more assets, and then choose the Delete command from the Asset menu. A short cut for creating an asset and adding it to a parent is provided by the "Insert Child" command. This command inserts 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, use the "Import command" to import other .inst files as well as .aiff and .aiff-c files. This is currently the only way to create wavetable assets.
The Select menu contains useful commands for selecting certain types of assets. The "Select Parents" command selects 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 selects all the sound assets that use the given keymap and will automatically display the sound folder. The "Select Orphans" commands selects all the folder's assets that do not have any parents. This is useful for determining which assets aren't being used anywhere -- so they can be deleted.
The ie tool supports creating, editing, and auditioning effects on the Nintendo 64. Effects are tightly coupled to the N64 Audio Library, so they appear for editing only if an N64 development system board is present. Otherwise, only bank components can be edited. If an N64 development system board is present, the ie tool automatically creates five built-in effects for auditioning and editing. These effects are small room, big room, chorus, flange, and echo. To add to the built-in effects, you can create custom effects from scratch as well.
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 except for the delay fields (length, input, and output). The delay parameters are displayed in msecs. They must be converted to samples and aligned to an 8 sample boundary before being used to configure a game. (The ie tool does this automatically when it loads to hear effects.)
Gloss description: Sample is a smallest unit for the aspMain audio microcode to interpret. It is mainly used when synthesized driver generates audio command lists.
Effects and effects sections can be edited just like editing bank assets. However, there are some special consideration for editing effects:
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 be greater than input/output delays by 160 samples. The ie tool automatically enforces the 8 sample boundary rule when it loads the effect on the N64, however it does not enforce the 160 sample rule. 160 sample rule depends on the chorus rate. Be careful when editing input/output delays so that it does not approach within 160 samples of the delay line's length. If it exceeds the limit, normally it creates artificial sounds such as click and pop.
When an effect is "online" (that is, 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. To make these changes to an online effect, you must "offline" the effect first.
Effect sections can have only one parent. Once it is being used by a parent effect, it will not be available for other effects to use it.
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 unnecessary memory.)
Initially, no effects are loaded onto the N64. 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 because the Audio Library must be initialized with an effect. This may take a few seconds because 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.
Currently, effect assets can not be saved to disk. This is because there is no standard .fx file like there is a standard .inst file for bank assets. However, effects can be restored from disk with a configuration (.cnfg) file. This will be described in detail later. The Audio Library treats effects as part the configuration data, so 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, see the following file.
/$ROOT/usr/src/PR/assets/banks/ie.cnfg
When 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 ie will not be able to audition any instruments or edit effects. In addition, ie will also boot up the gload tool to act 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 gload is running at the time ie is launched, ie will fail to run.
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.
For an example of a .cnfg file and its reserved words, see this file:
/$ROOT/usr/src/PR/assets/banks/ie.cnfg
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 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 ie. When 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 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 all of the following conditions are met:
When a bank is online, bank assets can be auditioned from the editor by clicking 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 by the startmidi tool.
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 play back the sequence. The profiler keeps track of the following resources:
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 (that is, 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.
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 gcord and so is not displaying best case performance.
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 as 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. Lastly, 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.
Following is a description of each of the configuration parameters:
<Audio Frame Preferences>
<Audio DMA Preferences>
Note that audio sample DMA is implemented by the game application, so the following configuration parameters may not be applicable to your game. Keep this in mind when setting these parameters.
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 again just like a local cache so holding them in memory is faster than performing a DMA from ROM to RDAM.
<Synthesizer Preferences>
<MIDI Player Preferences>
The following is list of the currently known issues in version 2.0g.
ic, startmidi
1999/04/30 Changed Format