# DoSound (Kernel)

> Do sound handles all sound related functions such as playing, loading, unloading, stopping, pausing, etc. It uses the first parameter to identify its subfunction, and the following parameters vary.

`DoSound`(sndINIT soundObj)

  Sets up the specified sound object. It loads the sound resource specified by the sound object’s number property and sets it’s status property to ssINITIALIZED.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

  Example:

      (DoSound sndINIT soundObj)

`DoSound`(sndPLAY soundObj)

  Plays the sound specified by the given sound object and sets the object’s status property to sndPLAYING.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

`DoSound`(sndDISPOSE soundObj)

  Disposes of the sound specified by the given object unloading it and removing it from the sound system.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

`DoSound`(sndSET_SOUND [fTurnOn])

  Determines if the sound system is muted or not, and optionally mutes or unmutes it.

  Parameters: | fTurnOn (boolean) – Optional parameter to unmuted or mute the sound. If TRUE, the sound system is unmuted.
  Returns: | TRUE if the sound system is unmuted, FALSE otherwise.

  Example:

      ; If the sound system is not muted, mute it.
      (if (DoSound sndSET_SOUND)
              (DoSound sndSET_SOUND FALSE)
      )

`DoSound`(sndSTOP soundObj)

  Stops playing the sound specified by the given sound object and sets the object’s status property to sndSTOPPED.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

`DoSound`(sndPAUSE soundObj)

  Pauses the sound specified by the given sound object and sets the object’s status property to ssPAUSED.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

`DoSound`(sndRESUME)

  Important

  SCI0 only.

  Resumes playing sounds after a game has been resotred.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

`DoSound(sndVOLUME [volume]) **SCI0**`

`DoSound(sndMASTER_VOLUME [volume]) **SCI1.1**`

  Returns the currently set master sound volume, which is a number ranging from 0 to 15. Optionally sets the master volume.

  Parameters: | volume (number) – Optional new volume to set it to.
  Returns: | The current volume.

`DoSound`(sndUPDATE soundObj)

  Tells the sound system to update the specified sound. It notifies it that the sound has changed so its priority and loop properties are re-evaluated.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

`DoSound(sndFADE soundObj) SCI0`

  Important

  SCI0 only.

  Fades the specified sound for roughly two seconds, then stops it, setting it’s status property to ssSTOPPED.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

`DoSound(sndFADE soundObj targetVolume fadeTicker fadeStep stopAfterFade) SCI1.1`

  Important

  SCI1.1 only.

  Fades the sound. This provides more options than the SCI0 version.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`. targetVolume (number) – The target volume, ranging from 0 - 127. fadeTicker (number) – Unknown (25 is a common value to specify). fadeStep (number) – The volume increment to fade each game cycle (10 is a common value). stopAfterFade (boolean) – If TRUE, the sound is stopped after the fade is complete.

`DoSound`(sndCHECK_DRIVER)

  Important

  SCI0 only.

  Checks to see if the sound driver is installed. If it is, it returns TRUE, otherwise, it returns FALSE.

  Example:

      (if (not (DoSound sndCHECK_DRIVER))
               (Print "The sound driver is not installed!")
      )

`DoSound`(sndSTOP_ALL)

  Important

  SCI0 only.

  Stops all the sounds currently playing.

`DoSound`(sndGET_POLYPHONY)

  Important

  SCI1.1 only.

  Returns: | The number of voices the sound hardware is capable of playing.

`DoSound`(sndGET_AUDIO_CAPABILITY)

  Important

  SCI1.1 only.

  Determines digital audio support.

  Returns: | TRUE if digital audio support is available, otherwise FALSE.

`DoSound`(sndSUSPEND)

  Important

  SCI1.1 only.

  Unkonwn functionality. Not used in any Sierra games?

`DoSound`(sndSET_HOLD soundObj marker)

  Important

  SCI1.1 only.

  Sets the hold spot where the sound should be looped at. This is commonly used for engine sounds that want to loop at different spots for different pitches as the engine is starting and stopping.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`. marker (number) – Index of a hold marker in the Sound resource.

  Note

  SCI Companion doesn’t currently support editing the hold markers in a sound resource.

`DoSound`(UPDATE_CUES soundObj)

  Important

  SCI1.1 only.

  Updates the sound.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`.

`DoSound`(sndSEND_MIDI soundObj channel command controller parameter)

  Important

  SCI1.1 only.

  Sends MIDI information to the sound resource.

  Parameters: | soundObj (heapPtr) – An instance of `Sound`. channel (number) – The MIDI channel (e.g. 0-15). command (number) – The MIDI command. controller (number) – The MIDI controller. parameter (number) – A parameter for the command.

`DoSound`(sndGLOBAL_REVERB reverb)

  Important

  SCI1.1 only.

  Parameters: | reverb (number) – A reverb level (0 - 10).
  Returns: | The previous reverb level.