MOAR;

api/init.lua

@@ -2504,7 +2504,7 @@ return {
         {
           name = "newSound",
           summary = "Create a new Sound.",
-          description = "Creates a new Sound.",
+          description = "Creates a new Sound.  A sound can be loaded from an audio file, or it can be created empty with capacity for a certain number of audio frames.\n\nWhen loading audio from a file, use the `decode` option to control whether compressed audio should remain compressed or immediately get decoded to raw samples.\n\nWhen creating an empty sound, the `contents` parameter can be set to `'stream'` to create an audio stream.  On streams, `Sound:setFrames` will always write to the end of the stream, and `Sound:getFrames` will always read the oldest samples from the beginning.  The number of frames in the sound is the total capacity of the stream's buffer.",
           key = "lovr.data.newSound",
           module = "lovr.data",
           notes = "It is highly recommended to use an audio format that matches the format of the audio module: `f32` sample formats at a sample rate of 48000, with 1 channel for spatialized sources or 2 channels for unspatialized sources.  This will avoid the need to convert audio during playback, which boosts performance of the audio thread.\n\nThe WAV importer supports 16, 24, and 32 bit integer data and 32 bit floating point data.  The data must be mono, stereo, or 4-channel full-sphere ambisonic.  The `WAVE_FORMAT_EXTENSIBLE` extension is supported.\n\nAmbisonic channel layouts are supported for import (but not yet for playback).  Ambisonic data can be loaded from WAV files.  It must be first-order full-sphere ambisonic data with 4 channels.  If the WAV has a `WAVE_FORMAT_EXTENSIBLE` chunk with an `AMBISONIC_B_FORMAT` format GUID, then the data is understood as using the AMB format with Furse-Malham channel ordering and normalization.  *All other* 4-channel files are assumed to be using the AmbiX format with ACN channel ordering and SN3D normalization.  AMB files will get automatically converted to AmbiX on import, so ambisonic Sounds will always be in a consistent format.\n\nOGG and MP3 files will always have the `f32` format when loaded.",

api/lovr/data/newSound.lua

@@ -1,6 +1,17 @@
 return {
   summary = 'Create a new Sound.',
-  description = 'Creates a new Sound.',
+  description = [[
+    Creates a new Sound.  A sound can be loaded from an audio file, or it can be created empty with
+    capacity for a certain number of audio frames.
+
+    When loading audio from a file, use the `decode` option to control whether compressed audio
+    should remain compressed or immediately get decoded to raw samples.
+
+    When creating an empty sound, the `contents` parameter can be set to `'stream'` to create an
+    audio stream.  On streams, `Sound:setFrames` will always write to the end of the stream, and
+    `Sound:getFrames` will always read the oldest samples from the beginning.  The number of frames
+    in the sound is the total capacity of the stream's buffer.
+  ]],
   arguments = {
     frames = {
       type = 'number',