SNDNEW: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(9 intermediate revisions by 2 users not shown)
Line 4: Line 4:


{{PageSyntax}}
{{PageSyntax}}
: {{Parameter|soundHandle&}} = [[_SNDNEW]]({{Parameter|frames&}}, {{Parameter|channels&}}, {{Parameter|bits&}})
: {{Parameter|soundHandle&}} = [[_SNDNEW]]({{Parameter|frames&}}[, {{Parameter|channels&}}][, {{Parameter|bits&}}][, {{Parameter|sampleRate&}}])




{{PageParameters}}
{{PageParameters}}
* {{Parameter|frames&}} is the number of sample frames needed. The number needed for a one second of sound is determined by your sound hardware's sample rate, hence you may use the following formula:
* {{Parameter|frames&}} is the number of sample frames needed. The number needed for one second of sound is determined by your sound hardware's sample rate, hence you may use the following formula:
** {{InlineCode}}frames& = {{Cl|_SNDRATE}} * neededSeconds!{{InlineCodeEnd}}, where you may also specify fractional seconds.
** {{InlineCode}}frames& = {{Cl|_SNDRATE}} * neededSeconds!{{InlineCodeEnd}} where you may also specify fractional seconds.
* {{Parameter|channels&}} is the number of channels needed (1 = mono, 2 = stereo).
* {{Parameter|channels&}} (optional) specifies the number of channels (1 = mono, 2 = stereo). Defaults to 1 (mono) if omitted.
* {{Parameter|bits&}} is the number of bits per channel (8 = 8-bit unsigned integer, 16 = 16-bit signed integer, 32 = 32-bit floating point).
* {{Parameter|bits&}} (optional) specifies the number of bits per sample (8 = 8-bit unsigned integer, 16 = 16-bit signed integer, 32 = 32-bit floating point). Defaults to 32-bit if omitted.
* {{Parameter|sampleRate&}} (optional) specifies the playback sample rate in Hz. Defaults to the system's default sample rate if omitted.




{{PageDescription}}
{{PageDescription}}
* Use this function to create a raw sound in memory.
* The '''_SNDNEW''' function creates an empty sound buffer in memory that can be filled with sample data.
* Once the sound is created, it can be accessed and manipulated using the [[_MEM]] interface statements and functions, mainly [[_MEMSOUND]], [[_MEMGET]] & [[_MEMPUT]].
* Once created, the sound buffer can be accessed and modified using the [[_MEM]] interface, particularly with [[_MEMSOUND]], [[_MEMGET]], and [[_MEMPUT]].
* Using this function can generate sounds once programmatically and play it multiple times.
* This function allows generating and storing sounds programmatically for repeated playback.
* The sound memory can also be filled with sample data from other sources like files, DATA statements and more.
* The sound memory can be populated with sample data from various sources, such as files, [[DATA]] statements, or procedural generation.
* Sound handle values and the memory used must be freed using [[_SNDCLOSE]] when no longer required.
* Sound memory pointers obtained with [[_MEMSOUND]] must be freed using [[_MEMFREE]], and the sound handle itself must be released with [[_SNDCLOSE]] when no longer needed.




{{PageAvailability}}
{{PageAvailability}}
* '''QBPE 3.5 and up''' (QB64 Phoenix Edition)
<!-- QB64 = a version or none, QBPE = a version or all, Platforms = yes or no -->
<gallery widths="48px" heights="48px" mode="nolines">
File:Qb64.png|'''none'''
File:Qbpe.png|'''v3.5.0'''
File:Apix.png
File:Win.png|'''yes'''
File:Lnx.png|'''yes'''
File:Osx.png|'''yes'''
</gallery>
<!-- additional availability notes go below here -->
* Sample rate support was added in '''QB64-PE v4.2.0'''.




Line 29: Line 40:
;Example 1:Creating a sound at runtime and playing it.
;Example 1:Creating a sound at runtime and playing it.
{{CodeStart}}
{{CodeStart}}
{{Cl|$CONSOLE}}
{{Cl|_DEFINE}} A-Z {{Cl|AS}} {{Cl|LONG}}
{{Cl|OPTION _EXPLICIT}}
{{Cl|OPTION}} {{Cl|_EXPLICIT}}


