mirror of
https://github.com/QB64Official/qb64.git
synced 2024-09-12 16:40:25 +00:00
149 lines
6.4 KiB
Text
149 lines
6.4 KiB
Text
{{DISPLAYTITLE:_SNDOPEN}}
|
|
The [[_SNDOPEN]] function loads a sound file into memory and returns a [[LONG]] handle value above 0.
|
|
|
|
|
|
{{PageSyntax}}
|
|
: {{Parameter|soundHandle&}} = [[_SNDOPEN]]({{Parameter|fileName$}})
|
|
|
|
===Syntax prior to build 20170811/60===
|
|
: {{Parameter|soundHandle&}} = [[_SNDOPEN]]({{Parameter|fileName$}}[, "[VOL][,][SYNC][,][LEN][,][PAUSE][,][SETPOS]"])
|
|
|
|
|
|
{{PageDescription}}
|
|
* Returns a [[LONG]] {{Parameter|soundHandle&}} value to the sound file in memory. '''A zero value means the sound could not be loaded.'''
|
|
* The literal or variable [[STRING]] sound {{Parameter|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 [[Windows_Libraries#Play_WAV_Sounds|Play WAV sounds library]] to check it or convert the sound file to OGG.
|
|
|
|
|
|
===Older versions===
|
|
* 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.
|
|
{{TextStart}} '''QB64 versions prior to 1.000''' support the following sound file formats ('''Bold is a guaranteed capability'''):
|
|
|
|
WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter]
|
|
OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php 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" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter]
|
|
|
|
''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel.
|
|
{{TextEnd}}
|
|
|
|
* 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.
|
|
<center>See [[_SNDCOPY]] and [[_SNDPLAYCOPY]]</center>
|
|
{{TextStart}} '''Capability Descriptions'''
|
|
|
|
"'''VOL'''" can change the volume or balance of the sound using {{Cb|_SNDVOL}} and {{Cb|_SNDBAL}}.
|
|
"'''LEN'''" can get the length of the sound using the {{Cb|_SNDLEN}} function.
|
|
"'''PAUSE'''" can pause the sound using {{Cb|_SNDPAUSE}} and the {{Cb|_SNDPAUSED}} function can check it.
|
|
"'''SETPOS'''" can change the position the sound is (or will be) playing from. See {{Cb|_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.'''
|
|
{{TextEnd}}
|
|
|
|
*An '''Illegal Function Call''' error message means the capabilities$ string was invalid or two non-'''SYNC''' sounds are using the same channel.
|
|
|
|
|
|
{{PageExamples}}
|
|
''Snippet 1:'' Loading a sound file to use in the program later. Only load it once and use the handle any time you want.
|
|
{{CodeStart}}
|
|
h& = {{Cl|_SNDOPEN}}("dog.wav")
|
|
IF h& = 0 THEN BEEP ELSE {{Cl|_SNDPLAY}} h& 'check for valid handle before using!
|
|
{{CodeEnd}}
|
|
|
|
|
|
''Snippet 2:'' Playing a sound from 2 different speakers based on program results.
|
|
{{CodeStart}} '' ''
|
|
Laff& = {{Cl|_SNDOPEN}}("KONGlaff.ogg") 'load sound file and get LONG handle value
|
|
{{Cl|IF}} LaffX! < -1 {{Cl|THEN}} LaffX! = -1 'set full volume to left speaker
|
|
{{Cl|IF}} LaffX! > 1 {{Cl|THEN}} LaffX! = 1 'set full volume to right speaker
|
|
|
|
{{Cl|_SNDBAL}} Laff&, LaffX! 'balance sound to left or right speaker
|
|
{{Cl|_SNDPLAY}} Laff& 'play sound '' ''
|
|
{{CodeEnd}}
|
|
|
|
|
|
''Example:'' Playing a file and controlling playback:
|
|
{{CodeStart}}
|
|
s& = {{Cl|_SNDOPEN}}("song.ogg")
|
|
{{Cl|PRINT}} "{{Cl|READ}}Y"; s&
|
|
{{Cl|_SNDPLAY}} s&
|
|
{{Cl|_SNDLOOP}} s&
|
|
|
|
|
|
xleft = -1
|
|
xright = 1
|
|
DO
|
|
k$ = {{Cl|INKEY$}}
|
|
{{Cl|SELECT CASE}} k$
|
|
{{Cl|CASE}} "f"
|
|
xleft = xleft - 0.1
|
|
{{Cl|_SNDBAL}} s&, xleft, , , 1
|
|
{{Cl|CASE}} "g"
|
|
xleft = xleft + 0.1
|
|
{{Cl|_SNDBAL}} s&, xleft, , , 1
|
|
{{Cl|CASE}} "h"
|
|
xright = xright - 0.1
|
|
{{Cl|_SNDBAL}} s&, xright, , , 2
|
|
{{Cl|CASE}} "j"
|
|
xright = xright + 0.1
|
|
{{Cl|_SNDBAL}} s&, xright, , , 2
|
|
{{Cl|CASE}} "n"
|
|
volume = volume - 0.1
|
|
{{Cl|_SNDVOL}} s&, volume
|
|
{{Cl|CASE}} "m"
|
|
volume = volume + 0.1
|
|
{{Cl|_SNDVOL}} s&, volume
|
|
{{Cl|CASE}} "p"
|
|
{{Cl|_SNDPAUSE}} s&
|
|
{{Cl|CASE}} " "
|
|
{{Cl|_SNDPLAY}} s&
|
|
{{Cl|CASE}} "i"
|
|
{{Cl|PRINT}} {{Cl|_SNDPLAYING}}(s&)
|
|
{{Cl|PRINT}} {{Cl|_SNDPAUSED}}(s&)
|
|
{{Cl|SLEEP}}
|
|
{{Cl|CASE}} "b"
|
|
{{Cl|_SNDSETPOS}} s&, 110
|
|
{{Cl|CASE}} "l"
|
|
{{Cl|_SNDLIMIT}} s&, 10
|
|
{{Cl|PRINT}} "LIM"
|
|
{{Cl|SLEEP}}
|
|
{{Cl|CASE}} "k"
|
|
{{Cl|_SNDSTOP}} s&
|
|
{{Cl|CASE}} "c"
|
|
{{Cl|_SNDCLOSE}} s&
|
|
{{Cl|SLEEP}}
|
|
s2& = {{Cl|_SNDOPEN}}("song.ogg")
|
|
{{Cl|CASE}} "d"
|
|
s2& = {{Cl|_SNDCOPY}}(s&)
|
|
{{Cl|_SNDPLAY}} s2&
|
|
{{Cl|END SELECT}}
|
|
{{Cl|LOCATE}} 1, 1
|
|
{{Cl|PRINT}} xleft, xright, volume, {{Cl|_SNDGETPOS}}(s&); " "
|
|
LOOP
|
|
{{CodeEnd}}{{small|Code by Johny B}}
|
|
|
|
|
|
|
|
{{PageSeeAlso}}
|
|
* [[_SNDCLOSE]], [[_SNDPLAY]], [[_SNDSTOP]]
|
|
* [[_SNDPAUSE]], [[_SNDLOOP]], [[_SNDLIMIT]]
|
|
* [[_SNDSETPOS]], [[_SNDGETPOS]]
|
|
* [[_SNDPLAYING]], [[_SNDPAUSED]]
|
|
* [[_SNDCOPY]], [[_SNDPLAYCOPY]]
|
|
* [[_SNDBAL]], [[_SNDLEN]], [[_SNDVOL]]
|
|
* [[_SNDPLAYFILE]] {{text|(plays a named sound file directly and closes)}}
|
|
* [[_SNDRAW]], [[_SNDRATE]], [[_SNDRAWLEN]] {{text|(raw sounds without files)}}
|
|
|
|
|
|
{{PageNavigation}}
|