MIDI Tools Plug-in for Maya: Documentation

Paris Mavroidis, Aug. 2006

1. Introduction
2. Setup
3. Suggested Pipeline
4. Controls
5. How Behaviors Work
6. Clip Layout Example
7. Credits/Notes

1. Introduction

 The MIDI Tools plug-in for Maya allows users to import MIDI files into a scene and associate note events with animation clips in an intuitive and versatile way. It is designed to give animators the freedom to experiment with different approaches to musically-driven animation.

2. Setup
  1. Make sure the “paris_midiTools.mll” plug-in file has been loaded in Maya using the Plug-in Manager (“Window->Settings/Preferences->Plug-in Manager”). For the plugin to always be listed without browsing for it, the file should be moved to the “../bin/plug-ins/” folder in your Maya directory.
  2. Source the “paris_midiTools.mel” script file (in the Script Editor, “File->Source Script...”), or move the file to one of Maya's script paths (eg. “My Documents/Maya/scripts/” or “My Documents/Maya/7.0/scripts/” ).
  3. Type “paris_midiTools” into the command line and press “Enter”.

3. Suggested Pipeline

4. Controls

A

Songs – A list of imported MIDI files. The info box below the list shows information about the currently selected file.
Rename – Rename the currently selected song. Song names must be unique.
Remove – Remove the currently selected song. This will remove all the information stored about the MIDI file, as well as any related animation clips which have been placed in the Trax editor. The DELETE key can also be used to do the same thing.
New – Import a new MIDI file. You will need to specify a file, a unique name for the song and the frame on which the animation should begin.
Reload – Reload the MIDI file for the selected song. You will need to specify the file once again.
Evaluate Animation – This will create and place Animation Clips for the selected song, according to the behaviors which have been specified by the user. Previous clips which exist in the Trax editor for the song will be removed. This process can take a few minutes.

B

Tracks – A list of tracks belonging to the currently selected song. The tracks are named according to the way they were named in the original MIDI file, but these names can be changed.
Rename – Rename the currently selected track.
Remove – Remove the currently selected track. The DELETE key can also be used to do the same thing.
Select Track Node – Select the Dependency Graph node for the currently selected track. This feature should generally not be used except by advanced users who want to make direct connections using the key-frames that were created from MIDI note events.

C

Notes – A list of notes belonging to the currently selected track. The notes are numbered according to the MIDI file specification (0=C0, 12=C1, 127=G10, etc.). Three asterisks after the note (***) indicate that the note is used in the given song. A number in parentheses indicates the number of behaviors associated with that note. Multiple notes can be selected at one time, if the user wishes to apply the same behavior to multiple notes at once.
Show Active Notes Only – Indicates whether all possible notes (0-127) should be shown, or only the notes that are actually played in the song.

D

Behaviors – A list of behaviors belonging to the currently selected note. Selecting a behavior allows the user to edit its parameters in the “Edit Current Behavior” panel (see E, below). Note: changing the parameters of a behavior will not change the parameters of any other existing behavior, even if they have the same name, or are associated with the same notes or animation clips.
Remove – Remove the currently selected behavior.

E

Edit Current Behavior Panel – When a behavior is selected, this panel will show all of the information about that behavior. Any of the values pertaining to the behavior can also be edited here, but the changes will not take effect until the “Update Behavior” button is pressed. For more information about how behaviors work, see section 4 below.

F

Create New Behavior Panel – When one or more notes are selected, this panel allows the user to create behaviors and apply them to those notes by pressing the “Add Behavior to Note(s) ” button. The “---> ” button transfers all the values from the currently selected behavior into the Create New Behavior Panel while the “Reset” button resets all the values in the panel. For more information about how behaviors work, see section 4 below.

G

Refresh – Refreshes the midiTools window. Using this button should not be necessary unless changes have been made to midi-related notes directly in the dependency graph or the attribute editor (this is not recommended).
Close – Closes the midiTools window.

5. How Behaviors Work

  • Behaviors dictate how animation clips are placed on the trax editor, given a note's “on” and “off” events throughout the MIDI song. One or more behaviors can be associated with a note, but a single behavior cannot be associated with more than one note. If multiple notes are selected and a behavior is added to all of them simultaneously, separate behaviors with the identical values are added to each note.

  • Up to four clips can be specified in a behavior, each for a different event pertaining to the note (“Note On”, “Note Off”, “Sustain”, “Rest”). At least one of the four clips must be specified for a behavior to be valid. The animation clips created by a single behavior will be placed and scaled in such a way as to not overlap with each other, even if the clips are acting on different character sets. Section 6 (below) illustrates the layout of clips on the trax editor given the same MIDI note events but different behavior specifications. For a better understanding of how behaviors work, examining this illustration is highly recommended. Another useful way to see how behaviors work is examining the downloadable example files and their explanations.

  • NOTE: Unless it is intentional, it is best to prevent clips which act on the same attributes from overlapping in the trax editor. For example, when creating animation clips, it is highly recommended to only key the attributes which are actually being changed in the clip.

