Document raw AudioStream (constructor and append)

Documents the changes merged in https://github.com/bjornbytes/lovr/pull/180

api/lovr/audio/Source/seek.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'Set the playback position of the Source.',
-  description = 'Seeks the Source to the specified position.',
+  description = 'Seeks the Source to the specified position. Note that you may not `seek()` a `Source` backed by a raw `AudioStream`.',
   arguments = {
     {
       name = 'position',

api/lovr/audio/Source/tell.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'Get the playback position of the Source.',
-  description = 'Returns the current playback position of the Source.',
+  description = 'Returns the current playback position of the Source. Note that you may not `tell()` a `Source` backed by a raw `AudioStream`.',
   arguments = {
     {
       name = 'unit',

api/lovr/data/AudioStream/append.lua

@@ -0,0 +1,56 @@
+return {
+    summary = 'Append raw PCM audio data to this audio stream for playback.',
+    description = [[
+      Append audio data that you have constructed yourself (perhaps by generating it in code, or streaming it over the network).
+      Must only be called on a "raw" AudioStream (not one constructed with a file or a blob).
+
+      The data must be 16-bit signed integer, and the sample rate and channel count must match the values the AudioStream was
+      constructed with.
+
+      If a call to `append` would make the internal buffer of this `AudioStream` to become bigger than the `queueLimit` set 
+      on this AudioStream when it was constructed, that call to `append` will ignore your blob and return false, queueing
+      no data at all from that call.
+      
+      After you've created a Source with your raw AudioStream, and appended enough audio data, remember to call `Source:play()`
+      to make the `Source` start playing your queued data. If the `Source` plays all the audio data you've queued
+      and thus runs out of data to play, it will automatically stop and you'll have to append more sound data and call `Source:play()`
+      again. You can use `AudioStream:getDuration()` to see how much data has been queued so far. 
+      
+      Try to have more audio queued than the time it will take before you call append() again to avoid stuttery playback. Having
+      more than 0.2s audio queued at all times is a good guideline.
+    ]],
+    arguments = {
+        {
+            name = 'blob',
+            type = 'blob',
+            description = 'A `blob` of sound bytes. Since it has no information about the format of the data, `append` blindly trusts that you give it valid data.'
+        },
+        {
+            name = 'soundData',
+            type = 'soundData',
+            description = 'A SoundData blob of sound bytes. Lovr will assert if the format of the `SoundData` doesn\'t match the format of the `AudioStream`.'
+        },
+    },
+    returns = {
+      {
+        name = 'success',
+        type = 'bool',
+        description = 'True if this `append` did not exceed the queue limit, and data was thus appended to the queue; otherwise false.'
+      }
+    },
+    variants = {
+        {
+            arguments = { 'blob' },
+            returns = { 'success' }
+        },
+        {
+            arguments = { 'soundData' },
+            returns = { 'success' }
+        }
+    }
+    related = {
+      'lovr.audio.newAudioStream',
+      'AudioStream:getDuration'
+    }
+  }
+  

api/lovr/data/newAudioStream.lua

@@ -1,7 +1,10 @@
 return {
   summary = 'Create a new AudioStream.',
   description = [[
-    Creates a new AudioStream.  Right now, the only supported audio format is Ogg Vorbis (.ogg).
+    Creates a new AudioStream. AudioStream has two modes:
+
+    1. Constructed with a filename or blob, AudioStream will decode the given file on demand. Right now, the only supported audio format is Ogg Vorbis (.ogg).
+    2. Constructed without, it's a "raw" audiostream that you append data to in real-time. See `AudioStream:append` for usage.
   ]],
   arguments = {
     filename = {
@@ -16,6 +19,15 @@ return {
       type = 'number',
       default = '4096',
       description = 'The size of the stream\'s audio buffer, in samples.'
+    },
+    queueLimit = {
+      type = 'number',
+      default = 'sampleRate*0.5',
+      description = 'The maximum number of audio samples that this AudioStream will queue. The default is half a second worth of data. Set to 0 for no limit (but be careful not to use too much RAM).'
+    },
+    channelCount = {
+      type = 'number',
+      description = 'Number of audio channels (1 for mono or 2 for stereo)'
     }
   },
   returns = {
@@ -26,12 +38,19 @@ return {
   },
   variants = {
     {
+      description = 'Create an `AudioStream` decoding ogg audio from the file at `filename`',
       arguments = { 'filename', 'bufferSize' },
       returns = { 'audioStream' }
     },
     {
+      description = 'Create an `AudioStream` decoding ogg audio from the given blob.',
       arguments = { 'blob', 'bufferSize' },
       returns = { 'audioStream' }
+    },
+    {
+      description = 'Create a raw `AudioStream`. You must call `append` to give it audio to stream later.',
+      arguments = { 'channelCount', 'sampleRate', 'bufferSize', 'queueLimit'},
+      returns = { 'audioStream' }
     }
   }
 }