Audio docs;

api/init.lua

@@ -620,7 +620,7 @@ return {
           name = "getDopplerEffect",
           tag = "listener",
           summary = "Get the doppler effect parameters.",
-          description = "Returns the parameters that control the simulated doppler effect: The effect intensity and the speed of sound.",
+          description = "Returns the parameters that control the simulated doppler effect.",
           key = "lovr.audio.getDopplerEffect",
           module = "lovr.audio",
           variants = {
@@ -640,13 +640,13 @@ return {
               }
             }
           },
-          notes = "The default factor is 1 and the default speed of sound is 343.29."
+          notes = "The default factor is 1.0 and the default speed of sound is 343.29."
         },
         {
           name = "getMicrophoneNames",
           tag = "microphones",
-          summary = "Get a table containing the names of all connected microphones.",
-          description = "Returns a table containing the names of all microphones connected to the system.",
+          summary = "Get the names of all connected microphones.",
+          description = "Returns a table with the names of all microphones connected to the system.",
           key = "lovr.audio.getMicrophoneNames",
           module = "lovr.audio",
           related = {
@@ -689,6 +689,11 @@ return {
           description = "Returns the orientation of the virtual audio listener in angle/axis representation.",
           key = "lovr.audio.getOrientation",
           module = "lovr.audio",
+          related = {
+            "lovr.audio.getPosition",
+            "lovr.audio.getPose",
+            "Source:getOrientation"
+          },
           variants = {
             {
               arguments = {},
@@ -717,6 +722,61 @@ return {
             }
           }
         },
+        {
+          name = "getPose",
+          tag = "listener",
+          summary = "Get the pose of the listener.",
+          description = "Returns the position and orientation of the virtual audio listener.",
+          key = "lovr.audio.getPose",
+          module = "lovr.audio",
+          related = {
+            "lovr.audio.getPosition",
+            "lovr.audio.getOrientation",
+            "Source:getPose"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {
+                {
+                  name = "x",
+                  type = "number",
+                  description = "The x position of the listener, in meters."
+                },
+                {
+                  name = "y",
+                  type = "number",
+                  description = "The y position of the listener, in meters."
+                },
+                {
+                  name = "z",
+                  type = "number",
+                  description = "The z position of the listener, in meters."
+                },
+                {
+                  name = "angle",
+                  type = "number",
+                  description = "The number of radians the listener is rotated around its axis of rotation."
+                },
+                {
+                  name = "ax",
+                  type = "number",
+                  description = "The x component of the axis of rotation."
+                },
+                {
+                  name = "ay",
+                  type = "number",
+                  description = "The y component of the axis of rotation."
+                },
+                {
+                  name = "az",
+                  type = "number",
+                  description = "The z component of the axis of rotation."
+                }
+              }
+            }
+          }
+        },
         {
           name = "getPosition",
           tag = "listener",
@@ -803,7 +863,7 @@ return {
           name = "isSpatialized",
           tag = "listener",
           summary = "Check if audio is spatialized.",
-          description = "Returns whether or not audio is currently spatialized with HRTFs.  Spatialized audio is much more immersive.",
+          description = "Returns whether or not audio is currently spatialized with HRTFs.",
           key = "lovr.audio.isSpatialized",
           module = "lovr.audio",
           variants = {
@@ -823,7 +883,7 @@ return {
           name = "newMicrophone",
           tag = "microphones",
           summary = "Create a new Microphone.",
-          description = "Creates a new Microphone based on the name of an existing micrphone and a set of capture parameters.  If the specified parameters are not supported, `nil` will be returned.",
+          description = "Creates a new Microphone based on the name of an existing micrphone and a set of capture parameters.  If the specified combination of prameters are not supported for audio capture, `nil` will be returned.",
           key = "lovr.audio.newMicrophone",
           module = "lovr.audio",
           related = {
@@ -836,7 +896,8 @@ return {
                 {
                   name = "name",
                   type = "string",
-                  description = "The name of the microphone that this Microphone will record from."
+                  description = "The name of the microphone that this Microphone will record from, or `nil` to use the default microphone.",
+                  default = "nil"
                 },
                 {
                   name = "samples",
@@ -969,6 +1030,12 @@ return {
           description = "Pause all playing audio.",
           key = "lovr.audio.pause",
           module = "lovr.audio",
+          related = {
+            "Source:pause",
+            "lovr.audio.resume",
+            "lovr.audio.rewind",
+            "lovr.audio.stop"
+          },
           variants = {
             {
               arguments = {},
@@ -983,6 +1050,13 @@ return {
           description = "Resume all Sources.  Has no effect on Sources that are playing or stopped.",
           key = "lovr.audio.resume",
           module = "lovr.audio",
+          related = {
+            "Source:resume",
+            "Source:resume",
+            "lovr.audio.pause",
+            "lovr.audio.rewind",
+            "lovr.audio.stop"
+          },
           variants = {
             {
               arguments = {},
@@ -1003,6 +1077,12 @@ return {
               returns = {}
             }
           },
+          related = {
+            "Source:rewind",
+            "lovr.audio.pause",
+            "lovr.audio.resume",
+            "lovr.audio.stop"
+          },
           notes = "Sources that are paused will remain paused. Sources that are currently playing will restart from the beginning."
         },
         {
@@ -1031,7 +1111,7 @@ return {
               returns = {}
             }
           },
-          notes = "The default factor is 1 and the default speed of sound is 343.29."
+          notes = "The default factor is 1.0 and the default speed of sound is 343.29."
         },
         {
           name = "setOrientation",
@@ -1068,6 +1148,62 @@ return {
             }
           }
         },
+        {
+          name = "setPose",
+          tag = "listener",
+          summary = "Set the pose of the listener.",
+          description = "Sets the position and orientation of the virtual audio listener.",
+          key = "lovr.audio.setPose",
+          module = "lovr.audio",
+          variants = {
+            {
+              arguments = {
+                {
+                  name = "x",
+                  type = "number",
+                  description = "The x position of the listener, in meters."
+                },
+                {
+                  name = "y",
+                  type = "number",
+                  description = "The y position of the listener, in meters."
+                },
+                {
+                  name = "z",
+                  type = "number",
+                  description = "The z position of the listener, in meters."
+                },
+                {
+                  name = "angle",
+                  type = "number",
+                  description = "The number of radians the listener is rotated around its axis of rotation."
+                },
+                {
+                  name = "ax",
+                  type = "number",
+                  description = "The x component of the axis of rotation."
+                },
+                {
+                  name = "ay",
+                  type = "number",
+                  description = "The y component of the axis of rotation."
+                },
+                {
+                  name = "az",
+                  type = "number",
+                  description = "The z component of the axis of rotation."
+                }
+              },
+              returns = {}
+            }
+          },
+          related = {
+            "lovr.audio.setPosition",
+            "lovr.audio.setOrientation",
+            "Source:setPose"
+          },
+          notes = "The default implementation of `lovr.run` calls this function with the result of `lovr.headset.getPose`, so that the listener automatically tracks the headset."
+        },
         {
           name = "setPosition",
           tag = "listener",
@@ -1163,13 +1299,19 @@ return {
               returns = {}
             }
           },
+          related = {
+            "Source:stop",
+            "lovr.audio.pause",
+            "lovr.audio.resume",
+            "lovr.audio.rewind"
+          },
           notes = "If you want to resume the stopped audio later, see `lovr.audio.pause`."
         },
         {
           name = "update",
           tag = "sources",
           summary = "Updates the audio system.",
-          description = "Updates all playing sources. This must be called regularly for audio playback to occur. Normally this is called for you by `lovr.run`.",
+          description = "Updates all playing sources. This must be called regularly for audio playback to occur. This is called automatically by the default implementation of `lovr.run`.",
           key = "lovr.audio.update",
           module = "lovr.audio",
           variants = {

api/lovr/audio/Source/getBitDepth.lua

@@ -2,7 +2,7 @@ return {
   summary = 'Get the bit depth of the Source.',
   description = [[
     Returns the number of bits per sample in the Source.  This is a rough indicator of the
-    resolution of the Source, and is usually 16.
+    "resolution" or quality of the Source.  It's usually 16 or 32.
   ]],
   arguments = {},
   returns = {

api/lovr/audio/Source/getCone.lua

@@ -3,7 +3,7 @@ return {
   description = [[
     Returns the directional volume cone of the Source.  The cone is specified by three values:
     `innerAngle`, `outerAngle`, and `outerVolume`.  If the listener is inside the `innerAngle`, the
-    Source won't have its volume changed.  Otherwise, the volume will start to decrease, reaching a
+    Source won't have its volume reduced.  Otherwise, the volume will start to decrease, reaching a
     minimum volume of `outerVolume` once the listener is `outerAngle` degrees from the direction of
     the Source.
   ]],
@@ -32,6 +32,6 @@ return {
 
     The default `outerVolume` for a Source is `0`.
 
-    Make sure to set the direction of a Source before setting its cone.
+    `Source:setOrientation` can be used to change which way the cone points.
   ]]
 }

api/lovr/audio/Source/getOrientation.lua

@@ -0,0 +1,33 @@
+return {
+  summary = 'Get the orientation of the Source.',
+  description = 'Returns the orientation of the Source, in angle/axis representation.',
+  arguments = {},
+  returns = {
+    {
+      name = 'angle',
+      type = 'number',
+      description = 'The number of radians the Source is rotated around its axis of rotation.'
+    },
+    {
+      name = 'ax',
+      type = 'number',
+      description = 'The x component of the axis of rotation.'
+    },
+    {
+      name = 'ay',
+      type = 'number',
+      description = 'The y component of the axis of rotation.'
+    },
+    {
+      name = 'az',
+      type = 'number',
+      description = 'The z component of the axis of rotation.'
+    }
+  },
+  related = {
+    'Source:getPosition',
+    'Source:getPose',
+    'Source:getCone',
+    'lovr.audio.getOrientation'
+  }
+}

api/lovr/audio/Source/getPose.lua

@@ -0,0 +1,48 @@
+return {
+  summary = 'Get the pose of the Source.',
+  description = 'Returns the position and orientation of the Source.',
+  arguments = {},
+  returns = {
+    {
+      name = 'x',
+      type = 'number',
+      description = 'The x position of the Source, in meters.'
+    },
+    {
+      name = 'y',
+      type = 'number',
+      description = 'The y position of the Source, in meters.'
+    },
+    {
+      name = 'z',
+      type = 'number',
+      description = 'The z position of the Source, in meters.'
+    },
+    {
+      name = 'angle',
+      type = 'number',
+      description = 'The number of radians the Source is rotated around its axis of rotation.'
+    },
+    {
+      name = 'ax',
+      type = 'number',
+      description = 'The x component of the axis of rotation.'
+    },
+    {
+      name = 'ay',
+      type = 'number',
+      description = 'The y component of the axis of rotation.'
+    },
+    {
+      name = 'az',
+      type = 'number',
+      description = 'The z component of the axis of rotation.'
+    }
+  },
+  related = {
+    'Source:getPosition',
+    'Source:getOrientation',
+    'Source:getCone',
+    'lovr.audio.getPose'
+  }
+}

api/lovr/audio/Source/getPosition.lua

@@ -21,5 +21,11 @@ return {
       type = 'number',
       description = 'The z coordinate.'
     }
+  },
+  related = {
+    'Source:getOrientation',
+    'Source:getPose',
+    'Source:getCone',
+    'lovr.audio.getPosition'
   }
 }

api/lovr/audio/Source/isLooping.lua

@@ -1,8 +1,6 @@
 return {
   summary = 'Check if the Source is looping.',
-  description = [[
-    Returns whether or not the Source will loop when it finishes.
-  ]],
+  description = 'Returns whether or not the Source will loop when it finishes.',
   arguments = {},
   returns = {
     {

api/lovr/audio/Source/isRelative.lua

@@ -2,7 +2,8 @@ return {
   summary = 'Check if the Source is relative to the listener.',
   description = [[
     Returns whether or not the Source is relative to the listener.  If a Source is relative then its
-    position, velocity, cone, and direction are all relative to the audio listener.
+    position, velocity, cone, and orientation are all treated as relative to the audio listener,
+    instead of absolute positions in space.
   ]],
   arguments = {},
   returns = {

api/lovr/audio/Source/play.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'Play the Source.',
-  description = 'Plays the Source.  This has no effect if the Source is already playing.',
+  description = 'Plays the Source.  This doesn\'t do anything if the Source is already playing.',
   arguments = {},
   returns = {}
 }

api/lovr/audio/Source/setCone.lua

@@ -32,6 +32,6 @@ return {
 
     The default `outerVolume` for a Source is `0`.
 
-    Make sure to set the direction of a Source before setting its cone.
+    The direction of the cone can be changed using `Source:setOrientation`.
   ]]
 }

api/lovr/audio/Source/setFalloff.lua

@@ -2,6 +2,9 @@ return {
   summary = 'Set the falloff parameters for the Source.',
   description = [[
     Sets parameters that control how the volume of the Source falls of with distance.
+
+    Only mono sources support positional falloff.  Using this function on a stereo Source will cause
+    an error.
   ]],
   arguments = {
     {

api/lovr/audio/Source/setOrientation.lua

@@ -0,0 +1,33 @@
+return {
+  summary = 'Set the orientation of the Source.',
+  description = 'Sets the orientation of the Source in angle/axis representation.',
+  arguments = {
+    {
+      name = 'angle',
+      type = 'number',
+      description = 'The number of radians the Source should be rotated around its rotation axis.'
+    },
+    {
+      name = 'ax',
+      type = 'number',
+      description = 'The x component of the axis of rotation.'
+    },
+    {
+      name = 'ay',
+      type = 'number',
+      description = 'The y component of the axis of rotation.'
+    },
+    {
+      name = 'az',
+      type = 'number',
+      description = 'The z component of the axis of rotation.'
+    }
+  },
+  returns = {},
+  related = {
+    'Source:setPosition',
+    'Source:setPose',
+    'Source:setCone',
+    'lovr.audio.setOrientation'
+  }
+}

api/lovr/audio/Source/setPose.lua

@@ -0,0 +1,47 @@
+return {
+  summary = 'Set the pose of the Source.',
+  description = 'Sets the position and orientation of the Source.',
+  arguments = {
+    {
+      name = 'x',
+      type = 'number',
+      description = 'The x position of the Source, in meters.'
+    },
+    {
+      name = 'y',
+      type = 'number',
+      description = 'The y position of the Source, in meters.'
+    },
+    {
+      name = 'z',
+      type = 'number',
+      description = 'The z position of the Source, in meters.'
+    },
+    {
+      name = 'angle',
+      type = 'number',
+      description = 'The number of radians the Source is rotated around its axis of rotation.'
+    },
+    {
+      name = 'ax',
+      type = 'number',
+      description = 'The x component of the axis of rotation.'
+    },
+    {
+      name = 'ay',
+      type = 'number',
+      description = 'The y component of the axis of rotation.'
+    },
+    {
+      name = 'az',
+      type = 'number',
+      description = 'The z component of the axis of rotation.'
+    }
+  },
+  returns = {},
+  related = {
+    'Source:setPosition',
+    'Source:setOrientation',
+    'lovr.audio.setPose'
+  }
+}

api/lovr/audio/Source/setPosition.lua

@@ -4,7 +4,8 @@ return {
     Sets the position of the Source, in meters.  Setting the position will cause the Source to be
     distorted and attenuated based on its position relative to the listener.
 
-    Only mono sources can be positioned.
+    Only mono sources can be positioned.  Setting the position of a stereo Source will cause an
+    error.
   ]],
   arguments = {
     {

api/lovr/audio/Source/setRelative.lua

@@ -2,13 +2,13 @@ return {
   summary = 'Set whether or not the Source is relative.',
   description = [[
     Sets whether or not the Source is relative to the listener.  If a Source is relative then its
-    position, velocity, cone, and direction are all relative to the audio listener.
+    position, velocity, cone, and orientation are all treated as relative to the audio listener.
   ]],
   arguments = {
     {
       name = 'relative',
       type = 'boolean',
-      description = 'Whether or not the Source is relative.'
+      description = 'Whether or not the Source should be relative.'
     }
   },
   returns = {}

api/lovr/audio/Source/stop.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'Stop the Source.',
-  description = 'Stops the source.',
+  description = 'Stops the source, also rewinding it to the beginning.',
   arguments = {},
   returns = {}
 }