Name – The name of the behavior.

Blend Clips – If enabled, the clips created by this behavior will be blended with the other clips that act on the same character set. Blends are created between notes that are next to each other on the trax editor, provided that the clips are either overlapping or have space between them. See examples 6 and 10 below.

Every ___ Starting At ___– The numbers entered into these fields specify which note events to take into account when applying the behavior. Values of 1 and 1 will apply the behavior for every note, starting on the first note. An example in which these values are used differently is when the user wishes to use alternating behaviors on alternating occurrences of the note. This would require setting values of 2 and 1 for one behavior and values of 2 and 2 for the other behavior. Example 8 below demonstrates how clips are placed given values of 2 and 2 (the rest are all examples of 1 and 1).

Velocity Median – If the user wants all animation clips to be inserted with a weight of 1.0, this value should remain at 0. If the user wants animation clips to be weighted according to the velocity of the note event they are associated with, the “velocity median” value should reflect the velocity that corresponds to a weight of 1.0. For note velocities above and below this median, the clips will be weighted accordingly. Note: the weighting of clips will only affect “Note On” and “Note Off” clips (see below).

On – These are the controls for the source clip or pose associated with “Note On” events. To specify a clip or pose, click on the “...” button and choose from the available clips and poses. The “clr” button clears the clip if one has been specified. The “offset” value defines how many frames before or after the “Note On” event the clip should start (see example 3, below). If the clip is scaled, the offset is also scaled accordingly. The “rel” checkbox defines whether the clip should affect values relatively or absolutely. The “stretch” checkbox specifies whether to stretch the clip to a scale higher than 1.0 if space on the timeline allows for it (see example 2, below).

Off – These are the controls for the source clip or pose associated with “Note Off” events. To specify a clip or pose, click on the “...” button and choose from the available clips and poses. The “clr” button clears the clip if one has been specified. The “offset” value defines how many frames before or after the “Note Off” event the clip should start (see example 3, below). If the clip is scaled, the offset is also scaled accordingly. The “rel” checkbox defines whether the clip should affect values relatively or absolutely. The “stretch” checkbox specifies whether to stretch the clip to a scale higher than 1.0 if space on the timeline allows for it.

Sus – These are the controls for the source clip or pose associated with the periods of time between “Note On” and “Note Off” events (sustain). To specify a clip or pose, click on the “...” button and choose from the available clips and poses. The “clr” button clears the clip if one has been specified. The “scale>” value defines the minimum scale for the clip. Thus, if the period of time between a “Note On” and a “Note Off” event is smaller than the sustain clip's length scaled by this minimum, no clip will be placed within this space. The “rel” checkbox defines whether the clip should affect values relatively or absolutely. If “stretch” is enabled, the sustain clip will be stretched so that only one instance of it covers the entire sustain space. If it's disabled, then multiple sustain clips may be laid down, depending on the length of the sustain.

Rest – These are the controls for the source clip or pose associated with the periods of time between “Note Off” and “Note On” events (rest). To specify a clip or pose, click on the “...” button and choose from the available clips and poses. The “clr” button clears the clip if one has been specified. The “scale>” value defines the minimum scale for the clip. Thus, if the period of time between a “Note Off” and a “Note On” event is smaller than the rest clip's length scaled by this minimum, no clip will be placed within this space (see example 9, below). The “rel” checkbox defines whether the clip should affect values relatively or absolutely. If “stretch” is enabled, the sustain clip will be stretched so that only one instance of it covers the entire rest space. If it's disabled, then multiple rest clips may be laid down, depending on the length of the rest.

6. Clip Layout Example

 The following diagram illustrates the way that different behavior specifications for a note result in different placements of clips on the trax editor. The MIDI notes are shown in grey.

7. Credits / Notes

  • The Midi Tools Plug-in For Maya was developed by Paris Mavroidis at the Digital Arts Research Lab at Pratt Institute.

  • The plug-in makes use of a Midi file parser written by Gary P. Scavone, 2003. The parser is part of the “Synthesis Toolkit in C++” (STK).

  • Please send the developer examples of work you've made using this plug-in.

  • Please feel free to credit the developer in your work.

  • Contact: paris@parismav.com

  • Personal Website: http://www.parismav.com

  • Digital Arts Lab Website: http://dal.pratt.edu

  • STK Website: http://ccrma.stanford.edu/software/stk/