Miles Sound System SDK 7.2a

AIL_set_sequence_volume

The function AIL_set_sequence_volume establishes a scaling factor for the value of each MIDI Part Volume Control Change (controller 7) event occurring in a sequence.

void AIL_set_sequence_volume(
  HSEQUENCE S,
  S32 volume,
  S32 milliseconds
);

In Parameters

S: indicates the sequence whose volume controller event values are to be scaled.
volume: specifies the volume-scaling value in standard MIDI units, from 0 (minimum) to 127 (maximum, or no scaling).
milliseconds: specifies a delay time over which the requested volume-scaling change should take place.

Discussion

Volume values are expressed as a number from 0 to 127 which acts as a multiplier for the normal (unscaled) volume levels specified in a sequence's MIDI Control Change events. The default volume-scaling value is 127, indicating no change in the sequence's Part Volume controller values.

The milliseconds parameter allows the application to specify a number of milliseconds from 0 (immediate) to 2.1 billion (slightly more than three weeks) over which the relative tempo should ramp up or down to reach the specified value. This graduation time is measured only while the sequence is actually playing; if a sequence is paused during a ramp-up or ramp-down with a call to AIL_stop_sequence, the graduation effect itself will continue, along with the rest of the sequence's performance, upon a subsequent call to AIL_resume_sequence.

Two important differences affect this function's operation under MSS version 3, as compared with MSS version 2. First, the volume value is no longer given as a percentage, but in standard MIDI units from 0 to 127. It is possible to specify volume values greater than 127, but this is not ordinarily desirable since it may cause imbalances in channel volumes relative to each other. Second, the default volume-scaling value is no longer synthesizer-specific. Under MSS version 2, the volume-scaling factor was reduced to 90% with the Roland MT-32 XMIDI driver active, to reduce distortion inherent in the Roland MT-32 synthesizer circuitry. This is no longer the case under MSS version 3, since most MT-32s in the field are now third-party "clones" rather than genuine Roland MT-32 or LAPC-1 synthesizers.

Important!AIL_set_sequence_volume will not affect MIDI channels which contain no MIDI Channel Volume Control Change (7) controller events. All MSS-compatible MIDI sequences should contain Volume Control events near the beginning of each channel; otherwise, each channel will "inherit" the volume level which was established in the last sequence played on that channel.

Group: XMIDI Services
Related Functions: AIL_resume_sequence, AIL_sequence_volume, AIL_set_XMIDI_master_volume, AIL_set_sequence_volume, AIL_stop_sequence
Related Basic Types: HSEQUENCE, MILES_PREFERENCES, S32, void
Related FAQs: I can't seem to change the volume of my XMIDI sequences, what's going on?