mp3 docs

Author: braindigitalis

docpages/basic-language-reference/BASIC_SOUND.md

@@ -4,13 +4,22 @@
 
 ## Audio System Structure
 
-Retro Rocket’s audio system has three main parts:
+Retro Rocket’s audio system has four main parts:
 
 ### Drivers
 
-The driver is the low-level hardware backend (e.g. `MODLOAD "ac97"`).
+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**.
 
+### Codecs
+
+A codec is a small specialised program that knows how to **decode audio files** into the raw data format used by Retro Rocket.
+Codecs are provided as kernel modules, just like drivers, and must be loaded before you can use them.
+
+* WAV support is built in and always available.
+* MP3 support is available via the `mp3.ko` module (`MODLOAD "mp3"`).
+
+If you try to load an MP3 file without first loading the MP3 codec module, you will receive an error as the file type will be unrecognised.
 
 ### Streams
 
@@ -20,37 +29,50 @@ A stream is a **playback channel** created with `STREAM CREATE`.
 * 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 can be loaded from any supported codec (e.g. WAV, MP3).
 * 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
+File on disk (WAV/MP3/other) → Codec module decodes → SOUND LOAD → Sound handle
 Sound handle + Stream → SOUND PLAY → Playback
 ```
 
-## Example
+## Examples
+
+### Play a WAV file
 
 ```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
