document audio

Author: braindigitalis

cmake/custom_targets.cmake

@@ -121,19 +121,67 @@ endfunction()
 function(run TARGETFILE)
     set(FILENAME "${CMAKE_BINARY_DIR}/iso/kernel.bin")
     set(OUTNAME "${CMAKE_BINARY_DIR}/${TARGETFILE}")
+
     # Choose network device based on -DUSE_E1000
     if(USE_E1000)
         set(NET_DEVICE "-device e1000,netdev=netuser")
     else()
         set(NET_DEVICE "-device rtl8139,netdev=netuser")
     endif()
+
     if (PROFILE_KERNEL)
         set(PROFILE "-serial file:callgrind.out")
     else()
         set(PROFILE "")
     endif()
+
+    # ---- Audio detection (Linux only) ----
+    set(AUDIO_OPTS "")
+    if(UNIX AND NOT APPLE)
+        # Try the modern help first. Some older QEMU builds return non-zero and print an error.
+        execute_process(
+                COMMAND qemu-system-x86_64 -audiodev help
+                OUTPUT_VARIABLE QEMU_AD_OUT
+                ERROR_VARIABLE QEMU_AD_ERR
+                RESULT_VARIABLE QEMU_AD_RC
+                OUTPUT_STRIP_TRAILING_WHITESPACE
+                ERROR_STRIP_TRAILING_WHITESPACE
+        )
+        # Combine both streams for robust matching
+        set(QEMU_AD_TEXT "${QEMU_AD_OUT}\n${QEMU_AD_ERR}")
+
+        if(QEMU_AD_RC EQUAL 0 OR QEMU_AD_TEXT MATCHES "Available audio drivers")
+            # Prefer PipeWire if QEMU lists it and host has it; else fall back to PulseAudio
+            set(_BACKEND "")
+            if(QEMU_AD_TEXT MATCHES "(^|[ \n\r\t])pipewire([ \n\r\t]|$)")
+                # Check host has PipeWire
+                execute_process(COMMAND pipewire --version RESULT_VARIABLE PW_RC OUTPUT_QUIET ERROR_QUIET)
+                if(PW_RC EQUAL 0)
+                    set(_BACKEND "pipewire")
+                endif()
+            endif()
+            if(_BACKEND STREQUAL "")
+                if(QEMU_AD_TEXT MATCHES "(^|[ \n\r\t])pa([ \n\r\t]|$)")
+                    # Check host has PulseAudio (or PipeWire's Pulse server)
+                    execute_process(COMMAND pactl --version RESULT_VARIABLE PA_RC OUTPUT_QUIET ERROR_QUIET)
+                    if(PA_RC EQUAL 0)
+                        set(_BACKEND "pa")
+                    endif()
+                endif()
+            endif()
+
+            if(_BACKEND STREQUAL "pipewire")
+                set(AUDIO_OPTS "-audiodev pipewire,id=snd0 -device AC97,audiodev=snd0")
+            elseif(_BACKEND STREQUAL "pa")
+                # If you strictly only want PipeWire, comment this line out to skip Pulse fallback.
+                set(AUDIO_OPTS "-audiodev pa,id=snd0 -device AC97,audiodev=snd0")
+            endif()
+        endif()
+    endif()
+    # ---- end audio detection ----
+
     add_custom_command(OUTPUT ${OUTNAME}
-        COMMAND echo "qemu-system-x86_64 \
+            COMMAND echo "qemu-system-x86_64 \
 	-machine q35,accel=kvm \
 	-s \
 	-monitor stdio \
@@ -152,8 +200,8 @@ function(run TARGETFILE)
 	-debugcon file:debug.log \
 	-netdev user,id=netuser,hostfwd=tcp::2000-:2000,hostfwd=tcp::2080-:80 \
 	-object filter-dump,id=dump,netdev=netuser,file=dump.dat \
-	${NET_DEVICE} ${PROFILE}" >${OUTNAME} && chmod ugo+x ${OUTNAME}
-        DEPENDS ${FILENAME})
+	${NET_DEVICE} ${PROFILE} ${AUDIO_OPTS}" >${OUTNAME} && chmod ugo+x ${OUTNAME}
+            DEPENDS ${FILENAME})
     add_custom_target(RUN_${TARGETFILE} ALL DEPENDS ${OUTNAME})
     add_dependencies(RUN_${TARGETFILE} "kernel.bin")
 endfunction()

docpages/basic-language-reference/BASIC_SOUND.md

