MOAR;

api/lovr/audio/AudioMaterial.lua

@@ -0,0 +1,50 @@
+return {
+  summary = 'Different types of audio materials.',
+  description = 'Different types of audio material presets, for use with `lovr.audio.setGeometry`.',
+  values = {
+    {
+      name = 'generic',
+      description = 'Generic default audio material.'
+    },
+    {
+      name = 'brick',
+      description = 'Brick.'
+    },
+    {
+      name = 'carpet',
+      description = 'Carpet.'
+    },
+    {
+      name = 'ceramic',
+      description = 'Ceramic.'
+    },
+    {
+      name = 'concrete',
+      description = 'Concrete.'
+    },
+    {
+      name = 'glass',
+      descripion = 'Glass.'
+    },
+    {
+      name = 'gravel',
+      descripion = 'Gravel.'
+    },
+    {
+      name = 'metal',
+      descripion = 'Metal.'
+    },
+    {
+      name = 'plaster',
+      descripion = 'Plaster.'
+    },
+    {
+      name = 'rock',
+      descripion = 'Rock.'
+    },
+    {
+      name = 'wood',
+      descripion = 'Wood.'
+    }
+  }
+}

api/lovr/audio/Effect.lua

@@ -0,0 +1,30 @@
+return {
+  summary = 'Different types of Source effects.',
+  description = 'Different types of effects that can be applied with `Source:setEffectEnabled`.',
+  values = {
+    {
+      name = 'absorption',
+      description = 'Models absorption as sound travels through the air, water, etc.'
+    },
+    {
+      name = 'falloff',
+      description = 'Decreases audio volume with distance (1 / max(distance, 1)).'
+    },
+    {
+      name = 'occlusion',
+      description = 'Causes audio to drop off when the Source is occluded by geometry.'
+    },
+    {
+      name = 'reverb',
+      description = 'Models reverb caused by audio bouncing off of geometry.'
+    },
+    {
+      name = 'spatialization',
+      description = 'Spatializes the Source using either simple panning or an HRTF.'
+    },
+    {
+      name = 'transmission',
+      descripion = 'Causes audio to be heard through walls when occluded, based on audio materials.'
+    }
+  }
+}

api/lovr/audio/Source/getRadius.lua

@@ -0,0 +1,19 @@
+return {
+  summary = 'Get the radius of the Source.',
+  description = [[
+    Returns the radius of the Source, in meters.
+
+    This does not control falloff or attenuation.  It is only used for smoothing out occlusion.  If
+    a Source doesn't have a radius, then when it becomes occluded by a wall its volume will
+    instantly drop.  Giving the Source a radius that approximates its emitter's size will result in
+    a smooth transition between audible and occluded, improving realism.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'radius',
+      type = 'number',
+      description = 'The radius of the Source, in meters.'
+    }
+  }
+}

api/lovr/audio/Source/getVolume.lua

