The _SNDOPEN function loads a sound file into memory and returns a LONG handle value above 0.
- soundHandle& = _SNDOPEN(fileName$)
Syntax prior to build 20170811/60
- soundHandle& = _SNDOPEN(fileName$[, "[VOL][,][SYNC][,][LEN][,][PAUSE][,][SETPOS]"])
- Returns a LONG soundHandle& value to the sound file in memory. A zero value means the sound could not be loaded.
- The literal or variable STRING sound fileName$ can be WAV, OGG or MP3 file types.
- Older versions of QB64 may support AIFF, RIFF, VOC, MOD and MIDI.
- Always check the handle value returned is greater than zero before attempting to play the sound.
- The handle can be used by most of the _SND sound playing functions and statements in QB64 except _SNDPLAYFILE which plays a sound file directly from the disk and does not use a handle value.
- Handles can be closed with _SNDCLOSE when the sound is no longer necessary.
- If a WAV sound file won't play, try it using the Windows Play WAV sounds library to check it or convert the sound file to OGG.
- The second parameter ("capabilities") is a string of parameters separated by commas, according to the table below. It is not case sensitive.
- Each capability can only be specified once and must be valid for that file or it won't play. Capabilities can be listed in any order.
QB64 versions prior to 1.000 support the following sound file formats (Bold is a guaranteed capability): WAV = "VOL,SYNC,LEN,PAUSE" Free WAV to OGG GUI converter OGG = "VOL,SYNC,LEN,PAUSE" Free WAV to OGG converter AIF = "VOL,SYNC,LEN,PAUSE" RIF = "VOL,SYNC,LEN,PAUSE" VOC = "VOL,SYNC,LEN,PAUSE" MID = "VOL" MOD = "VOL,PAUSE" MP3 = "VOL,PAUSE,SETPOS" Free WMA, MP3 and OGG converter Note: _SNDBAL only affects MP3 volume. Sound will reside in main channel.
- The required sound file capabilities can make a difference as to whether a sound file can be played or not and how it can be used.
- Only one sound can exist on the primary channel, and it must be closed before playing another non-SYNC sound.
Capability Descriptions "VOL" can change the volume or balance of the sound using _SNDVOL and _SNDBAL. "LEN" can get the length of the sound using the _SNDLEN function. "PAUSE" can pause the sound using _SNDPAUSE and the _SNDPAUSED function can check it. "SETPOS" can change the position the sound is (or will be) playing from. See _SNDSETPOS. "SYNC" can load the sound onto a unique channel, to be played simultaneously with others. When SYNC is not specified, the sound is loaded onto the primary channel.
- An Illegal Function Call error message means the capabilities$ string was invalid or two non-SYNC sounds are using the same channel.
Snippet 1: Loading a sound file to use in the program later. Only load it once and use the handle any time you want.
h& = _SNDOPEN("dog.wav") IF h& = 0 THEN BEEP ELSE _SNDPLAY h& 'check for valid handle before using!
Snippet 2: Playing a sound from 2 different speakers based on program results.
Laff& = _SNDOPEN("KONGlaff.ogg") 'load sound file and get LONG handle value IF LaffX! < -1 THEN LaffX! = -1 'set full volume to left speaker IF LaffX! > 1 THEN LaffX! = 1 'set full volume to right speaker _SNDBAL Laff&, LaffX! 'balance sound to left or right speaker _SNDPLAY Laff& 'play sound
Example: Playing a file and controlling playback:
s& = _SNDOPEN("song.ogg") PRINT "READY"; s& _SNDPLAY s& _SNDLOOP s& xleft = -1 xright = 1 DO k$ = INKEY$ SELECT CASE k$ CASE "f" xleft = xleft - 0.1 _SNDBAL s&, xleft, , , 1 CASE "g" xleft = xleft + 0.1 _SNDBAL s&, xleft, , , 1 CASE "h" xright = xright - 0.1 _SNDBAL s&, xright, , , 2 CASE "j" xright = xright + 0.1 _SNDBAL s&, xright, , , 2 CASE "n" volume = volume - 0.1 _SNDVOL s&, volume CASE "m" volume = volume + 0.1 _SNDVOL s&, volume CASE "p" _SNDPAUSE s& CASE " " _SNDPLAY s& CASE "i" PRINT _SNDPLAYING(s&) PRINT _SNDPAUSED(s&) SLEEP CASE "b" _SNDSETPOS s&, 110 CASE "l" _SNDLIMIT s&, 10 PRINT "LIM" SLEEP CASE "k" _SNDSTOP s& CASE "c" _SNDCLOSE s& SLEEP s2& = _SNDOPEN("song.ogg") CASE "d" s2& = _SNDCOPY(s&) _SNDPLAY s2& END SELECT LOCATE 1, 1 PRINT xleft, xright, volume, _SNDGETPOS(s&); " " LOOP
- _SNDCLOSE, _SNDPLAY, _SNDSTOP
- _SNDPAUSE, _SNDLOOP, _SNDLIMIT
- _SNDSETPOS, _SNDGETPOS
- _SNDPLAYING, _SNDPAUSED
- _SNDCOPY, _SNDPLAYCOPY
- _SNDBAL, _SNDLEN, _SNDVOL
- _SNDPLAYFILE (plays a named sound file directly and closes)
- _SNDRAW, _SNDRATE, _SNDRAWLEN (raw sounds without files)