raylib icon indicating copy to clipboard operation
raylib copied to clipboard
verified publisher icon raysan5

[examples] Review audio examples `audio_raw_stream`(split) and `audio_sound_loading` to add more clarity

Open meisei4 opened this issue 1 month ago • 5 comments

Review audio examples to provide more clarity

I was encountering many time-consuming audio specification issues in my own tests and so I thought things could be improved documentation-wise in this area. My idea is simply updating the following examples to be a little more clear/expressive with how raudio.c works, especially in relation to the Update related functions.

NOTE: the main diff for this reviewing this PR is:https://github.com/raysan5/raylib/commit/b3c25186d9cf395bab53f8b4b5f4162d88897242 because it allows you to see how the original audio_raw_stream was updated after it was COPIED/SPLIT for both manual and callbacks variations.

audio_raw_stream: (manual) diff with original

  1. fix the commented out code styling of this example -> split the manual and the callback into two separate examples
  2. fix the wavelength discrepancy between callback and manual (manual resulted in an octave pitch higher than callback version): waveLength = (int)(22050/frequency); to waveLength = (int)(stream.sampleRate/frequency); <- this will use 44100 via sampleRate

audio_raw_stream_callback: diff with original

  1. add more clarity with coverage/new callback options (ESPECIALLY TO ALLOW FOR TESTING PROBLEMATIC BEHAVIOR)
  2. add simple toggle between callbacks specifications

audio_sound_loading

  1. there was no usage of UpdateSound anywhere in the raylib codebase, so I added a simple reversal effect using that function in the existing audio_load_sound example. If this is inappropriate then perhaps UpdateSound as a function should be removed from raudio? as it is never used and just calls StopAudioBuffer and memcpy (which is very different behavior than something like UpdateAudioStream, and AudioProcessors take care of all the sort of effects you can do on sounds anyways i believe)
  2. There may be some need for documentation improvements with Sound always setting stream specifications 'sampleSizeto32`, and channels as stereo, so I also thought it would be helpful to have this example for showing that updating sound you need to also always match those specs between any scratch data you want to work with

Also since it provides really simple opportunity to demonstrate how strict the Sound streams are, I believe it is appropriate to add to this bare mininum load sound example, rather than try to add it somewhere else.

meisei4 avatar Nov 12 '25 22:11 meisei4

@meisei4 I prefer to avoid changing audio_load_sound and keep it simple as it was.

raysan5 avatar Nov 13 '25 09:11 raysan5

@raysan5 I have reverted the changes for that example. But i wanted to confirm that Sounds are intentionally always sampleSize of 32 and channeled to stereo?

The issue i encountered here was from trying to figure out how to use the UpdateSound function. Where now i am confused as to why the function exists actually, being that its just a memcpy that can result in issues if you are not careful with the exact specification of the audio data you are working with (must be exactly same formatting and size as the sound you are updating). I think it is something that is not very clear in comparison to the flexibility of what being an AudioStream wrapper could allow (and what Music and raw audio streams do allow)

meisei4 avatar Nov 13 '25 17:11 meisei4

But i wanted to confirm that Sounds are intentionally always sampleSize of 32 and channeled to stereo?

No, afair, it is dependand on the loaded sound. About UpdateSound(), it is like UpdateTexture(), it's up to the user to provide data in the correct format.

raysan5 avatar Nov 18 '25 15:11 raysan5

it is dependent on the loaded sound. About UpdateSound(), it is like UpdateTexture(), it's up to the user to provide data in the correct format.

I see, so then i think there might be an issue here in expected behavior. Because UpdateSound, and Sound in general (loading and then any processing) is enforcing (implicitly) 32 bit and stereo specifications according to my understanding from this investigation:

So far in this area there has only been an addition in the form of commented warnings (thanks to @AmityWilder for helping me discover this behavior: https://github.com/raysan5/raylib/pull/5031). It was being encountered over in the rust bindings initially: https://github.com/raylib-rs/raylib-rs/pull/212

@raysan5 I am wondering if you would like for this to be updated such that Sound can be configured to behave as flexibly as raw AudioStream and Music? (allowing for both Mono and Stereo channeling and then 8, 16, and 32 bit depths etc?)

meisei4 avatar Nov 21 '25 01:11 meisei4

@meisei4 I'm reviewing this PR, you are right, Sounds are converted at loading to output format of the playback device, by default:

INFO: AUDIO: Device initialized successfully
INFO:     > Backend:       miniaudio | WASAPI
INFO:     > Format:        32-bit IEEE Floating Point -> 32-bit IEEE Floating Point
INFO:     > Channels:      2 -> 2
INFO:     > Sample rate:   48000 -> 48000
INFO:     > Periods size:  1440

Just reviewed function comments to make it clear.

About the example split, I prefer to keep it as a single example with just one callback function but it can be improved with comments to explain the limitation to a single data format.

raysan5 avatar Nov 30 '25 18:11 raysan5