Sound:getFrames;

api/init.lua

@@ -3569,6 +3569,150 @@ return {
               },
               notes = "For streams, this returns the number of frames in the stream's buffer."
             },
+            {
+              name = "getFrames",
+              summary = "Read frames from the Sound.",
+              description = "Reads frames from the Sound into a table, Blob, or another Sound.",
+              key = "Sound:getFrames",
+              module = "lovr.data",
+              variants = {
+                {
+                  arguments = {
+                    {
+                      name = "count",
+                      type = "number",
+                      description = "The number of frames to read.  If nil, reads as many frames as possible.\n\nCompressed sounds will automatically be decoded.\n\nReading from a stream will ignore the source offset and read the oldest frames.",
+                      default = "nil"
+                    },
+                    {
+                      name = "srcOffset",
+                      type = "number",
+                      description = "A frame offset to apply to the sound when reading frames.",
+                      default = "0"
+                    }
+                  },
+                  returns = {
+                    {
+                      name = "t",
+                      type = "table",
+                      description = "A table containing audio frames."
+                    },
+                    {
+                      name = "count",
+                      type = "number",
+                      description = "The number of frames read."
+                    }
+                  }
+                },
+                {
+                  arguments = {
+                    {
+                      name = "t",
+                      type = "table",
+                      description = "An existing table to read frames into."
+                    },
+                    {
+                      name = "count",
+                      type = "number",
+                      description = "The number of frames to read.  If nil, reads as many frames as possible.\n\nCompressed sounds will automatically be decoded.\n\nReading from a stream will ignore the source offset and read the oldest frames.",
+                      default = "nil"
+                    },
+                    {
+                      name = "srcOffset",
+                      type = "number",
+                      description = "A frame offset to apply to the sound when reading frames.",
+                      default = "0"
+                    },
+                    {
+                      name = "dstOffset",
+                      type = "number",
+                      description = "An offset to apply to the destination when writing frames (indices for tables, bytes for Blobs, frames for Sounds).",
+                      default = "0"
+                    }
+                  },
+                  returns = {
+                    {
+                      name = "t",
+                      type = "table",
+                      description = "A table containing audio frames."
+                    },
+                    {
+                      name = "count",
+                      type = "number",
+                      description = "The number of frames read."
+                    }
+                  }
+                },
+                {
+                  arguments = {
+                    {
+                      name = "blob",
+                      type = "Blob",
+                      description = "A Blob to read frames into."
+                    },
+                    {
+                      name = "count",
+                      type = "number",
+                      description = "The number of frames to read.  If nil, reads as many frames as possible.\n\nCompressed sounds will automatically be decoded.\n\nReading from a stream will ignore the source offset and read the oldest frames.",
+                      default = "nil"
+                    },
+                    {
+                      name = "srcOffset",
+                      type = "number",
+                      description = "A frame offset to apply to the sound when reading frames.",
+                      default = "0"
+                    },
+                    {
+                      name = "dstOffset",
+                      type = "number",
+                      description = "An offset to apply to the destination when writing frames (indices for tables, bytes for Blobs, frames for Sounds).",
+                      default = "0"
+                    }
+                  },
+                  returns = {
+                    {
+                      name = "count",
+                      type = "number",
+                      description = "The number of frames read."
+                    }
+                  }
+                },
+                {
+                  arguments = {
+                    {
+                      name = "sound",
+                      type = "Sound",
+                      description = "Another Sound to copy frames into ."
+                    },
+                    {
+                      name = "count",
+                      type = "number",
+                      description = "The number of frames to read.  If nil, reads as many frames as possible.\n\nCompressed sounds will automatically be decoded.\n\nReading from a stream will ignore the source offset and read the oldest frames.",
+                      default = "nil"
+                    },
+                    {
+                      name = "srcOffset",
+                      type = "number",
+                      description = "A frame offset to apply to the sound when reading frames.",
+                      default = "0"
+                    },
+                    {
+                      name = "dstOffset",
+                      type = "number",
+                      description = "An offset to apply to the destination when writing frames (indices for tables, bytes for Blobs, frames for Sounds).",
+                      default = "0"
+                    }
+                  },
+                  returns = {
+                    {
+                      name = "count",
+                      type = "number",
+                      description = "The number of frames read."
+                    }
+                  }
+                }
+              }
+            },
             {
               name = "getSampleCount",
               summary = "Get the number of samples in the Sound.",

api/lovr/data/Sound/getFrames.lua

@@ -0,0 +1,70 @@
+return {
+  summary = 'Read frames from the Sound.',
+  description = 'Reads frames from the Sound into a table, Blob, or another Sound.',
+  arguments = {
+    t = {
+      type = 'table',
+      description = 'An existing table to read frames into.'
+    },
+    blob = {
+      type = 'Blob',
+      description = 'A Blob to read frames into.'
+    },
+    sound = {
+      type = 'Sound',
+      description = 'Another Sound to copy frames into .'
+    },
+    count = {
+      type = 'number',
+      default = 'nil',
+      description = [[
+        The number of frames to read.  If nil, reads as many frames as possible.
+
+        Compressed sounds will automatically be decoded.
+
+        Reading from a stream will ignore the source offset and read the oldest frames.
+      ]]
+    },
+    srcOffset = {
+      type = 'number',
+      default = '0',
+      description = 'A frame offset to apply to the sound when reading frames.'
+    },
+    dstOffset = {
+      type = 'number',
+      default = '0',
+      description = [[
+        An offset to apply to the destination when writing frames (indices for tables, bytes for
+        Blobs, frames for Sounds).
+      ]]
+    }
+  },
+  returns = {
+    t = {
+      type = 'table',
+      description = 'A table containing audio frames.'
+    },
+    count = {
+      type = 'number',
+      description = 'The number of frames read.'
+    }
+  },
+  variants = {
+    {
+      arguments = { 'count', 'srcOffset' },
+      returns = { 't', 'count' }
+    },
+    {
+      arguments = { 't', 'count', 'srcOffset', 'dstOffset' },
+      returns = { 't', 'count' }
+    },
+    {
+      arguments = { 'blob', 'count', 'srcOffset', 'dstOffset' },
+      returns = { 'count' }
+    },
+    {
+      arguments = { 'sound', 'count', 'srcOffset', 'dstOffset' },
+      returns = { 'count' }
+    }
+  }
+}