al - Audio Library Functions gDP - DP GBI Macros gdSP - General GBI Macros gSP - SP GBI Macros gt - Turbo Microcode RDP gu - Graphics Utilities Math - Math Functions nuSys - NuSystem os - N64 Operating System sp - Sprite Library Functions uh - Host to Target IO 64DD - N64 Disk Drive
|
ieFormatie [-b <.inst file>] [-c <.cnfg file>] [-v] What This Tool Does It is the instrument editor for Nintendo 64 audio. 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:
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. Bank Editing 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. 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. Editing Assets 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. 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 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. Auditioning Assets 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 "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. The File Menu 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 so choosing Open from the File menu when another .inst file is currently open will close the open 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 commands write the file to disk. The Edit Menu The Edit menu commands are currently not supported. The Asset Menu 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-c files. This is currently the only way to create wavetable assets. The Select Menu 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 keyman is selected, the Select Parents command selects all the sound assets that use the given keyman 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. Effects 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 is present. Otherwise, only bank components can be edited. If an N64 development system 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. 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. 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.) Effects Editing Effects and effects sections can be edited. 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:
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. 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 a standard .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.) 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, which defines a custom effect: /$ROOT/usr/src/PR/assets/banks/ie.cnfg Nintendo 64 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. 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, see this file: /$ROOT/usr/src/PR/assets/banks/ie.cnfg. 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 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:
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 play back the sequence. The profiler keeps track of the following resources:
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.
Following is a description of each of the configuration parameters: Audio Frame Preferencesoutput rate: the requested sampling rate of the audio interface in Hz.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 (for example, 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. 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. Audio DMA PreferencesNote 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.DMA buffers: the number of available buffers for performing DMA requests. DMA buffer size: the size of each DMA buffer. Smaller buffer sizes usually require more DMA requests while larger buffer sizes usually require fewer DMA requests. max DMA requests: the maximum number of DMA requests that can be made. This value directly affects the size of the DMA message queue set up by the N64 code. # 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. Synthesizer Preferencesmax virtual voices: the maximum number of virtual voices available to both the synthesis driver and the MIDI player.max physical voices: the maximum number of physical voices available. If this is less than virtual voices then voice stealing is enabled. 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, and so on. This value directly affects the memory allocated for control data. MIDI Player Preferencesmax 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.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, and so on. This value directly affects the memory allocated for event data. BugsThe following is list of the currently known bugs or problems.
ic startmidi
|