Merge pull request #14 from alloverse/rawaudiostream

Documentation for new audio APIs

api/lovr/audio/Microphone/getData.lua

@@ -3,12 +3,50 @@ return {
   description = [[
     Returns a new SoundData with all of the buffered audio samples that the Microphone has recorded.
   ]],
-  arguments = {},
-  returns = {
+  arguments = {
+    {
+      name = 'soundData',
+      type = 'soundData',
+      description = 'The `SoundData` to fill with audio (instead of this method creating a new one).'
+    },
+    {
+      name = 'sampleCount',
+      type = 'number',
+      description = 'How many samples of audio to get right now, at most. If less is available, you will get less.'
+    },
     {
-      name = 'channels',
+      name = 'offset',
       type = 'number',
-      description = 'The number of channels recorded.'
+      description = 'Index in samples into `soundData` at which to start to overwrite with new audio data from the microphone\'s internal buffer.'
+    }
+  },
+  returns = {
+    {
+      name = 'soundData',
+      type = 'soundData',
+      description = 'A `SoundData` with `sampleCount` of samples in it (or less if less was available; or all if sampleCount was not given). Nothing is returned if no data is available.'
+    }
+  },
+  variants = {
+    {
+        description = "Get all available audio as a newly created `SoundData`",
+        arguments = { },
+        returns = { 'soundData' }
+    },
+    {
+      description = "Get at most `sampleCount` samples from the microphone\'s internal queue as a newly created `SoundData`",
+      arguments = { 'sampleCount' },
+      returns = { 'soundData' }
+    },
+    {
+      description = "Get at all available audio and write it into `soundData`.",
+      arguments = { 'soundData' },
+      returns = { 'soundData' }
+    },
+    {
+      description = "Get at all available audio and write it into `soundData` starting at 'offset' samples into `soundData`.",
+      arguments = { 'soundData', 'offset' },
+      returns = { 'soundData' }
     }
   },
   notes = [[

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/SoundData/getBlob.lua

@@ -0,0 +1,13 @@
+return {
+    summary = 'Get the bytes backing this SoundData as a `Blob`.',
+    description = 'This replaces `SoundData:getPointer()`, since you can get that through the blob.',
+    arguments = {},
+    returns = {
+      {
+        name = 'blob',
+        type = 'blob',
+        description = 'The blob instance containing the bytes for the `SoundData`.'
+      }
+    }
+  }
+  

api/lovr/data/TextureData/getBlob.lua

@@ -0,0 +1,13 @@
+return {
+    summary = 'Get the bytes backing this `TextureData` as a `Blob`.',
+    description = 'This replaces `TextureData:getPointer()`, since you can get that through the blob.',
+    arguments = {},
+    returns = {
+      {
+        name = 'blob',
+        type = 'blob',
+        description = 'The blob instance containing the bytes for the `TextureData`.'
+      }
+    }
+  }
+  

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' }
     }
   }
 }