SNDOPEN: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
No edit summary
(Add _MEMSOUND related info)
 
(24 intermediate revisions by 2 users not shown)
Line 9: Line 9:
{{PageDescription}}
{{PageDescription}}
* Returns a [[LONG]] {{Parameter|soundHandle&}} value to the sound file in memory. '''A value of zero means the sound could not be loaded.'''
* Returns a [[LONG]] {{Parameter|soundHandle&}} value to the sound file in memory. '''A value of zero means the sound could not be loaded.'''
* The literal or variable [[STRING]] sound {{Parameter|fileName$}} can be '''WAV, FLAC, OGG, MP3, MID, IT, XM, S3M, MOD, RAD (v2 only), AHX & HVL''' file types.
* The literal or variable [[STRING]] sound {{Parameter|fileName$}} can be '''WAV, AIFF, AIFC, FLAC, OGG, MP3, IT, XM, S3M, MOD, RAD, AHX, HVL, MUS, HMI, HMP, HMQ, KAR, LDS, MDS, MIDS, RCP, R36, G18, G36, RMI, MID, MIDI, XFM, XMI & QOA''' file types.
** '''MID''' support is enabled via the [[$MIDISOUNDFONT]] metacommand.
* The literal or variable [[STRING]] {{Parameter|capabilities$}} is optional but can be one of the following. Anything else is ignored. Multiple capability strings can be specified separated by a comma.
* The literal or variable [[STRING]] {{Parameter|capabilities$}} is optional but can be one of the following. Anything else is ignored. Multiple capability strings can be specified separated by a comma.
**'''STREAM''': This will "stream" the sound into memory rather than fully decoding it.
**'''NODECODE''' (NoDecode): This loads the sound into memory without decompressing it. Decompression is performed in small blocks at the final mixing stage.
**'''STREAM''': This will stream the sound into memory in small blocks instead of loading it entirely. Using '''NODECODE''' with '''STREAM''' will postpone the block's decoding until the final mixing phase.
**'''NOASYNC''' (NoAsync): This option will block the caller until the entire sound (or a portion, if '''STREAM''' is utilized) is loaded and prepared in memory.
**'''MEMORY''': This will treat {{Parameter|fileName$}} as a memory buffer containing the sound file instead of a file name.
**'''MEMORY''': This will treat {{Parameter|fileName$}} as a memory buffer containing the sound file instead of a file name.
* Short sounds should not be loaded using '''STREAM'''. Use '''STREAM''' when you want to play long sounds as background music and want to avoid loading delays.
* Short sounds should not be loaded using '''STREAM'''. Use '''STREAM''' when you want to play long sounds as background music.
* [[_MEMSOUND]] will not work for sounds loaded using '''STREAM''' or '''MEMORY'''.
* '''Always check the handle value returned is greater than zero before attempting to play the sound.'''
* '''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.
* 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.  
* 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 FLAC, OGG or MP3.
* 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 FLAC, OGG or MP3.
* MIDI files can be played using a built-in 108 channel OPL3 FM emulation, which is ideal for retro-style music playback. Additionally, MIDI files can also be played using other FM Banks and SoundFonts. For more information, refer to [[_MIDISOUNDBANK]].
* [[_MEMSOUND]] does not work for sounds loaded with '''_SNDOPEN''' when using the '''STREAM''' or '''NODECODE''' flags.




{{PageAvailability}}
{{PageAvailability}}
<!-- QB64 = a version or none, QBPE = a version or all, Platforms = yes or no -->
<gallery widths="48px" heights="48px" mode="nolines">
<gallery widths="48px" heights="48px" mode="nolines">
File:Qb64.png|'''v0.61'''
File:Qb64.png|'''v0.610'''
File:Qbpe.png|'''all'''
File:Qbpe.png|'''all'''
File:Apix.png
File:Apix.png
Line 31: Line 34:
File:Osx.png|'''yes'''
File:Osx.png|'''yes'''
</gallery>
</gallery>
 
<!-- additional availability notes go below here -->
* Available for ''Linux'' since '''QB64 v0.8''' and for ''macOS'' since '''QB64 v0.9'''
* Available for ''Linux'' since '''QB64 v0.800''' and for ''macOS'' since '''QB64 v0.900'''
* Until '''QB64 v0.954''' the formats WAV, OGG, AIFF, RIFF, VOC, MP3, MOD and MID were supported via SDL audio.
* Until '''QB64 v0.954''' various formats and capabilities are supported via the SDL audio backend.
* From '''QB64 v0.960''' until today and in the Phoenix Edition up to '''QB64-PE v3.0.0''' only WAV, OGG, and MP3 are supported via OpenAL.
** See the historic page [[_SNDOPEN-v0.954]] for reference.
:* Until here the capabilities VOL, LEN, SYNC, SETPOS and PAUSE were allowed in both Editions.
* In '''QB64 v0.960''' the underlying SDL library was exchanged by OpenGL (graphics) and OpenAL (sound) and as a result only the WAV, OGG, and MP3 formats are supported until today's current versions without any special capabilities.
:* These old capabilities are alltogether '''{{Text|deprecated now in the Phoenix Edition only|red}}''' and will be ignored here.
** See historic page [[_SNDOPEN-v0.960]] for reference.
* Since '''QB64-PE v3.1.0''' the FLAC, MOD, S3M, XM, IT and RAD formats were added in the move from OpenAL to Miniaudio. Also the new capability to ''stream'' the sound was added.
** This limitation also applies up to '''QB64-PE v3.0.0''' of the Phoenix Edition.
* With '''QB64-PE v.3.2.0''' the MID format was added again when enabled via the [[$MIDISOUNDFONT]] metacommand.
* Since '''QB64-PE v3.1.0''' the new formats FLAC, MOD, S3M, XM, IT and RAD were added to that very limited list, in the move away from OpenAL to the Miniaudio library in combination with separate and extensible player libraries.
* In '''QB64-PE v.3.5.0''' the Amiga AHX and HVL formats were added, and also the capability to load from ''memory''.
** In this version also the new capability to STREAM the sound was added.
* With '''QB64-PE v3.2.0''' the MID format was added, but needs explicitly to be enabled via the [[$MIDISOUNDFONT]] metacommand.
* In '''QB64-PE v3.5.0''' the Amiga AHX and HVL formats were added to the list.
** In this version also the new capability to load sounds from MEMORY was added.
* In '''QB64-PE v3.8.0''' support for Apple's AIFF and AIFC formats was added.
* In '''QB64-PE v3.9.0''' support for Quite OK Audio (QOA) format was added.
* In '''QB64-PE v3.9.0''' the old OpenAL audio backend was finally removed.
* In '''QB64-PE v3.14.0''' support for unrestricted MUS, HMI, HMP, HMQ, KAR, LDS, MDS, MIDS, RCP, R36, G18, G36, RMI, MID, MIDI, XFM, and XMI was added.
** In this version also the NODECODE and NOASYNC capabilities were added.
** The previous requirement to use [[$UNSTABLE]]:'''MIDI''' and [[$MIDISOUNDFONT]] has been removed.




{{PageExamples}}
{{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.
;Example 1:Loading a sound file to use in the program later. Only load it once and use the handle any time you want.
{{CodeStart}}
{{CodeStart}}
h& = {{Cl|_SNDOPEN}}("dog.wav")
h& = {{Cl|_SNDOPEN}}("dog.wav")
Line 49: Line 61:
{{CodeEnd}}
{{CodeEnd}}


----


''Snippet 2:'' Playing a sound from 2 different speakers based on program results.
;Example 2:Playing a sound from 2 different speakers based on program results.
{{CodeStart}}
{{CodeStart}}
' This examples load, plays and then bounces the sound between the left and right channels
' This examples load, plays and then bounces the sound between the left and right channels
Line 75: Line 88:
{{CodeEnd}}
{{CodeEnd}}


----


''Snippet 3:'' Loading a sound file from memory and then playing it.
;Example 3:Loading a sound file from memory and then playing it.
{{CodeStart}}
{{CodeStart}}
{{Cl|OPTION _EXPLICIT}}
{{Cl|OPTION _EXPLICIT}}
Line 158: Line 172:
* [[_SNDCOPY]], [[_SNDPLAYCOPY]]
* [[_SNDCOPY]], [[_SNDPLAYCOPY]]
* [[_SNDBAL]], [[_SNDLEN]], [[_SNDVOL]]
* [[_SNDBAL]], [[_SNDLEN]], [[_SNDVOL]]
* [[_SNDPLAYFILE]] {{text|(plays a named sound file directly and closes)}}
* [[_SNDPLAYFILE]]
* [[_SNDRAW]], [[_SNDRATE]], [[_SNDRAWLEN]] {{text|(raw sounds without files)}}
* [[_SNDRAW]], [[_SNDRATE]], [[_SNDRAWLEN]]
* [[_MEMSOUND]]




{{PageNavigation}}
{{PageNavigation}}

Latest revision as of 04:31, 21 November 2024

The _SNDOPEN function loads a sound file into memory and returns a LONG handle value above 0.


Syntax

soundHandle& = _SNDOPEN(fileName$[, capabilities$])


Description

  • Returns a LONG soundHandle& value to the sound file in memory. A value of zero means the sound could not be loaded.
  • The literal or variable STRING sound fileName$ can be WAV, AIFF, AIFC, FLAC, OGG, MP3, IT, XM, S3M, MOD, RAD, AHX, HVL, MUS, HMI, HMP, HMQ, KAR, LDS, MDS, MIDS, RCP, R36, G18, G36, RMI, MID, MIDI, XFM, XMI & QOA file types.
  • The literal or variable STRING capabilities$ is optional but can be one of the following. Anything else is ignored. Multiple capability strings can be specified separated by a comma.
    • NODECODE (NoDecode): This loads the sound into memory without decompressing it. Decompression is performed in small blocks at the final mixing stage.
    • STREAM: This will stream the sound into memory in small blocks instead of loading it entirely. Using NODECODE with STREAM will postpone the block's decoding until the final mixing phase.
    • NOASYNC (NoAsync): This option will block the caller until the entire sound (or a portion, if STREAM is utilized) is loaded and prepared in memory.
    • MEMORY: This will treat fileName$ as a memory buffer containing the sound file instead of a file name.
  • Short sounds should not be loaded using STREAM. Use STREAM when you want to play long sounds as background music.
  • 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 FLAC, OGG or MP3.
  • MIDI files can be played using a built-in 108 channel OPL3 FM emulation, which is ideal for retro-style music playback. Additionally, MIDI files can also be played using other FM Banks and SoundFonts. For more information, refer to _MIDISOUNDBANK.
  • _MEMSOUND does not work for sounds loaded with _SNDOPEN when using the STREAM or NODECODE flags.


Availability

  • v0.610

    v0.610

  • all

    all

  • Apix.png
  • yes

    yes

  • yes

    yes

  • yes

    yes

  • Available for Linux since QB64 v0.800 and for macOS since QB64 v0.900
  • Until QB64 v0.954 various formats and capabilities are supported via the SDL audio backend.
  • In QB64 v0.960 the underlying SDL library was exchanged by OpenGL (graphics) and OpenAL (sound) and as a result only the WAV, OGG, and MP3 formats are supported until today's current versions without any special capabilities.
    • See historic page _SNDOPEN-v0.960 for reference.
    • This limitation also applies up to QB64-PE v3.0.0 of the Phoenix Edition.
  • Since QB64-PE v3.1.0 the new formats FLAC, MOD, S3M, XM, IT and RAD were added to that very limited list, in the move away from OpenAL to the Miniaudio library in combination with separate and extensible player libraries.
    • In this version also the new capability to STREAM the sound was added.
  • With QB64-PE v3.2.0 the MID format was added, but needs explicitly to be enabled via the $MIDISOUNDFONT metacommand.
  • In QB64-PE v3.5.0 the Amiga AHX and HVL formats were added to the list.
    • In this version also the new capability to load sounds from MEMORY was added.
  • In QB64-PE v3.8.0 support for Apple's AIFF and AIFC formats was added.
  • In QB64-PE v3.9.0 support for Quite OK Audio (QOA) format was added.
  • In QB64-PE v3.9.0 the old OpenAL audio backend was finally removed.
  • In QB64-PE v3.14.0 support for unrestricted MUS, HMI, HMP, HMQ, KAR, LDS, MDS, MIDS, RCP, R36, G18, G36, RMI, MID, MIDI, XFM, and XMI was added.
    • In this version also the NODECODE and NOASYNC capabilities were added.
    • The previous requirement to use $UNSTABLE:MIDI and $MIDISOUNDFONT has been removed.


Examples

Example 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!
Example 2
Playing a sound from 2 different speakers based on program results.
' This examples load, plays and then bounces the sound between the left and right channels
Laff& = _SNDOPEN("KONGlaff.ogg", "stream") 'load sound file and get LONG handle value
IF Laff& > 0 THEN
    _SNDPLAY Laff& 'play sound
ELSE
    PRINT "Failed to load sound file."
    END
END IF

PRINT "Press ESC to stop."
dir = 0.01
DO
    IF laffx! <= -1 THEN dir = 0.01
    IF laffx! >= 1 THEN dir = -0.01
    laffx! = laffx! + dir

    LOCATE , 1: PRINT USING "Balance = ##.##"; laffx!;
    _SNDBAL Laff&, laffx! 'balance sound to left or right speaker

    _LIMIT 60
LOOP WHILE _SNDPLAYING(Laff&) AND _KEYHIT <> 27
Example 3
Loading a sound file from memory and then playing it.
OPTION _EXPLICIT

DIM buffer AS STRING: buffer = LoadSlidingAwayData
PRINT "Size ="; LEN(buffer)

DIM h AS LONG: h = _SNDOPEN(buffer, "memory")
PRINT "Handle ="; h
PRINT "Length ="; _SNDLEN(h)

PRINT "Looping audio..."
_SNDLOOP h

END

' This function reads the file directly from data and then returns the decompressed data
FUNCTION LoadSlidingAwayData$
    DIM AS LONG numL, numb, stroffs, i, dat
    DIM rawdata AS STRING

    RESTORE Sliding_Away
    READ numL, numb
    rawdata = SPACE$((numL * 4) + numb)
    stroffs = 1

    FOR i = 1 TO numL
        READ dat
        MID$(rawdata, stroffs, 4) = MKL$(dat)
        stroffs = stroffs + 4
    NEXT

    IF numb > 0 THEN
        FOR i = 1 TO numb
            READ dat
            MID$(rawdata, stroffs, 1) = CHR$(dat)
            stroffs = stroffs + 1
        NEXT
    END IF

    LoadSlidingAwayData = _INFLATE$(rawdata)

    '--- DATAs representing the contents of file sliding_away.hvl
    '---------------------------------------------------------------------
    Sliding_Away:
    DATA 192,10
    DATA &H56A59C78,&H51134F5B,&H7766FE10,&HE96D0B6B,&HC5258202,&H5BAED8BA,&H840A956B,&HFBB240F8
    DATA &H3E2483E0,&H4B3E24A0,&H018928C4,&H6217892F,&H9F813FA2,&H47E14FC0,&H3D1356F1,&HED9D9EB7
    DATA &H9A78DA05,&HFB3399CE,&HCCE677CD,&HB3CE6ECC,&H7451CF57,&HDF05877E,&H02F0F2DF,&H0F297204
    DATA &HA39E8435,&HF47BD182,&H9ED67297,&H95727A62,&HC2AD1C62,&HF6E174BD,&HFC52E2CC,&HCDF31E7B
    DATA &H8C1BFE31,&H0530CF3F,&HFC639FC6,&H767F8C33,&H3E117F0C,&H12FE196E,&HFC3551E6,&HC5602C65
    DATA &H88B0E660,&H622FE19A,&HBF86AB19,&H6DB89B82,&H42588BF8,&HFF9CEADD,&HFE69F88E,&HFE8E0AA2
    DATA &HB4151E28,&HB77813DB,&HC0F00F98,&HB1D0D7E2,&H6878BBF8,&HB23C0DF1,&H2DD626F8,&HE2D7443E
    DATA &HC5B1E1EF,&HF8B0D847,&H35213616,&H7DC6DF37,&HBF4CA16C,&H51D38F90,&H988C1126,&H6396662B
    DATA &H92BEE941,&H82D4AECA,&HAE19975A,&H84D3803F,&H78C59C84,&H2FDA3819,&H91FEB274,&HBD99B759
    DATA &H696D74A3,&H9EC47B19,&HD31127F3,&H7BFBB907,&H55F2AF36,&H07F1906A,&H48D709CE,&H28535583
    DATA &H14E43B7B,&H26A6E166,&HC5B6BE73,&H9987436B,&H4B9F9E0D,&H711ECA4F,&H1F8A569A,&H4C4C7F8E
    DATA &HD687B61D,&H169A5E4D,&H2C214CDF,&H606A9A4F,&H39E3E02F,&H19D3C0E2,&HBB2BA06B,&H44260BBA
    DATA &H36837A77,&HD7E5755B,&H8B6D5EB2,&HE2BD64E8,&H5DAFD7B6,&H511EC46B,&H28D99976,&HB2229E54
    DATA &H119E361B,&H7F0D34A1,&H3F556E80,&H54E38DA8,&HB2C43EA2,&H4A6A18AA,&H6D68D8AE,&HDD4B1A0F
    DATA &HB08FCF44,&H9F93723A,&H9BF305C9,&H0940B334,&H77655317,&HCFA7E047,&H1FABC0EE,&HB2C99E6B
    DATA &H6938C69D,&HD2B70456,&H3A4AA7FE,&H9A5571BE,&H72E75DE4,&HC6436D54,&H63C88D17,&H3B1E4C6B
    DATA &H7D6DAFC6,&H2D781D78,&H551D6B43,&H6D631693,&H0CA258D9,&HC2AD8353,&HDBED2EA1,&HE7D494D6
    DATA &HDB5D33AA,&HD774C635,&HB7B60E08,&HEA3C14D4,&HAE70F1F7,&H15274254,&H20DB7E57,&HDF3624DB
    DATA &HD967DE36,&H34FB694A,&H5CF3EAD5,&H3714A95D,&HDFB4B55D,&H8E1B15F5,&HD4C09FBB,&HB2E5593E
    DATA &HAE7965FB,&H1C50DEAF,&H4AADD413,&HCCF2D114,&H3C053CBE,&H2131FA2A,&HA86FB8EF,&H8B5EE49A
    DATA &H8E4EC59B,&H4A212712,&HE24DEF20,&H5CD1131F,&H8F7D3BC9,&HBACE8D52,&H48140715,&HF214BADF
    DATA &H2F5717E5,&HF0A5E631,&H5148A8A5,&HF4DD4296,&HDD4AEDD4,&HA3C4BD17,&HB991EF24,&H2C4E0200
    DATA &HE1EE4B6F,&H5A527069,&H07B674FC,&HDA9EC13F,&H70AF9D0A,&HA12937B6,&H196D4427,&H8BD50886
    DATA &H3422259D,&HE5FA7FC8,&HD1E1D1C3,&HE0E0BBF1,&H7C0FC1DB,&HE4F9FB7F,&H760F5838,&H63EEEE5F
    DATA &HA3,&HDB,&HDD,&H16,&HF8,&H7F,&HEE,&H68,&H18,&HB9
END FUNCTION


See also


Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=SNDOPEN&oldid=9275"