FLAC support

Author: braindigitalis

docpages/basic-language-reference/BASIC_SOUND.md

@@ -18,8 +18,9 @@ Codecs are provided as kernel modules, just like drivers, and must be loaded bef
 
 * WAV support is built in and always available.
 * MP3 support is available via the `mp3.ko` module (`MODLOAD "mp3"`).
+* FLAC support is available via the `flac.ko` module (`MODLOAD "flac"`).
 
-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.
+If you try to load any file type except WAV without first loading the corresponding codec module, you will receive an error as the file type will be unrecognised.
 
 ### Streams
 
@@ -33,7 +34,7 @@ A stream is a **playback channel** created with `STREAM CREATE`.
 
 A sound is **decoded audio data** loaded into memory with `SOUND LOAD`.
 
-* Sounds can be loaded from any supported codec (e.g. WAV, MP3).
+* Sounds can be loaded from any supported codec (e.g. WAV, MP3, FLAC).
 * 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.
@@ -70,6 +71,16 @@ SOUND PLAY music, song
 
 \image html mp3.png
 
+### Play a FLAC file
+
+```basic
+MODLOAD "ac97"                     ' load audio driver
+MODLOAD "flac"                     ' load FLAC codec module
+STREAM CREATE music
+SOUND LOAD song, "track.flac"
+SOUND PLAY music, song
+```
+
 ## Audio Keywords/Functions
 
 * \ref STREAM "STREAM"

docs/ABS.html

@@ -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_md69"></a>
+<h3><a class="anchor" id="autotoc_md70"></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_md71"></a>
+<h3><a class="anchor" id="autotoc_md72"></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_md71"></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_md73"></a>
+<h3><a class="anchor" id="autotoc_md74"></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_md73"></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 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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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">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_md457"></a>
+<h3><a class="anchor" id="autotoc_md458"></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_md457"></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_md459"></a>
+<h3><a class="anchor" id="autotoc_md460"></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_md459"></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 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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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">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_md76"></a>
+<h3><a class="anchor" id="autotoc_md77"></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_md76"></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_md78"></a>
+<h3><a class="anchor" id="autotoc_md79"></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_md78"></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 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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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

@@ -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_md462"></a>
+<h3><a class="anchor" id="autotoc_md463"></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_md462"></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_md464"></a>
+<h3><a class="anchor" id="autotoc_md465"></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_md464"></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 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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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

@@ -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_md467"></a>
+<h3><a class="anchor" id="autotoc_md468"></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_md467"></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_md469"></a>
+<h3><a class="anchor" id="autotoc_md470"></a>
 Notes</h3>
 <ul>
 <li>Input range: any real number is valid.</li>
@@ -123,7 +123,7 @@ <h3><a class="anchor" id="autotoc_md469"></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 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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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

@@ -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_md472"></a>
+<h3><a class="anchor" id="autotoc_md473"></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_md472"></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_md474"></a>
+<h3><a class="anchor" id="autotoc_md475"></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_md474"></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 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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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/AUTOFLIP.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 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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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/BACKGROUND.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 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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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/BINREAD.html

@@ -97,7 +97,7 @@
 <li><code>integer-length</code> — number of bytes to read.</li>
 </ul>
 <hr  />
-<h3><a class="anchor" id="autotoc_md720"></a>
+<h3><a class="anchor" id="autotoc_md721"></a>
 Examples</h3>
 <div class="fragment"><div class="line">fh  = OPENIN(&quot;asset.bin&quot;)</div>
 <div class="line">size = FILESIZE(&quot;asset.bin&quot;)</div>
@@ -109,7 +109,7 @@ <h3><a class="anchor" id="autotoc_md720"></a>
 <div class="line">MEMRELEASE buf</div>
 <div class="line">CLOSE fh</div>
 </div><!-- fragment --><hr  />
-<h3><a class="anchor" id="autotoc_md722"></a>
+<h3><a class="anchor" id="autotoc_md723"></a>
 Notes</h3>
 <ul>
 <li>Use <a class="el" href="FILESIZE.html">FILESIZE</a> to size your buffer appropriately.</li>
@@ -125,7 +125,7 @@ <h3><a class="anchor" id="autotoc_md722"></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="keywords.html">Keywords</a></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>
+    <li class="footer">Generated on Thu Sep 18 2025 22:41: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>