StopChannel channel

Parameters

channel - channel handle returned by PlaySound or PlayMusic

Description

Stops a playing channel for good.

Every sound that has to end on your terms rather than its own goes through here: the music when the player leaves a level, an engine loop when the car is destroyed, a siren when the alarm is cleared, an ambience when a door closes behind you. Anything started with LoopSound will run forever otherwise, so this is the only way out of a loop.

It is a Channel command, so it needs the handle you kept from PlaySound or PlayMusic. If you did not keep the handle you cannot stop the sound - the usual fix is to store the channel for anything long-running and ignore the return value only for one-shot effects.

Stopping is final. Unlike PauseChannel, which holds the playback so ResumeChannel can pick it up again, a stopped channel cannot be restarted - play the sound again to get a new channel. ChannelPlaying reports False afterwards.

It stops the playback, not the sound in memory, so the loaded sound is still there to play again. Calling it on a channel that has already finished is harmless. It works on any channel, whether it came from a sound effect or from PlayMusic.

See also: PauseChannel, ResumeChannel, ChannelPlaying, PlaySound, FreeSound.

Example

; StopChannel Example
; -------------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

; A short tone looped endlessly - it will hum forever unless stopped
snd=LoadSound("media/beep.wav")
LoopSound snd
channel=PlaySound(snd)

While Not KeyDown(1)

    ; S stops the channel dead. Unlike PauseChannel there is no
    ; resuming - the channel is finished for good.
    If KeyHit(31) Then StopChannel channel

    ; Space starts a fresh looping channel with PlaySound
    If KeyHit(57) Then
        StopChannel channel
        channel=PlaySound(snd)
    End If

    ; ChannelPlaying confirms the stop: 1 while humming, 0 after
    playing=ChannelPlaying(channel)

    Cls

    If playing Then
        Color 80,255,80
        Oval 296,190,48,48,True
        Color 255,255,255
        Text 320,260,"channel humming - ChannelPlaying = 1",True
    Else
        Color 70,70,70
        Oval 296,190,48,48,False
        Color 160,160,160
        Text 320,260,"stopped - ChannelPlaying = 0",True
    End If

    Color 255,255,255
    Text 0,0,"S: StopChannel   Space: start a new loop   Esc: exit"

    Flip

Wend

StopChannel channel

End

Index