| asset - a ready audio mix asset, from FindWorldAsset |
|
Tries out an audio mix, remembering the mixer set-up to go back to. Use it to audition a mix - in an editor, or on an options screen - without losing the settings in use. It saves the current mixer settings, including any made with the group and master commands, then applies the mix. Hand the token it returns to EndAudioMixPreview to put everything back. While a preview runs, other mixes, other previews and the group, master and effects setters are refused, so nothing can change what the preview will restore. Sound and channel commands and the meters still work. Returns a token, or 0 with the reason in AudioLastError(). Sounds with effects need InitAudioEffects before they play. Freeing the world that loaded the mix does not end the preview: keep the token and end it yourself. For the full story, see the Sound definitions and audio mixes guide and its complete ResourcePresets.bb sample. See also: EndAudioMixPreview, ApplyAudioMix, InitAudioEffects, AudioLastError. |
; ApplyAudioMix Example
; ---------------------
; Effects must be initialized before the first WAV/Ogg playback
If Not InitAudioEffects() Then RuntimeError AudioLastError()
; Loading resources needs 3D graphics
Graphics3D 640,480,0,2
SetBuffer BackBuffer()
; A looping machine hum in the ambience group, sending to the reverb
sound=LoadSound("../../../samples/audio/media/machine.wav")
If sound=0 Then RuntimeError "The audio sample media is missing."
LoopSound sound
SoundVolume sound,0.25
SoundGroup sound,3
SoundReverb sound,0.6
; The stone room mix: reverb, an echo and a filtered ambience group
document=LoadResourceDocument("../../../samples/audio/resources/room.audiomix")
If document=0 Then RuntimeError ResourceDocumentError()
library=LoadResourceDocumentAsync(document)
FreeResourceDocument document
While Not WorldReady(library)
If WorldLoadState(library)=WORLD_LOAD_FAILED Then RuntimeError WorldLoadError(library)
UpdateAsyncLoads 2
Wend
room=FindWorldAsset(library,"resource")
; Meters make the audio state visible on screen
AudioMasterMeter True
AudioGroupMeter 3,True
channel=PlaySound(sound)
If channel=0 Then RuntimeError "Unable to play the example sound."
preview=0
message$="Playing with the default mix"
While Not KeyDown(1)
; Space tries the room mix for a while, and gives back the old mix
If KeyHit(57) Then
If preview=0 Then
preview=BeginAudioMixPreview(room)
If preview=0 Then message=AudioLastError() Else message="BeginAudioMixPreview: previewing the stone room"
Else
If EndAudioMixPreview(preview) Then
preview=0
message="EndAudioMixPreview: the previous mix is back"
Else
message=AudioLastError()
EndIf
EndIf
EndIf
; A applies the room mix for good - refused while a preview runs
If KeyHit(30) Then
If ApplyAudioMix(room) Then message="ApplyAudioMix room returned True" Else message=AudioLastError()
EndIf
Cls
Text 0,0,"Space: preview / restore the room mix A: apply it for good Esc: exit"
Text 0,20,message
Text 0,60,"Ambience group RMS: "+AudioGroupRMS(3)
Text 0,80,"Master RMS: "+AudioMasterRMS()
Flip
Wend
; Stop the sound before ending a preview, then free the mix's world
StopChannel channel
If preview<>0 Then EndAudioMixPreview preview
FreeWorld library
FreeSound sound
End