MOAR;

api/lovr/audio/AudioShareMode.lua

@@ -0,0 +1,22 @@
+return {
+  summary = 'How audio devices are shared on the system.',
+  description = [[
+    Audio devices can be created in shared mode or exclusive mode.  In exclusive mode, the audio
+    device is the only one active on the system, which gives better performance and lower latency.
+    However, exclusive devices aren't always supported and might not be allowed, so there is a
+    higher chance that creating one will fail.
+  ]],
+  values = {
+    {
+      name = 'shared',
+      description = 'Shared mode.'
+    },
+    {
+      name = 'exclusive',
+      description = 'Exclusive mode.'
+    }
+  },
+  related = {
+    'lovr.audio.setDevice'
+  }
+}

api/lovr/audio/AudioType.lua

@@ -0,0 +1,16 @@
+return {
+  summary = 'Different types of audio devices',
+  description = [[
+    When referencing audio devices, this type indicates whether it's the playback or capture device.
+  ]],
+  values = {
+    {
+      name = 'playback',
+      description = 'The playback device (speakers, headphones).'
+    },
+    {
+      name = 'capture',
+      description = 'The capture device (microphone).'
+    }
+  }
+}

api/lovr/audio/Source/clone.lua

@@ -0,0 +1,24 @@
+return {
+  summary = 'Create an identical copy of the Source.',
+  description = [[
+    Creates a copy of the Source, referencing the same `Sound` object and inheriting all of the
+    settings of this Source.  However, it will be created in the stopped state and will be rewound to
+    the beginning.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'source',
+      type = 'Source',
+      description = 'A genetically identical copy of the Source.'
+    }
+  },
+  notes = [[
+    This is a good way to create multiple Sources that play the same sound, since the audio data
+    won't be loaded multiple times and can just be reused.  You can also create multiple `Source`
+    objects and pass in the same `Sound` object for each one, which will have the same effect.
+  ]],
+  related = {
+    'lovr.audio.newSource'
+  }
+}

api/lovr/audio/Source/init.lua

@@ -11,5 +11,8 @@ return {
     `Source:seek` and `Source:tell` can be used to control the playback position of the Source.  A
     Source can be set to loop when it reaches the end using `Source:setLooping`.
   ]],
-  constructor = 'lovr.audio.newSource'
+  constructors = {
+    'lovr.audio.newSource',
+    'Source:clone'
+  }
 }

api/lovr/audio/getDevices.lua

@@ -0,0 +1,47 @@
+return {
+  tag = 'devices',
+  summary = 'Get a list of audio devices.',
+  description = [[
+    Returns a list of playback or capture devices.  Each device has an `id`, `name`, and a `default`
+    flag indicating whether it's the default device.
+
+    To use a specific device id for playback or capture, pass it to `lovr.audio.setDevice`.
+  ]],
+  arguments = {
+    {
+      name = 'type',
+      type = 'AudioType',
+      default = [['playback']],
+      description = 'The type of devices to query (playback or capture).'
+    }
+  },
+  returns = {
+    {
+      name = 'devices',
+      type = 'table',
+      description = 'The list of devices.',
+      table = {
+        {
+          name = 'id',
+          type = 'userdata',
+          description = 'A unique, opaque id for the device.'
+        },
+        {
+          name = 'name',
+          type = 'string',
+          description = 'A human readable name for the device.'
+        },
+        {
+          name = 'default',
+          type = 'boolean',
+          description = 'Whether the device is the default audio device.'
+        }
+      }
+    }
+  },
+  related = {
+    'lovr.audio.setDevice',
+    'lovr.audio.start',
+    'lovr.audio.stop'
+  }
+}

api/lovr/audio/init.lua

@@ -18,7 +18,19 @@ return {
       description = [[
         The listener is a virtual object in 3D space that "hears" all the sounds that are playing.
         It can be positioned and oriented in 3D space, which controls how Sources in the world are
-        heard.
+        heard.  Usually this would be locked to the headset pose.
+      ]]
+    },
+    {
+      name = 'Devices',
+      tag = 'devices',
+      description = [[
+        It's possible to list the available audio devices on the system, and pick a specific device
+        to use for either playback or capture.  Devices can also be manually started and stopped.
+        Other useful features of `lovr.audio.setDevice` include the ability to stream all audio data
+        to a custom sink and the option to create a device in exclusive mode for higher performance.
+        By default, the default playback device is automatically initialized and started, but this
+        can be configured using `lovr.conf`.
       ]]
     }
   }

api/lovr/audio/isStarted.lua

@@ -0,0 +1,24 @@
+return {
+  tag = 'devices',
+  summary = 'Check if an audio device is started.',
+  description = 'Returns whether an audio device is started.',
+  arguments = {
+    {
+      name = 'type',
+      type = 'AudioType',
+      default = [['playback']],
+      description = 'The type of device to check.'
+    }
+  },
+  returns = {
+    {
+      name = 'started',
+      type = 'boolean',
+      description = 'Whether the device is active.'
+    }
+  },
+  related = {
+    'lovr.audio.start',
+    'lovr.audio.stop'
+  }
+}

api/lovr/audio/newSource.lua

@@ -35,5 +35,8 @@ return {
       arguments = { 'sound' },
       returns = { 'source' }
     }
+  },
+  related = {
+    'Source:clone'
   }
 }

api/lovr/audio/setDevice.lua

