ProSound - superclass: SoundClass; super-superclass:MAXWrapper - classID: #(1198500318, 1536265802) 

The ProSound SoundClass introduced in 3ds Max 2010 provides an advanced Sound Object with support for 100 sound channels and extensive MAXScript access.

See also the ProSound Extension topic for an introduction.

Methods:

Sound System Initialization

<boolean>prosound.init <boolean>KeepExistingFile      

Initializes ProSound for MaxScript access. If ProSound is not loaded, it will load itself and become the Sound Object for 3ds Max. If there is already an audio file loaded in the Default SoundClass object of 3ds Max, setting the KeepExistingFile flag to true will add that file as one of the audio tracks in ProSound, thus preserving the existing track.

Returns true if successful, false otherwise.

<boolean>prosound. isActive() 

Returns true if ProSound is the Sound Object for 3ds Max, false otherwise. If the return value is false, call prosound.init() to access all other ProSound MAXScript functions.

<integer>prosound.Version() 

Returns the version of ProSound times 100. For example if the version is 1.4, this function will return 140.

EXAMPLES:

   prosound.isActive () --check whether ProSound is active
   --> ProSound is not active. Call ProSound.Init (true)
   ProSound.Init (true)
   --> Attempting to Load ProSound
   --> ProSound Init Success
   --> true
   prosound.isActive () --try again
   --> ProSound is active.
   --> true
   prosound.version () --get version
   --> 140

<boolean>prosound.unload () 

Unloads ProSound and enables the 3dsMaxDefault SoundClass Object. Returns true if successful, false otherwise.

EXAMPLE:

   prosound.unload () -- unload ProSound and enable Default Sound.

ProSound Dialog Control

<void>prosound.open () 

Opens/Maximizes the ProSound dialog.

If the ProSound is not active, it will activate it as well.

<void>prosound.close() 

Closes the ProSound dialog if it is open.

EXAMPLES:

   prosound.open () -- open the ProSound dialog.
   prosound.close () -- close the dialog.

Adding and Querying Sound Files

<integer>prosound.MaxTracks() 

Returns the maximum number of audio tracks supported in ProSound. Currently, this number is 100.

<integer>prosound.NumTracks() 

Returns the number of audio tracks in use within ProSound. This includes tracks that are inactive, but have a file assigned.

<boolean>prosound.append <filename>AudioFile 

Loads the specified file and appends it to the list of audio tracks. The argument must be the full name of a valid audio file.

Equivalent to using the "Add" button in the ProSound UI.

Returns true if successful, false otherwise.

boolean>prosound.delete <index>Track 

Deletes the specified audio track.

Equivalent to using the "Delete" button in the ProSound UI.

Returns true if successful, false otherwise.

<boolean>prosound.replace <index>Track <filename>AudioFile 

Replaces the audio file at the specified index. The first argument is the Index of the file to replace, the second argument is the full file name of a valid audio file to replace with.

Equivalent to using the "Replace" button in the ProSound UI.

Returns true if successful, false otherwise.

<boolean>prosound.ReloadAll() 

Reloads all audio files in ProSound. Returns true if the reload is successful, false otherwise.

EXAMPLES:

   prosound.append"C:\\WINDOWS\\Media\\chimes.wav"--adds a file
   --> true
   prosound.append"C:\\WINDOWS\\Media\\tada.wav"--adds another
   --> true
   prosound.numtracks() --check the number of tracks
   --> 2
   prosound.delete 1 --deletestrack 1
   --> true
   prosound.replace 1 "C:\\WINDOWS\\Media\\notify.wav"
   --> true
   prosound.numtracks() --get the number of track safter deleting 1
   --> 1
   prosound.maxtracks() --see how many tracks are supported
   --> 100
   prosound.reloadall() --reload all tracks
   --> true

Working With Tracks

<boolean>prosound.active <index>Track 

Returns true if the specified indexed track is active, false otherwise.

<boolean>prosound.SetActive <index>Track <boolean>ActiveState 