@@ -0,0 +1,56 @@
+\page audio-basics Audio Introduction
+
+[TOC]
+
+## Audio System Structure
+
+Retro Rocket’s audio system has three main parts:
+
+### Drivers
+
+The driver is the low-level hardware backend (e.g. `MODLOAD "ac97"`).
+It is specific to your sound card in your PC. Without a driver, **no audio commands will work**.
+
+
+### Streams
+
+A stream is a **playback channel** created with `STREAM CREATE`.
+
+* Each stream has its own queue of sounds, volume, and state.
+* Multiple streams can run at once (for mixing music, effects, voices, etc.).
+* A stream handle is always a positive integer ID.
+
+
+### Sounds
+
+A sound is **decoded audio data** loaded into memory with `SOUND LOAD`.
+
+* Sounds can be loaded from any .WAV file which contains PCM or FLOAT format audio.
+* Sounds are stored in RAM as 44.1 kHz stereo, 16-bit PCM.
+* Sound handles are always non-zero integer IDs.
+* Sounds must be freed with `SOUND UNLOAD` when no longer needed.
+
+
+## Flow of audio
+
+```
+File on disk (WAV) → SOUND LOAD → Sound handle
+Sound handle + Stream → SOUND PLAY → Playback
+```
+
+## Example
+
+```basic
+MODLOAD "ac97"             ' load audio driver
+STREAM CREATE music        ' create playback channel
+SOUND LOAD song, "track.wav"  ' load audio into RAM
+SOUND PLAY music, song     ' play on stream
+```
+
+\image html sound.png
+
+## Audio Keywords/Functions
+
+- \ref STREAM "STREAM"
+- \ref STREAM "SOUND"
+- \ref DECIBELS "DECIBELS"

docpages/basic-language-reference/INDEX.md

@@ -32,6 +32,7 @@ For real-world examples of programs in the operating system, see the [os/program
 * \subpage variables
 * \subpage keywords
 * \subpage builtin-functions
+* \subpage audio-basics
 * \subpage networking
 * \subpage libraries
 * \subpage tasks

docpages/basic-language-reference/functions/integer/02_INDEX.md

@@ -19,6 +19,7 @@ The following functions operate on or return **integer values** in Retro Rocket
 * \subpage CURRENTX
 * \subpage CURRENTY
 * \subpage DAY
+* \subpage DECIBELS
 * \subpage EOF
 * \subpage EXISTSVARI
 * \subpage FILESIZE

docpages/basic-language-reference/functions/integer/DECIBELS.md

@@ -0,0 +1,64 @@
+\page DECIBELS DECIBELS Function
+
+```basic
+DECIBELS(integer-expression)
+```
+
+Converts a **decibel (dB) value** into a volume level suitable for `SOUND VOLUME`.
+The return value is always in the range **0–255**, where:
+
+* `0` means completely silent.
+* `255` means full volume (unity gain).
+
+---
+
+### What are decibels?
+
+Decibels are a way of describing **relative loudness**.
+They don’t measure sound directly, but how much **quieter or louder** something is compared to a reference point:
+
+* `0 dB` means “no change” - the sound plays at its original level.
+* Negative values (e.g. `-6 dB`, `-12 dB`) make the sound quieter.
+* The further the number is below zero, the quieter the result.
+* Positive values are not useful here. Anything above `0 dB` is clamped to maximum.
+
+For example, `-6 dB` is a common setting to “turn something down a bit” (50% loudness in Retro Rocket) without muting it.
+
+---
+
+### Behaviour in Retro Rocket
+
+* `DECIBELS(0)` → 255 (full volume).
+* `DECIBELS(-6)` → about half volume (128).
+* `DECIBELS(-12)` → quieter still (around 64).
+* `DECIBELS(-60)` → 0 (silent).
+
+Values above 0 are treated as 0 dB.
+Values below –60 are treated as silence.
+
+This gives a simple but natural way to think about volume, since each **–6 dB step roughly halves the loudness**.
+
+---
+
+### Notes
+
+* Use `DECIBELS()` when you want to set volume in familiar dB terms instead of raw 0–255 values.
+* The mapping is not linear: small changes near 0 dB make a noticeable difference, while changes at very low levels fade smoothly towards silence.
+* Internally this uses a fast lookup table, so performance is constant time.
+
+---
+
+### Examples
+
+```basic
+gain = DECIBELS(-6)
+SOUND VOLUME music, gain
+
+gain = DECIBELS(-20)
+SOUND VOLUME effects, gain
+```
+
+---
+
+**See also**
+\ref SOUND "SOUND" VOLUME · \ref STREAM "STREAM"

docpages/basic-language-reference/keywords/00_INDEX.md

@@ -129,8 +129,10 @@ The following parameter types are used throughout this documentation:
 * \subpage SOCKFLUSH
 * \subpage SOCKREAD
 * \subpage SOCKWRITE
+* \subpage SOUND
 * \subpage SPRITEFREE
 * \subpage SPRITELOAD
+* \subpage STREAM
 * \subpage TRIANGLE
 * \subpage UDPBIND
 * \subpage UDPUNBIND