@@ -1,9 +1,14 @@
 return {
   summary = 'Get the volume of the Source.',
-  description = [[
-    Returns the current volume factor for the Source.  1.0 is the default and the maximum.
-  ]],
-  arguments = {},
+  description = 'Returns the current volume factor for the Source.',
+  arguments = {
+    {
+      name = 'units',
+      type = 'VolumeUnit',
+      default = [['linear']],
+      description = 'The units to return (linear or db).'
+    }
+  },
   returns = {
     {
       name = 'volume',

api/lovr/audio/Source/setRadius.lua

@@ -0,0 +1,19 @@
+return {
+  summary = 'Set the radius of the Source.',
+  description = [[
+    Sets the radius of the Source, in meters.
+
+    This does not control falloff or attenuation.  It is only used for smoothing out occlusion.  If
+    a Source doesn't have a radius, then when it becomes occluded by a wall its volume will
+    instantly drop.  Giving the Source a radius that approximates its emitter's size will result in
+    a smooth transition between audible and occluded, improving realism.
+  ]],
+  arguments = {
+    {
+      name = 'radius',
+      type = 'number',
+      description = 'The new radius of the Source, in meters.'
+    }
+  },
+  returns = {}
+}

api/lovr/audio/Source/setVolume.lua

@@ -1,14 +1,19 @@
 return {
   summary = 'Set the volume of the Source.',
-  description = [[
-    Sets the current volume factor for the Source.  1.0 is the default and the maximum.
-  ]],
+  description = 'Sets the current volume factor for the Source.',
   arguments = {
     {
       name = 'volume',
       type = 'number',
       description = 'The new volume.'
+    },
+    {
+      name = 'units',
+      type = 'VolumeUnit',
+      default = [['linear']],
+      description = 'The units of the value.'
     }
   },
-  returns = {}
+  returns = {},
+  notes = 'The volume will be clamped to a 0-1 range (0 dB).'
 }

api/lovr/audio/VolumeUnit.lua

@@ -0,0 +1,17 @@
+return {
+  summary = 'Different units of volume.',
+  description = [[
+    When accessing the volume of Sources or the audio listener, this can be done in linear units
+    with a 0 to 1 range, or in decibels with a range of -∞ to 0.
+  ]],
+  values = {
+    {
+      name = 'linear',
+      description = 'Linear volume range.'
+    },
+    {
+      name = 'db',
+      description = 'Decibels.'
+    }
+  }
+}

api/lovr/audio/getAbsorption.lua

@@ -0,0 +1,36 @@
+return {
+  summary = 'Get the absorption coefficients.',
+  description = [[
+    Returns the global air absorption coefficients for the medium.  This affects Sources that have
+    the `absorption` effect enabled, causing audio volume to drop off with distance as it is
+    absorbed by the medium it's traveling through (air, water, etc.).  The difference between
+    absorption and falloff is that absorption is more subtle and is frequency-dependent, so
+    higher-frequency bands can get absorbed more quickly than lower ones.  This can be used to apply
+    "underwater" effects and stuff.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'low',
+      type = 'number',
+      description = 'The absorption coefficient for the low frequency band.'
+    },
+    {
+      name = 'mid',
+      type = 'number',
+      description = 'The absorption coefficient for the mid frequency band.'
+    },
+    {
+      name = 'high',
+      type = 'number',
+      description = 'The absorption coefficient for the high frequency band.'
+    }
+  },
+  notes = [[
+    Absorption is currently only supported by the phonon spatializer.
+
+    The frequency bands correspond to `400Hz`, `2.5KHz`, and `15KHz`.
+
+    The default coefficients are `.0002`, `.0017`, and `.0182` for low, mid, and high.
+  ]]
+}

api/lovr/audio/getVolume.lua

@@ -2,9 +2,17 @@ return {
   tag = 'listener',
   summary = 'Get the master volume.',
   description = [[
-    Returns the master volume.  All Source objects have their volume multiplied by this factor.
+    Returns the master volume.  All audio sent to the playback device has its volume multiplied by
+    this factor.
   ]],
-  arguments = {},
+  arguments = {
+    {
+      name = 'units',
+      type = 'VolumeUnit',
+      default = [['linear']],
+      description = 'The units to return (linear or db).'
+    }
+  },
   returns = {
     {
       name = 'volume',
@@ -12,5 +20,5 @@ return {
       description = 'The master volume.'
     }
   },
-  notes = 'The default is 1.0.'
+  notes = 'The default volume is 1.0 (0 dB).'
 }

api/lovr/audio/setAbsorption.lua

@@ -0,0 +1,36 @@
+return {
+  summary = 'Set the absorption coefficients.',
+  description = [[
+    Sets the global air absorption coefficients for the medium.  This affects Sources that have the
+    `absorption` effect enabled, causing audio volume to drop off with distance as it is absorbed by
+    the medium it's traveling through (air, water, etc.).  The difference between absorption and
+    falloff is that absorption is more subtle and is frequency-dependent, so higher-frequency bands
+    can get absorbed more quickly than lower ones.  This can be used to apply "underwater" effects
+    and stuff.
+  ]],
+  arguments = {
+    {
+      name = 'low',
+      type = 'number',
+      description = 'The absorption coefficient for the low frequency band.'
+    },
+    {
+      name = 'mid',
+      type = 'number',
+      description = 'The absorption coefficient for the mid frequency band.'
+    },
+    {
+      name = 'high',
+      type = 'number',
+      description = 'The absorption coefficient for the high frequency band.'
+    }
+  },
+  returns = {},
+  notes = [[
+    Absorption is currently only supported by the phonon spatializer.
+
+    The frequency bands correspond to `400Hz`, `2.5KHz`, and `15KHz`.
+
+    The default coefficients are `.0002`, `.0017`, and `.0182` for low, mid, and high.
+  ]]
+}

api/lovr/audio/setVolume.lua

@@ -2,15 +2,22 @@ return {
   tag = 'listener',
   summary = 'Set the master volume.',
   description = [[
-    Sets the master volume.  The volume of all Sources will be multiplied by this factor.
+    Sets the master volume.  All audio sent to the playback device has its volume multiplied by this
+    factor.
   ]],
-  arguments = {},
-  returns = {
+  arguments = {
     {
       name = 'volume',
       type = 'number',
       description = 'The master volume.'
+    },
+    {
+      name = 'units',
+      type = 'VolumeUnit',
+      default = [['linear']],
+      description = 'The units of the value.'
     }
   },
-  notes = 'The default is 1.0.'
+  returns = {},
+  notes = 'The volume will be clamped to a 0-1 range (0 dB).'
 }