Sets the active status of the specified track. Returns true if successful, false otherwise.

EXAMPLES:

   prosound.active 1 --see if track 1 is active
   -->true
   prosound.setactive 1 false --turn it off
   -->true
   prosound.active 1 --see if it is on or off now
   -->false
   prosound.setactive 1 true --turn it back on
   -->true

filename>Name <index>Track 

Returns the name of the file for the specified track.

<integer>prosound.SampleRate <index>Track 

Returns the sample rate of the audio track.

integer>prosound.channels <index>Track 

Returns the number of audio channels for the specified audio track.

EXAMPLES:

   prosound.name 1 --get the name of track 1
   -->"C:\WINDOWS\Media\notify.wav"
   prosound.SampleRate 1 --get the sample rate of track 1
   -->22050
   prosound.channels 1 --get the channels of track 1
   -->2

time>prosound.start <index>Track 

Returns the start frame number for the specified indexed track.

<boolean>prosound.SetStart <index>Track <time>StartFrame 

Sets the start frame of the specified indexed track. Returns true if successful, false otherwise.

time>prosound.end <index>Track 

Returns the end frame number for the specified track.

<boolean>prosound.SetEnd <index>Track <time>EndFrame 

Sets the end frame of the specified track. Returns true if successful, false otherwise.

<boolean>prosound.Shift <index>Track <time>Frames 

Shifts the start and end frames of the specified track by the specified amount. Returns true if successful, false otherwise.

<boolean>prosound.ShiftAll <integer>Frames 

Shifts the start and end frames of all audio tracks by the specified amount. Returns true if successful, false otherwise.

time>prosound.filelength <index>Track 

Returns the length of the specified audio file (in frames). Note that this is the file length, not the track length. So, if the file is 120 frames long, but the track has a start and end frame of 0 and 150, 120 and not 150 is returned. Use prosound.end() and prosound.start() to get the track length.

Equivalent to the "Duration" value in the ProSound UI.

EXAMPLES:

   prosound.start 1 --get the start frame of track 1
   -->0f
   prosound.end 1 --get the end frame of track 1
   -->18.9625f
   prosound.filelength 1 --get the file length of track 1
   -->40.5875f
   prosound.setstart 1 10 --sets the start frame of track 1to 10
   -->true
   prosound.setend 1 123 --sets the end frame of track 1 to 123
   -->true
   prosound.start 1 --check the new start frame of track 1
   -->10f
   prosound.end 1 --check the new end frame of track 1
   -->123f
   prosound.shift 1 50 --shift both start and end by 50 frames
   -->true
   prosound.start 1 --check the shifted start frame of track 1
   -->60f
   prosound.end 1 --check the shifted end frame of track 1
   -->173f
   prosound.shiftAll -50 --shift all tracks back 50 frames
   -->true

<integer>prosound.NumLoops <index>Track 

If this track uses loops, returns the number of loops for the track. Otherwise, calculates the number of complete loops based on track duration and file length.

<boolean>prosound.SetNumLoops <index>Track <integer>NumberOfLoops 

Sets the number of loops for the specified track. It also sets the "Use Loops" option for this track to true. Returns true if successful, false otherwise.

<boolean>prosound.UseLoops <index>Track 

Returns true if "UseLoops" option is enabled for the specified track, false otherwise.

EXAMPLES:

   prosound.numloops 1 --get the loops of track 1 
   -->2
   prosound.setnumloops 1 3 --set the loops of track 1 to 3
   -->true
   prosound.end 1 --check the new end frame of track 1
   -->181.762f
   prosound.useloops 1 --see if track 1 will use loops
   -->true

Playback Controls

<boolean>prosound.backwardScrub() 

Returns the state of the "Permit Backwards Scrubbing" playback option - true if Backwards Scrubbing is enabled, false otherwise.

<boolean>prosound.setBackwardScrub <boolean>BackwardsScrubState 

Sets the "Permit Backwards Scrubbing" playback option. Returns true if successful, false otherwise.