+MODLOAD "ac97"                     ' load audio driver
+STREAM CREATE music
+SOUND LOAD song, "track.wav"
+SOUND PLAY music, song
 ```
 
 \image html sound.png
 
+### Play an MP3 file
+
+```basic
+MODLOAD "ac97"                     ' load audio driver
+MODLOAD "mp3"                      ' load MP3 codec module
+STREAM CREATE music
+SOUND LOAD song, "track.mp3"
+SOUND PLAY music, song
+```
+
+\image html mp3.png
+
 ## Audio Keywords/Functions
 
-- \ref STREAM "STREAM"
-- \ref STREAM "SOUND"
-- \ref DECIBELS "DECIBELS"
+* \ref STREAM "STREAM"
+* \ref STREAM "SOUND"
+* \ref DECIBELS "DECIBELS"
+

docpages/images/mp3.png

@@ -92,15 +92,15 @@
 <div class="textblock"><div class="fragment"><div class="line">ABS(numeric-expression)</div>
 </div><!-- fragment --><p>Returns the <b>absolute value</b> of a numeric expression. Negative values are converted to positive; positive values remain unchanged.</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md66"></a>
+<h3><a class="anchor" id="autotoc_md69"></a>
 How to read it</h3>
 <ul>
 <li>For integers: <code>ABS(-5)</code> becomes <code>5</code>.</li>
 <li>For reals: <code>ABS(-3.14)</code> becomes <code>3.14</code>.</li>
 <li>Zero always remains <code>0</code>.</li>
 </ul>
 <hr  />
-<h3><a class="anchor" id="autotoc_md68"></a>
+<h3><a class="anchor" id="autotoc_md71"></a>
 Examples</h3>
 <div class="fragment"><div class="line">PRINT ABS(-42)</div>
 </div><!-- fragment --><p>This example produces <code>42</code>.</p>
@@ -112,7 +112,7 @@ <h3><a class="anchor" id="autotoc_md68"></a>
 <div class="line">    PRINT &quot;Distance: &quot;; ABS(x)</div>
 <div class="line">NEXT</div>
 </div><!-- fragment --><hr  />
-<h3><a class="anchor" id="autotoc_md70"></a>
+<h3><a class="anchor" id="autotoc_md73"></a>
 Notes</h3>
 <ul>
 <li>Works with both <b>integers</b> and <b>reals</b>.</li>
@@ -128,7 +128,7 @@ <h3><a class="anchor" id="autotoc_md70"></a>
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="basic-ref.html">BASIC Language Reference</a></li><li class="navelem"><a class="el" href="builtin-functions.html">Built-In Functions</a></li><li class="navelem"><a class="el" href="int-funcs.html">Integer Functions</a></li>
-    <li class="footer">Generated on Thu Sep 18 2025 00:15:35 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Thu Sep 18 2025 21:16:10 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

docs/ABS.html

@@ -92,7 +92,7 @@
 <div class="textblock"><div class="fragment"><div class="line">ACS(real-expression)</div>
 </div><!-- fragment --><p>Returns the <b>arc cosine</b> (inverse cosine) of the given expression, in <b>radians</b>. The input must be between <code>-1</code> and <code>1</code>.</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md454"></a>
+<h3><a class="anchor" id="autotoc_md457"></a>
 Examples</h3>
 <div class="fragment"><div class="line">PRINT ACS(1)</div>
 </div><!-- fragment --><p>Produces <code>0</code>.</p>
@@ -105,7 +105,7 @@ <h3><a class="anchor" id="autotoc_md454"></a>
 <div class="line">PRINT ACS(COS(angle#))</div>
 </div><!-- fragment --><p>Produces the original angle (within floating point accuracy).</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md456"></a>
+<h3><a class="anchor" id="autotoc_md459"></a>
 Notes</h3>
 <ul>
 <li>Argument range: <code>-1 ≤ x ≤ 1</code>. Values outside this range cause an error.</li>
@@ -126,7 +126,7 @@ <h3><a class="anchor" id="autotoc_md456"></a>
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="basic-ref.html">BASIC Language Reference</a></li><li class="navelem"><a class="el" href="builtin-functions.html">Built-In Functions</a></li><li class="navelem"><a class="el" href="real-funcs.html">Real Functions</a></li>
-    <li class="footer">Generated on Thu Sep 18 2025 00:15:35 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Thu Sep 18 2025 21:16:10 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

docs/ACS.html

@@ -92,7 +92,7 @@
 <div class="textblock"><div class="fragment"><div class="line">ASC(string-expression)</div>
 </div><!-- fragment --><p>Returns the <b>ASCII code</b> of the first character in <code>string-expression</code>.</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md73"></a>
+<h3><a class="anchor" id="autotoc_md76"></a>
 Examples</h3>
 <div class="fragment"><div class="line">PRINT ASC(&quot;A&quot;)</div>
 </div><!-- fragment --><p>This example produces <code>65</code>.</p>
@@ -106,7 +106,7 @@ <h3><a class="anchor" id="autotoc_md73"></a>
 <div class="line">    PRINT &quot;You pressed: &quot;; code</div>
 <div class="line">ENDIF</div>
 </div><!-- fragment --><hr  />
-<h3><a class="anchor" id="autotoc_md75"></a>
+<h3><a class="anchor" id="autotoc_md78"></a>
 Notes</h3>
 <ul>
 <li>Only the <b>first character</b> of the string is considered.</li>
@@ -122,7 +122,7 @@ <h3><a class="anchor" id="autotoc_md75"></a>
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="basic-ref.html">BASIC Language Reference</a></li><li class="navelem"><a class="el" href="builtin-functions.html">Built-In Functions</a></li><li class="navelem"><a class="el" href="int-funcs.html">Integer Functions</a></li>
-    <li class="footer">Generated on Thu Sep 18 2025 00:15:35 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Thu Sep 18 2025 21:16:10 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

docs/ASC.html

@@ -92,7 +92,7 @@
 <div class="textblock"><div class="fragment"><div class="line">ASN(real-expression)</div>
 </div><!-- fragment --><p>Returns the <b>arc sine</b> (inverse sine) of the given expression, in <b>radians</b>. The input must be between <code>-1</code> and <code>1</code>.</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md459"></a>
+<h3><a class="anchor" id="autotoc_md462"></a>
 Examples</h3>
 <div class="fragment"><div class="line">PRINT ASN(0)</div>
 </div><!-- fragment --><p>Produces <code>0</code>.</p>
@@ -105,7 +105,7 @@ <h3><a class="anchor" id="autotoc_md459"></a>
 <div class="line">PRINT ASN(SIN(angle#))</div>
 </div><!-- fragment --><p>Produces the original angle (within floating point accuracy).</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md461"></a>
+<h3><a class="anchor" id="autotoc_md464"></a>
 Notes</h3>
 <ul>
 <li>Argument range: <code>-1 ≤ x ≤ 1</code>. Values outside this range cause an error.</li>
@@ -126,7 +126,7 @@ <h3><a class="anchor" id="autotoc_md461"></a>
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="basic-ref.html">BASIC Language Reference</a></li><li class="navelem"><a class="el" href="builtin-functions.html">Built-In Functions</a></li><li class="navelem"><a class="el" href="real-funcs.html">Real Functions</a></li>
-    <li class="footer">Generated on Thu Sep 18 2025 00:15:35 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Thu Sep 18 2025 21:16:10 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

docs/ASN.html

@@ -93,7 +93,7 @@
 </div><!-- fragment --><p>Returns the <b>arc tangent</b> (inverse tangent) of the given expression, in <b>radians</b>.</p>
 <p>The result will always lie between <code>-PI#/2</code> and <code>PI#/2</code>.</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md464"></a>
+<h3><a class="anchor" id="autotoc_md467"></a>
 Examples</h3>
 <div class="fragment"><div class="line">PRINT ATAN(0)</div>
 </div><!-- fragment --><p>Produces <code>0</code>.</p>
@@ -106,7 +106,7 @@ <h3><a class="anchor" id="autotoc_md464"></a>
 <div class="line">PRINT ATAN(TAN(angle#))</div>
 </div><!-- fragment --><p>Produces the original angle (within floating point accuracy).</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md466"></a>
+<h3><a class="anchor" id="autotoc_md469"></a>
 Notes</h3>
 <ul>
 <li>Input range: any real number is valid.</li>
@@ -123,7 +123,7 @@ <h3><a class="anchor" id="autotoc_md466"></a>
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="basic-ref.html">BASIC Language Reference</a></li><li class="navelem"><a class="el" href="builtin-functions.html">Built-In Functions</a></li><li class="navelem"><a class="el" href="real-funcs.html">Real Functions</a></li>
-    <li class="footer">Generated on Thu Sep 18 2025 00:15:35 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Thu Sep 18 2025 21:16:10 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

docs/ATAN.html

@@ -92,7 +92,7 @@
 <div class="textblock"><div class="fragment"><div class="line">ATAN2(real-y, real-x)</div>
 </div><!-- fragment --><p>Returns the <b>arc tangent of y ÷ x</b>, using the signs of both arguments to determine the correct <b>quadrant</b> of the angle. The result is given in <b>radians</b>, in the range <code>-PI#</code> to <code>PI#</code>.</p>
 <hr  />
-<h3><a class="anchor" id="autotoc_md469"></a>
+<h3><a class="anchor" id="autotoc_md472"></a>
 Examples</h3>
 <div class="fragment"><div class="line">PRINT ATAN2(1, 1)</div>
 </div><!-- fragment --><p>Produces approximately <code>0.785398</code> (π/4).</p>
@@ -108,7 +108,7 @@ <h3><a class="anchor" id="autotoc_md469"></a>
 <div class="line">angle# = ATAN2(dy#, dx#)</div>
 <div class="line">PRINT &quot;Angle = &quot;; angle#; &quot; radians&quot;</div>
 </div><!-- fragment --><hr  />
-<h3><a class="anchor" id="autotoc_md471"></a>
+<h3><a class="anchor" id="autotoc_md474"></a>
 Notes</h3>
 <ul>
 <li>Unlike <a class="el" href="ATAN.html">ATAN</a>, which only returns results in <code>-π/2 … π/2</code>, <code>ATAN2</code> resolves the full circle by considering both <code>x</code> and <code>y</code> signs.</li>
@@ -125,7 +125,7 @@ <h3><a class="anchor" id="autotoc_md471"></a>
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="basic-ref.html">BASIC Language Reference</a></li><li class="navelem"><a class="el" href="builtin-functions.html">Built-In Functions</a></li><li class="navelem"><a class="el" href="real-funcs.html">Real Functions</a></li>
-    <li class="footer">Generated on Thu Sep 18 2025 00:15:35 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Thu Sep 18 2025 21:16:10 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

docs/ATAN2.html

@@ -102,7 +102,7 @@
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="basic-ref.html">BASIC Language Reference</a></li><li class="navelem"><a class="el" href="keywords.html">Keywords</a></li>
-    <li class="footer">Generated on Thu Sep 18 2025 00:15:35 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Thu Sep 18 2025 21:16:11 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

docs/AUTOFLIP.html

@@ -157,7 +157,7 @@ <h5>Notes</h5>
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="index.html">index</a></li><li class="navelem"><a class="el" href="basic-ref.html">BASIC Language Reference</a></li><li class="navelem"><a class="el" href="keywords.html">Keywords</a></li>
-    <li class="footer">Generated on Thu Sep 18 2025 00:15:35 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Thu Sep 18 2025 21:16:11 for Retro Rocket OS by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>