commit b110c29749b3fba8dcdf86dfefd5a6a5521fe084
Author: Max Rottenkolber <max@mr.gy>
Date:   Sun Jul 26 20:45:05 2015 +0200

    Add riff-wave documentation.

diff --git a/software/riff-wave/api.mk2 b/software/riff-wave/api.mk2
new file mode 100644
index 0000000..2b88288
--- /dev/null
+++ b/software/riff-wave/api.mk2
@@ -0,0 +1,135 @@
+< riff-wave.read
+
+ Functins to read WAVE files.
+
+
+ < read-sample \(Function\)
+
+  *Syntax:*
+
+  — Function: *read-sample* _stream_ _sample-size_
+
+  → _sample_
+
+  *Arguments and Values:*
+
+  _stream_—a _binary input stream_.
+
+  _sample-size_—the sample size of the WAVE _stream_.
+
+  _sample_—either an {\(unsigned-byte 8\)} or an {\(unsigned-byte 16\)}
+  depending on _sample-size_.
+
+  *Description:*
+
+  {read-sample} reads and returns a sample of _sample-size_ from
+  _stream_.
+
+ >
+
+
+ < read-wave-header \(Function\)
+
+  *Syntax:*
+
+  — Function: *read-wave-header* _stream_
+
+  → _sample-rate_, _sample-size_, _n-channels_, _length_
+
+  *Arguments and Values:*
+
+  _stream_—a _binary input stream_.
+
+  _sample-rate_—the sample rate in Hertz specified by the WAVE header.
+  Represented as a positive _integer_.
+
+  _sample-size_—the sample size specified by the WAVE header. May be be 1
+  or 2 indicating 8-bit or 16-bit samples respectively.
+
+  _n-channels_—the number of channels specified by the WAVE header.
+  Represented as a positive _integer_.
+
+  _length_—the contained number of samples per channel specified by the
+  WAVE header. Represented as an unsigned _integer_.
+
+  *Description:*
+
+  {read-wave-header} reads a PCM WAVE header at _stream_ and returns the
+  _sample-rate_, _sample-size_, _n-channels_, and _length_ of the WAVE
+  stream specified by the header. _Stream_ is advanced to the beginning
+  of the first sample and {read-sample} may be used to read _length_
+  times _n-samples_ of _sample-size_ from _stream_.
+
+  E.g. if a WAVE stream contains two channels and has a length of four,
+  then there should be eight samples in the stream, with each even sample
+  belonging to the first channel and each odd sample belonging to the
+  second channel of the stream.
+
+  *Exceptional Situations:*
+
+  Signals an error of _type_ {error} if _stream_ does not contain a
+  RIFF/WAVE header using the PCM audio format.
+
+ >
+
+>
+
+
+< riff-wave.write
+
+ Functions to write WAVE files.
+
+
+ < write-sample \(Function\)
+
+  *Syntax:*
+
+  — Function: *write-sample* _sample_ _sample-size_ _stream_
+
+  *Arguments and Values:*
+
+  _sample_—the sample value represented as a {\(real -1 1\)}.
+
+  _sample-size_—one to write an 8-bit sample; Two to write a 16-bit
+  sample.
+
+  _stream_—a _binary output stream_.
+
+  {write-sample} writes _sample_ encoded in _sample-size_ bytes to
+  _stream_.
+
+ >
+
+
+ < write-wave-header \(Function\)
+
+  *Syntax:*
+
+  — Function: *write-wave-header* _sample-rate_ _sample-size_
+  _n-channels_ _length_ _stream_
+
+  *Arguments and Values:*
+
+  _sample-rate_—an {\(unsigned-byte 32\)} denoting the sample rate in
+  Hertz.
+
+  _sample-size_—one for 8-bit samples; Two for 16-bit samples.
+
+  _n-channels_—a positive _integer_ denoting the number of channels.
+
+  _length_—an unsigned _integer_ denoting the number of samples per
+  channel following the WAVE header.
+
+  _stream_—a _binary output stream_.
+
+  *Description:*
+
+  {write-wave-header} writes the PCM WAVE header specified by
+  _sample-rate_, _sample-size_, _n-channels_ and _length_ to _stream_.
+  {write-sample} should be used to write _n-channels_ times _length_
+  samples of _sample-size_ to _stream_.
+
+ >
+
+>
+