QB64 Audio Prototype 1.0 _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ / \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \ \_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/ Facts: -Plays .wav, .

mp3, .mid and some other formats -Can play a sound using only one command -Can play sounds simultaneously -Can track, pause, loop, volume change, time limit and 3D position sounds -Uses handles to identify loaded sounds -Has strict specifications of what should happen in any given situation (eg. what happens if you try to pause an already paused sound) -Doesn't create QB-type errors unless called/used incorrectly -Checks for required functional capabilities when a file is opened so all error checking can be performed at this point -Ignores handles of value 0, so even if opening failed on a particular computer and this wasn't checked the program simply continues with no sound _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ / \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \ \_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/ Limitations: QB64 Audio uses third-party libraries which imposes some limitations. These third-party libraries may change in the future. For this reason when opening a sound the required capabilities MUST be specified. To make it possible for a QB64 program using QB64 Audio to be compatible with all future changes a list of minimum capabilities which can be relied upon for certain formats has been created for 3 file types: WAVE "SYNC,VOL,LEN" MP3 "VOL" MIDI "VOL" However, the current library actually supports the following: WAVE,OGG,AIFF,RIFF,VOC "SYNC,VOL,LEN,PAUSE" MP3 "VOL,PAUSE,SETPOS" MOD "VOL,PAUSE" MIDI "VOL" _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ / \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \ \_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/ Sub/Function Overview: _SNDPLAYFILE s) _SNDOPEN _SNDCLOSE playing) _SNDPLAY _SNDSTOP _SNDPLAYING _SNDLOOP _SNDLIMIT t number of seconds _SNDGETPOS Simple command to play a sound file (with limited option Returns a handle to a sound file Unloads a sound file (waits until after it has finished Plays a sound Stops a playing (or paused) sound Returns whether a sound is being played Like _SNDPLAY but sound is looped Stops playing a sound after it has been playing for a se Returns to current playing position in seconds

(Subs/Functions requiring the "SYNC" capability) _SNDCOPY Copies a sound (so two or more of the same sound can be played at once) _SNDPLAYCOPY Copies a sound, plays it and automatically closes the co py

the sound is loaded onto the primary channel.[sync%]. *The sound is closed automatically after it finishes playing Example: _SNDPLAYFILE "dog. and it must be closed before another non-SYNC sound can be opened. Capabilities include: SYNC. *The value returned by _SNDOPEN is a handle to the sound or 0.wav".[volume!]) *If sync% is 0 or not used. *The SYNC capability loads the sound onto a unique channel.1 FUNCTION _SNDOPEN& (filename$. *If you receive an ILLEGAL FUNCTION CALL error message."sync. 0 means the sound couldn't be loaded. all sounds are automatically freed *Closing a looping/paused/etc.(Subs/Functions requiring the "PAUSE" capability) _SNDPAUSE Pauses a sound _SNDPAUSED Checks if a sound is paused (Subs/Functions requiring the "LEN" capability) _SNDLEN Returns the length of a sound in seconds (Subs/Functions requiring the "VOL" capability) _SNDVOL Sets the volume of a sound _SNDBAL Sets the balance/3D position of a sound (Subs/Functions requiring the "SETPOS" capability) _SNDSETPOS Changes the current/starting playing position of a sound in seconds _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ / \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \/ \ \_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/\_/ Sub/Function Details: SUB _SNDPLAYFILE (filename$. *Changing the usage of sync% and volume! can make a difference to whether a sound can be played or not. Only one sound can exist on the primary channel. The order in which they are specified is unimportant. the most likely cause is the capabilities$ string was invalid.vol") SUB _SNDCLOSE (handle&) *Frees/unloads an open sound. Handles can be closed with _SNDCLOSE. so playing multiple copies of this sound at the same time won't be possible. If not used. PAUSE. *If the sound is still playing. *_SNDPLAYFILE never creates an error. Each capability can only be specified once and must be valid. the sound will be played at full volume. If SYNC is not specified. It is case insensitive.wav". If the sound cannot be played it takes no further action. (see the _SNDOPEN function for more information about the way QB64 manages channels) *volume! is a value from 0(silence) to 1(full volume). Example: h&=_SNDOPEN("dog. the sound will be played on the main channel. *When your program QB64 terminates. sound will mean it is never freed until . LEN.[capabilities$]) *capabilities$ is a string of words separated by commas. VOL and SETPOS The required capabilities can make a difference to whether a sound file can be opened or not. so it can be played simultaneously with other sounds. it will be freed after it finishes automatically.

Example: PRINT _SNDGETPOS(h&) FUNCTION _SNDCOPY& (handle&) *Returns a new handle to the same sound data referred to by the source handle.. *If a sound is paused. Copies/duplicates the source handle (see _SNDCOPY) 2. h2&=_SNDCOPY(h&):_SNDVOL h2&. Closes the copy *Makes coding easier Example: _SNDPLAYCOPY h&. the value returned continues to increment and does not restart at 0 when the sound loops. looping it.5. Example: _SNDLIMIT h&. it returns 0. Plays the copy 4.0. Example: PRINT _SNDPLAYING(h&) SUB _SNDLOOP (handle&) *Plays the sound. *For a looping sound. Example: _SNDCLOSE h& SUB _SNDPLAY (handle&) Example: _SNDPLAY h& SUB _SNDSTOP (handle&) Example: _SNDSTOP h& FUNCTION _SNDPLAYING% (handle&) *Returns 0 if a sound is not playing or -1 if it is.. h2&=_SNDCOPY(h&) SUB _SNDPLAYCOPY (handle&.5:_SNDPLAY h2&:_SNDCLOSE h2& SUB _SNDPAUSE (handle&) . *If a sound isn't playing. *If a sound is paused. *No changes to the source handle (such as a volume change) are inherited.limit!) *Sets how long a sound will be played for in seconds. Changes the volume of the copy if volume! passed (must have VOL capability) 3. it returns the paused position. *Cannot be set for playing looping sound. _SNDPLAYING will return 0. *The sound data referred to by the handle and its copies is not freed until all of them are closed. *SETPOS cannot be called while a looping sound is being played. *Set limit to 0 to remove the limit.5 FUNCTION _SNDGETPOS! (handle&) *Returns the currently playing position in seconds.0.[volume!]) *Performs the following actions: 1.the QB64 program terminates.5 'effectively. *Non-SYNC sounds must be closed before another Non-SYNC sound can be opened. Example: _SNDLOOP h& SUB _SNDLIMIT (handle&.

position!) *changes the current/starting playing position of a sound in seconds *if position! is past the length of the sound the sound will stop playing Example: _SNDSETPOS h&.[x!].*Must be playing or will not do anything *Continue playing by calling _SNDPLAY *Calling _SNDPAUSE again will not continue playing! Example: _SNDPAUSE h& FUNCTION _SNDPAUSED% (handle&) *Returns -1 if the sound is paused Example: PRINT _SNDPAUSED(h&) FUNCTION _SNDLEN! (handle&) *Returns the length of a sound in seconds Example: PRINT _SNDLEN(h&) SUB _SNDVOL (handle&. *Sounds further than a distance of 1000 cannot be heard. *x values go from left(negative) to right(positive).5 SUB _SNDBAL (handle&. or as close to it as the underlying software libraries allow. *y values go from below(negative) to above(positive).5 . *The volume decreases linearly (at a constant gradient) over distance. In some cases.[z!]) *Attempts to position a sound in 3D space.volume!) *Volume is a value form 0(silence) to 1(full volume) Example: _SNDVOL h&.5. *z values go from behind(negative) to in front(positive). this will be true 3D positioning. y or z values are set to 0.[y!].-1 'sound coming from the left SUB _SNDSETPOS (handle&. *Omitted x.0. in others. *By setting the x value to -1 or 1 it plays the sound at full volume from the appropriate speaker. *Sounds at a distance of 1 or less are played at full volume. a mere volume adjustment based on distance alone. Example: _SNDBAL h&.

Sign up to vote on this title
UsefulNot useful