Blitz3D+ Command Reference

SoundPitch sound,pitch

Parameters

sound - handle of a sound loaded with LoadSound

pitch - playback rate in hertz; the sample's own rate plays it normally

Description

Sets the playback rate a sound will start at the next time it is played.

The number is a sample rate in hertz, and it is compared against the rate the file was recorded at. Play a 22050 Hz sample at 22050 and it sounds normal; at 44100 it plays twice as fast and an octave up; at 11025 it plays half speed and an octave down. Pitch and speed move together, exactly like changing the speed of a record.

That makes it the cheapest variety trick in games. Pick a random pitch within a few percent each time a footstep, gunshot or coin plays and a repeated effect stops sounding like a loop. Slide the pitch up as a power meter charges, or drop it as a machine winds down, and you get a whole extra sound out of one file.

This is a Sound command, so it applies to the next PlaySound and every one after it. To bend the pitch of something already playing - a revving engine - use ChannelPitch on the channel handle.

Because it changes the rate rather than resampling, a looping sound also loops faster or slower, and a pitched-up sound finishes sooner. Extreme values are clamped by the audio engine, so very large ratios will not keep climbing.

See also: ChannelPitch, SoundVolume, SoundPan, PlaySound, LoadSound.

Example

; SoundPitch Example
; ------------------

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

; Load the sound into memory - beep.wav was recorded at 11025 hertz,
; so 11025 is its natural pitch
snd=LoadSound("media/beep.wav")

hertz=11025

While Not KeyDown(1)

    ; Up/Down arrows tune the playback frequency
    If KeyDown(200) And hertz<33000 Then hertz=hertz+150
    If KeyDown(208) And hertz>2000 Then hertz=hertz-150

    ; SoundPitch changes the SOUND itself, so it must be set BEFORE
    ; PlaySound - every later play uses it. To retune a sound that is
    ; already playing, use ChannelPitch on its channel instead.
    SoundPitch snd,hertz

    ; Space plays the sound at the current pitch
    If KeyHit(57) Then PlaySound snd

    Cls

    ; A frequency meter: the bar grows with the hertz value
    Color 100,100,100
    Rect 100,240,441,20,False
    Color 255,180,80
    Rect 102,242,(hertz-2000)*437/31000,16

    Color 255,255,255
    Text 0,0,"Up/Down: set pitch   Space: play sound   Esc: exit"
    Text 0,20,"SoundPitch snd,"+hertz+"   (recorded at 11025 Hz)"

    Flip

Wend

End

Index