{{Cl|RANDOMIZE}} {{Cl|TIMER}}
{{Cl|RANDOMIZE}} {{Cl|TIMER (function)|TIMER}}


{{Cl|CONST}} SOUND_DURATION = 5 ' duration is seconds
{{Cl|CONST}} SOUND_DURATION = {{Text|5|#F580B1}} {{Text|<nowiki>' duration in seconds</nowiki>|#919191}}
{{Cl|CONST}} SAMPLE_CHANNELS = 1 ' number of channes. For stereo we need to add another _MEMPUT below and +offset by SAMPLE_BYTES
{{Cl|CONST}} SAMPLE_CHANNELS = {{Text|1|#F580B1}} {{Text|<nowiki>' number of channes. For stereo, we need to add another _MEMPUT below and +offset by SAMPLE_BYTES</nowiki>|#919191}}
{{Cl|CONST}} SAMPLE_BYTES = 4 ' number of bytes / sample (not frame!)
{{Cl|CONST}} SAMPLE_BYTES = _SIZE_OF_SINGLE {{Text|<nowiki>' number of bytes/sample (not frame!)</nowiki>|#919191}}


{{Cl|DIM}} h {{Cl|AS}} {{Cl|LONG}}: h = {{Cl|_SNDNEW}}(SOUND_DURATION * {{Cl|_SNDRATE}}, SAMPLE_CHANNELS, SAMPLE_BYTES * 8)
{{Cl|DIM}} h {{Cl|AS}} {{Cl|LONG}}: h = {{Cl|_SNDNEW}}(SOUND_DURATION * {{Cl|_SNDRATE}}, SAMPLE_CHANNELS, SAMPLE_BYTES * {{Text|8|#F580B1}})
{{Cl|IF}} (h < 1) {{Cl|THEN}}
{{Cl|IF}} (h &lt; {{Text|1|#F580B1}}) {{Cl|THEN}}
     {{Cl|PRINT}} "Failed to create sound!"
     {{Cl|PRINT}} {{Text|<nowiki>"Failed to create sound!"</nowiki>|#FFB100}}
     {{Cl|END}}
     {{Cl|END}}
{{Cl|END IF}}
{{Cl|END IF}}


{{Cl|DIM}} sndblk {{Cl|AS}} {{Cl|_MEM}}: sndblk = {{Cl|_MEMSOUND}}(h, 0)
{{Cl|DIM}} sndblk {{Cl|AS}} {{Cl|_MEM}}: sndblk = {{Cl|_MEMSOUND}}(h, {{Text|0|#F580B1}})
{{Cl|IF}} sndblk.SIZE = 0 {{Cl|THEN}}
{{Cl|IF}} sndblk.SIZE = {{Text|0|#F580B1}} {{Cl|THEN}}
     {{Cl|_SNDCLOSE}} h
     {{Cl|_SNDCLOSE}} h
     {{Cl|PRINT}} "Failed to access sound data!"
     {{Cl|PRINT}} {{Text|<nowiki>"Failed to access sound data!"</nowiki>|#FFB100}}
     {{Cl|END}}
     {{Cl|END}}
{{Cl|END IF}}
{{Cl|END IF}}


{{Cl|DIM}} t {{Cl|AS}} {{Cl|_INTEGER64}}
{{Cl|DIM}} t {{Cl|AS}} {{Cl|_INTEGER64}}
{{Cl|FOR}} t = 0 {{Cl|TO}} (SOUND_DURATION * {{Cl|_SNDRATE}}) - 1
{{Cl|FOR}} t = {{Text|0|#F580B1}} {{Cl|TO}} (SOUND_DURATION * {{Cl|_SNDRATE}}) - {{Text|1|#F580B1}}
     {{Cl|_MEMPUT}} sndblk, sndblk.OFFSET + (t * SAMPLE_BYTES * SAMPLE_CHANNELS), {{Cl|SIN}}(2 * {{Cl|_PI}} * 440 * t / {{Cl|_SNDRATE}}) + {{Cl|RND}} - {{Cl|RND}} {{Cl|AS}} {{Cl|SINGLE}} ' mixes noise and a sine wave
     {{Cl|_MEMPUT}} sndblk, sndblk.OFFSET + (t * SAMPLE_BYTES * SAMPLE_CHANNELS), ({{Cl|SIN}}({{Cl|_PI}}({{Text|880!|#F580B1}} * t) / {{Cl|_SNDRATE}}) + ({{Cl|RND}} - {{Cl|RND}})) / {{Text|2!|#F580B1}} {{Cl|AS}} {{Cl|SINGLE}} {{Text|<nowiki>' mixes noise and a sine wave at half volume</nowiki>|#919191}}
{{Cl|NEXT}}
{{Cl|NEXT}}


Line 61: Line 72:


{{Cl|_SNDCLOSE}} h
{{Cl|_SNDCLOSE}} h
{{Cl|END}}
{{CodeEnd}}
----
;Example 2:Creating sounds with different sample rates.
{{CodeStart}}
{{Cl|_DEFINE}} A-Z {{Cl|AS}} {{Cl|LONG}}
{{Cl|OPTION}} {{Cl|_EXPLICIT}}
{{Cl|RANDOMIZE}} {{Cl|TIMER (function)|TIMER}}
{{Cl|CONST}} SOUND_DURATION = {{Text|3|#F580B1}} {{Text|<nowiki>' duration in seconds</nowiki>|#919191}}
{{Cl|CONST}} SAMPLE_CHANNELS = {{Text|1|#F580B1}} {{Text|<nowiki>' mono</nowiki>|#919191}}
{{Cl|CONST}} SAMPLE_BYTES = _SIZE_OF_SINGLE {{Text|<nowiki>' 32-bit floating point (4 bytes per sample)</nowiki>|#919191}}
{{Cl|DIM}} h1 {{Cl|AS}} {{Cl|LONG}}, h2 {{Cl|AS}} {{Cl|LONG}}
h1 = {{Cl|_SNDNEW}}(SOUND_DURATION * {{Cl|_SNDRATE}}, SAMPLE_CHANNELS, SAMPLE_BYTES * {{Text|8|#F580B1}}, {{Cl|_SNDRATE}} \ {{Text|2|#F580B1}})
h2 = {{Cl|_SNDNEW}}(SOUND_DURATION * {{Cl|_SNDRATE}}, SAMPLE_CHANNELS, SAMPLE_BYTES * {{Text|8|#F580B1}}, {{Cl|_SNDRATE}})
{{Cl|IF}} (h1 &lt; {{Text|1|#F580B1}}) {{Cl|_ORELSE}} (h2 &lt; {{Text|1|#F580B1}}) {{Cl|THEN}}
    {{Cl|PRINT}} {{Text|<nowiki>"Failed to create sound!"</nowiki>|#FFB100}}
    {{Cl|END}}
{{Cl|END IF}}
{{Cl|DIM}} sndblk1 {{Cl|AS}} {{Cl|_MEM}}, sndblk2 {{Cl|AS}} {{Cl|_MEM}}
sndblk1 = {{Cl|_MEMSOUND}}(h1, {{Text|0|#F580B1}})
sndblk2 = {{Cl|_MEMSOUND}}(h2, {{Text|0|#F580B1}})
{{Cl|IF}} (sndblk1.SIZE = {{Text|0|#F580B1}}) {{Cl|_ORELSE}} (sndblk2.SIZE = {{Text|0|#F580B1}}) {{Cl|THEN}}
    {{Cl|PRINT}} {{Text|<nowiki>"Failed to access sound data!"</nowiki>|#FFB100}}
    {{Cl|_SNDCLOSE}} h1
    {{Cl|_SNDCLOSE}} h2
    {{Cl|END}}
{{Cl|END IF}}
{{Cl|DIM}} t {{Cl|AS}} {{Cl|_INTEGER64}}
{{Cl|FOR}} t = {{Text|0|#F580B1}} {{Cl|TO}} (SOUND_DURATION * {{Cl|_SNDRATE}}) - {{Text|1|#F580B1}}
    {{Cl|_MEMPUT}} sndblk1, sndblk1.OFFSET + (t * SAMPLE_BYTES), {{Cl|SIN}}({{Cl|_PI}}({{Text|880!|#F580B1}} * t) / {{Cl|_SNDRATE}}) {{Cl|AS}} {{Cl|SINGLE}}
{{Cl|NEXT}}
{{Cl|FOR}} t = {{Text|0|#F580B1}} {{Cl|TO}} (SOUND_DURATION * {{Cl|_SNDRATE}}) - {{Text|1|#F580B1}}
    {{Cl|_MEMPUT}} sndblk2, sndblk2.OFFSET + (t * SAMPLE_BYTES), {{Cl|SIN}}({{Cl|_PI}}({{Text|880!|#F580B1}} * t) / {{Cl|_SNDRATE}}) {{Cl|AS}} {{Cl|SINGLE}}
{{Cl|NEXT}}
{{Cl|PRINT}} {{Text|<nowiki>"Playing sound at"</nowiki>|#FFB100}}; {{Cl|_SNDRATE}} \ {{Text|2|#F580B1}}; {{Text|<nowiki>"Hz..."</nowiki>|#FFB100}}
{{Cl|_SNDPLAY}} h1
{{Cl|SLEEP}} SOUND_DURATION * {{Text|2|#F580B1}}
{{Cl|PRINT}} {{Text|<nowiki>"Playing sound at"</nowiki>|#FFB100}}; {{Cl|_SNDRATE}}; {{Text|<nowiki>"Hz..."</nowiki>|#FFB100}}
{{Cl|_SNDPLAY}} h2
{{Cl|SLEEP}} SOUND_DURATION
{{Cl|_SNDCLOSE}} h1
{{Cl|_SNDCLOSE}} h2


{{Cl|END}}
{{Cl|END}}
Line 69: Line 136:
* [[_MEM]], [[_MEMSOUND]], [[_MEMFREE]]
* [[_MEM]], [[_MEMSOUND]], [[_MEMFREE]]
* [[_MEMPUT]], [[_MEMGET]], [[_MEMGET (function)]]
* [[_MEMPUT]], [[_MEMGET]], [[_MEMGET (function)]]
* [[_SNDOPEN]], [[_SNDCLOSE]], [[_SNDRAW]]
* [[_SNDOPEN]], [[_SNDCLOSE]], [[_SNDRAW]], [[_SNDRATE]]




{{PageNavigation}}
{{PageNavigation}}

Latest revision as of 00:42, 6 March 2025

The _SNDNEW function creates a raw empty sound in memory and returns a LONG handle value for later access.


Syntax

soundHandle& = _SNDNEW(frames&[, channels&][, bits&][, sampleRate&])


Parameters

  • frames& is the number of sample frames needed. The number needed for one second of sound is determined by your sound hardware's sample rate, hence you may use the following formula:
    • frames& = _SNDRATE * neededSeconds! where you may also specify fractional seconds.
  • channels& (optional) specifies the number of channels (1 = mono, 2 = stereo). Defaults to 1 (mono) if omitted.
  • bits& (optional) specifies the number of bits per sample (8 = 8-bit unsigned integer, 16 = 16-bit signed integer, 32 = 32-bit floating point). Defaults to 32-bit if omitted.
  • sampleRate& (optional) specifies the playback sample rate in Hz. Defaults to the system's default sample rate if omitted.


Description

  • The _SNDNEW function creates an empty sound buffer in memory that can be filled with sample data.
  • Once created, the sound buffer can be accessed and modified using the _MEM interface, particularly with _MEMSOUND, _MEMGET, and _MEMPUT.
  • This function allows generating and storing sounds programmatically for repeated playback.
  • The sound memory can be populated with sample data from various sources, such as files, DATA statements, or procedural generation.
  • Sound memory pointers obtained with _MEMSOUND must be freed using _MEMFREE, and the sound handle itself must be released with _SNDCLOSE when no longer needed.


Availability

  • none

    none

  • v3.5.0

    v3.5.0

  • Apix.png
  • yes

    yes

  • yes

    yes

  • yes

    yes

  • Sample rate support was added in QB64-PE v4.2.0.


Examples

Example 1
Creating a sound at runtime and playing it.
_DEFINE A-Z AS LONG
OPTION _EXPLICIT

RANDOMIZE TIMER

CONST SOUND_DURATION = 5 ' duration in seconds
CONST SAMPLE_CHANNELS = 1 ' number of channes. For stereo, we need to add another _MEMPUT below and +offset by SAMPLE_BYTES
CONST SAMPLE_BYTES = _SIZE_OF_SINGLE ' number of bytes/sample (not frame!)

DIM h AS LONG: h = _SNDNEW(SOUND_DURATION * _SNDRATE, SAMPLE_CHANNELS, SAMPLE_BYTES * 8)
IF (h < 1) THEN
    PRINT "Failed to create sound!"
    END
END IF

DIM sndblk AS _MEM: sndblk = _MEMSOUND(h, 0)
IF sndblk.SIZE = 0 THEN
    _SNDCLOSE h
    PRINT "Failed to access sound data!"
    END
END IF

DIM t AS _INTEGER64
FOR t = 0 TO (SOUND_DURATION * _SNDRATE) - 1
    _MEMPUT sndblk, sndblk.OFFSET + (t * SAMPLE_BYTES * SAMPLE_CHANNELS), (SIN(_PI(880! * t) / _SNDRATE) + (RND - RND)) / 2! AS SINGLE ' mixes noise and a sine wave at half volume
NEXT

_SNDPLAY h

SLEEP SOUND_DURATION

_SNDCLOSE h

END
Example 2
Creating sounds with different sample rates.
_DEFINE A-Z AS LONG
OPTION _EXPLICIT

RANDOMIZE TIMER

CONST SOUND_DURATION = 3 ' duration in seconds
CONST SAMPLE_CHANNELS = 1 ' mono
CONST SAMPLE_BYTES = _SIZE_OF_SINGLE ' 32-bit floating point (4 bytes per sample)

DIM h1 AS LONG, h2 AS LONG
h1 = _SNDNEW(SOUND_DURATION * _SNDRATE, SAMPLE_CHANNELS, SAMPLE_BYTES * 8, _SNDRATE \ 2)
h2 = _SNDNEW(SOUND_DURATION * _SNDRATE, SAMPLE_CHANNELS, SAMPLE_BYTES * 8, _SNDRATE)

IF (h1 < 1) _ORELSE (h2 < 1) THEN
    PRINT "Failed to create sound!"
    END
END IF

DIM sndblk1 AS _MEM, sndblk2 AS _MEM
sndblk1 = _MEMSOUND(h1, 0)
sndblk2 = _MEMSOUND(h2, 0)

IF (sndblk1.SIZE = 0) _ORELSE (sndblk2.SIZE = 0) THEN
    PRINT "Failed to access sound data!"
    _SNDCLOSE h1
    _SNDCLOSE h2
    END
END IF

DIM t AS _INTEGER64
FOR t = 0 TO (SOUND_DURATION * _SNDRATE) - 1
    _MEMPUT sndblk1, sndblk1.OFFSET + (t * SAMPLE_BYTES), SIN(_PI(880! * t) / _SNDRATE) AS SINGLE
NEXT

FOR t = 0 TO (SOUND_DURATION * _SNDRATE) - 1
    _MEMPUT sndblk2, sndblk2.OFFSET + (t * SAMPLE_BYTES), SIN(_PI(880! * t) / _SNDRATE) AS SINGLE
NEXT

PRINT "Playing sound at"; _SNDRATE \ 2; "Hz..."
_SNDPLAY h1
SLEEP SOUND_DURATION * 2

PRINT "Playing sound at"; _SNDRATE; "Hz..."
_SNDPLAY h2
SLEEP SOUND_DURATION

_SNDCLOSE h1
_SNDCLOSE h2

END


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=SNDNEW&oldid=9642"