@@ -0,0 +1,64 @@
+return {
+  tag = 'devices',
+  summary = 'Switch audio devices.',
+  description = [[
+    Switches either the playback or capture device to a new one.
+
+    If a device for the given type is already active, it will be stopped and destroyed.  The new
+    device will not be started automatically, use `lovr.audio.start` to start it.
+
+    A device id (previously retrieved using `lovr.audio.getDevices`) can be given to use a specific
+    audio device, or `nil` can be used for the id to use the default audio device.
+
+    A sink can be also be provided when changing the device.  A sink is an audio stream (`Sound`
+    object with a `stream` type) that will receive all audio samples played (for playback) or all
+    audio samples captured (for capture).  When an audio device with a sink is started, be sure to
+    periodically call `Sound:read` on the sink to read audio samples from it, otherwise it will
+    overflow and discard old data.  The sink can have any format, data will be converted as needed.
+    Using a sink for the playback device will reduce performance, but this isn't the case for
+    capture devices.
+
+    Audio devices can be started in `shared` or `exclusive` mode.  Exclusive devices can have lower
+    latency than shared devices, but there's a higher chance that requesting exclusive access to an
+    audio device will fail (either because it isn't supported or not allowed).  You can first try to
+    use the device in exclusive mode, switching to shared mode if it doesn't work.
+  ]],
+  arguments = {
+    {
+      name = 'type',
+      type = 'AudioType',
+      default = [['playback']],
+      description = 'The type of devices to query (playback or capture).'
+    },
+    {
+      name = 'id',
+      type = 'userdata',
+      default = 'nil',
+      description = 'The id of the device to use, or `nil` to use the default device.'
+    },
+    {
+      name = 'sink',
+      type = 'Sound',
+      default = 'nil',
+      description = 'An optional audio stream to use as a sink for the device.'
+    },
+    {
+      name = 'mode',
+      type = 'AudioShareMode',
+      default = 'shared',
+      description = 'The sharing mode for the device (exclusive or shared).'
+    }
+  },
+  returns = {
+    {
+      name = 'success',
+      type = 'boolean',
+      description = 'Whether creating the audio device succeeded.'
+    }
+  },
+  related = {
+    'lovr.audio.getDevices',
+    'lovr.audio.start',
+    'lovr.audio.stop'
+  }
+}

api/lovr/audio/start.lua

@@ -0,0 +1,35 @@
+return {
+  tag = 'devices',
+  summary = 'Start an audio device.',
+  description = [[
+    Starts the active playback or capture device.  This may fail if:
+
+    - The device is already started
+    - No device was initialized with `lovr.audio.setDevice`
+    - Lack of `audiocapture` permission on Android (see `lovr.system.requestPermission`)
+    - Some other problem accessing the audio device
+  ]],
+  arguments = {
+    {
+      name = 'type',
+      type = 'AudioType',
+      default = [['playback']],
+      description = 'The type of device to start.'
+    }
+  },
+  returns = {
+    {
+      name = 'started',
+      type = 'boolean',
+      description = 'Whether the device was successfully started.'
+    }
+  },
+  related = {
+    'lovr.audio.getDevices',
+    'lovr.audio.setDevice',
+    'lovr.audio.stop',
+    'lovr.audio.isStarted',
+    'lovr.system.requestPermission',
+    'lovr.permission'
+  }
+}

api/lovr/audio/stop.lua

@@ -0,0 +1,32 @@
+return {
+  tag = 'devices',
+  summary = 'Stop an audio device.',
+  description = [[
+    Stops the active playback or capture device.  This may fail if:
+
+    - The device is not started
+    - No device was initialized with `lovr.audio.setDevice`
+  ]],
+  arguments = {
+    {
+      name = 'type',
+      type = 'AudioType',
+      default = [['playback']],
+      description = 'The type of device to stop.'
+    }
+  },
+  returns = {
+    {
+      name = 'stopped',
+      type = 'boolean',
+      description = 'Whether the device was successfully stopped.'
+    }
+  },
+  notes = 'Switching devices with `lovr.audio.setDevice` will stop the existing one.',
+  related = {
+    'lovr.audio.getDevices',
+    'lovr.audio.setDevice',
+    'lovr.audio.start',
+    'lovr.audio.isStarted'
+  }
+}

api/lovr/callbacks/conf.lua

@@ -206,6 +206,10 @@ return {
           -- Set the project identity
           t.identity = 'default'
 
+          -- Audio
+          t.audio.spatializer = nil
+          t.audio.start = true
+
           -- Graphics
           t.graphics.debug = false
 

api/lovr/data/SampleFormat.lua

@@ -0,0 +1,14 @@
+return {
+  summary = 'Different data types for samples in a Sound.',
+  description = 'Sounds can store audio samples as 16 bit integers or 32 bit floats.',
+  values = {
+    {
+      name = 'f32',
+      description = '32 bit floating point samples (between -1.0 and 1.0).'
+    },
+    {
+      name = 'i16',
+      description = '16 bit integer samples (between -32768 and 32767).'
+    }
+  }
+}

api/lovr/headset/getDisplayDimensions.lua

@@ -1,7 +1,7 @@
 return {
   tag = 'headset',
   summary = 'Get the dimensions of the headset display.',
-  description = 'Returns the dimensions of the headset display (for one eye), in pixels.',
+  description = 'Returns the texture dimensions of the headset display (for one eye), in pixels.',
   arguments = {},
   returns = {
     {

api/lovr/physics/Shape/setOrientation.lua

@@ -24,6 +24,7 @@ return {
     }
   },
   returns = {},
+  notes = 'If the Shape isn\'t attached to a Collider, this will error.',
   related = {
     'Shape:getPosition',
     'Shape:setPosition'

api/lovr/physics/Shape/setPosition.lua

@@ -18,6 +18,7 @@ return {
       description = 'The z offset.'
     }
   },
+  notes = 'If the Shape isn\'t attached to a Collider, this will error.',
   returns = {},
   related = {
     'Shape:getOrientation',