<boolean>prosound.PlayOnce() 

Returns true if the "Play Once" option is enabled, false otherwise.

<boolean>prosound.SetPlayOnce <boolean>State 

Sets the "Play Once" playback option to true or false. Returns true if successful, false otherwise.

<boolean>prosound.UsePlaybackRange() 

Returns true if the "Use Playback Range"option is enabled, false otherwise.

<boolean>prosound.SetUsePlaybackRange <boolean>State 

Sets the "Use Playback Range" playback option to the given Boolean state. Returns true if successful, false otherwise.

<boolean>prosound.SetPlaybackEnd <integer>EndFrame 

Sets the end frame of the "Use Playback Range" playback option. Returns true if successful, false otherwise.

<boolean>prosound.SetPlaybackStart <integer>StartFrame 

Sets the starting frame for the "Use Playback Range" playback option. Returns true if successful, false otherwise.

<boolean>prosound.PingPong() 

Returns true if the "Ping Pong" playback option is enabled, false otherwise.

<boolean>prosound.SetPingPong <boolean>State 

Sets the state of the "Ping Pong" playback option. Returns true if successful, false otherwise.

EXAMPLES:

   prosound.backwardScrub ()-- check if backwards scrubbing is on
   --> false
   prosound.setBackwardScrub true-- enable backwards scrubbing
   --> true
   prosound.backwardScrub () --check again
   --> true
   prosound.playonce () --check the state of the Play Once option
   --> false
   prosound.setplayonce true --set to loop the playback
   --> true
   prosound.useplaybackrange () --see if playback range is used
   --> false
   prosound.setuseplaybackrange true --enable playback range
   --> true
   prosound.setplaybackend 100 --set the playback range end to 100
   --> true
   prosound.setplaybackstart 0 --set the playback range start to 0
   --> true
   prosound.pingpong () --see if ping-pong playback is enabled
   --> false
   prosound.setpingpong true --enable ping-pong playback
   --> true

<boolean>prosound.isPlaybackActive () 

Returns true if the ProSound playback is enabled, false otherwise.

<boolean>prosound.SetPlaybackActive <boolean>State 

Enables or disables the audio playback based on the Boolean argument. Returns true if successful, false otherwise.

<void>prosound.Step() 

Steps forward by one frame and plays the corresponding audio.

<void>prosound.Stepback() 

Steps backwards by one frame and plays the corresponding audio.

EXAMPLES:

   prosound.isplaybackactive() --check if playback is active
   --> false
   prosound.setplaybackactive true --activate playback
   --> true
   prosound.isplaybackactive() --check again if playback is active
   --> true
   prosound.step()
   prosound.Stepback()

Render Controls

<boolean>prosound.export <filename>AudioFile <integer>StartFrame <integer>EndFrame 

Attempts to export the combined audio to the specified filename. The file will be saved in PCM using the Render settings. Returns true if successful, false otherwise.

<boolean>prosound.isRenderActive() 

Returns true if the ProSound audio rendering is enabled, false otherwise.

<boolean>prosound.SetRenderActive <boolean>State 

Enables audio rendering based on the Boolean argument.

Returns true if successful, false otherwise.

EXAMPLES:

   prosound.export "c:\\sounds\\export_test.wav" 0 100
   --> true
   prosound.isrenderactive() --check if rendering is active
   --> false
   prosound.setrenderactive true
   --> true

Metronome Controls

<boolean>prosound.isMetroActive () 

Returns true if the Metronome is enabled, false if it is disabled.

<boolean>prosound.SetMetroActive <boolean>ActiveState 

Turns the metronome on or off depending on the Boolean argument. Returns true if successful, false otherwise.

EXAMPLES:

   prosound.ismetroactive() --check if metronome is active
   --> false
   prosound.setmetroactive true --enable metronome
   --> true
   prosound.ismetroactive() --see if the change worked
   --> true
   prosound.setmetroactive false --disable metronome
   --> true
   prosound.ismetroactive() --should be false (disabled) now
   --> false