Merge pull request #200 from aaronfranke/KHR_audio_tweaks_2

Sync up KHR_audio schemas with recent prose changes

extensions/2.0/KHR_audio/README.md

@@ -134,7 +134,7 @@ The extension must be added to the file's `extensionsUsed` array and because it
 
 ### Audio Data
 
-Audio data objects define where audio data is located. Data is either accessed via a bufferView or uri.
+Audio data objects define where audio data is located and what format the data is in. The data is either accessed via a bufferView or uri.
 
 When storing audio data in a buffer view, the `mimeType` field must be specified. The base specification supports `audio/mpeg` and `audio/wav` MIME types. These were chosen with consideration for the wide support for these types acrosss 3D engines and common use cases. Other supported audio formats may be added via extensions.
 
@@ -154,7 +154,7 @@ The uri of the audio file. Relative paths are relative to the .gltf file.
 
 ### Audio Sources
 
-Audio sources define the playing state for a given audio data. They connect one audio data to zero to many audio emitters.
+Audio sources reference audio data and define playback properties for it. Audio sources may be used by zero to many audio emitters.
 
 #### Property Summary
 
@@ -201,7 +201,7 @@ Audio emitters define how audio sources are played back. Emitter properties are
 Specifies the audio emitter type. This property is required.
 
 - `global` Global audio emitters are not affected by the position of audio listeners. All `positional` properties may not be defined on global audio emitters.
-- `positional` Positional audio emitters. The properties are defined in the `positional` object. Using sound cones, the orientation is `-Z` having the same emission direction as [`KHR_lights_punctual`](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_lights_punctual) and [glTF cameras](https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_016_Cameras.md).
+- `positional` Positional audio emitters play audio at a position in the scene. The properties are defined in the `positional` object. Using sound cones, the orientation is `-Z` having the same emission direction as [`KHR_lights_punctual`](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_lights_punctual) and [glTF cameras](https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_016_Cameras.md).
 
 #### `gain`
 
@@ -243,7 +243,7 @@ The angle, in radians, of a cone outside of which the volume will be reduced to
 
 #### `coneOuterGain`
 
-The gain of the audio emitter set when outside the cone defined by the `coneOuterAngle` property. It is a linear value (not dB). If not specified, the cone outer gain is `0.0`, meaning the audio will be silent outside of the cone.
+The linear volume gain of the audio emitter set when outside the cone defined by the `coneOuterAngle` property. It is a linear value (not dB). If not specified, the cone outer gain is `0.0`, meaning the audio will be silent outside of the cone.
 
 #### `distanceModel`
 

extensions/2.0/KHR_audio/schema/audio.schema.json

@@ -2,7 +2,7 @@
     "$schema": "http://json-schema.org/draft-04/schema",
     "title": "KHR_audio Audio Data",
     "type": "object",
-    "description": "A source for audio data referenced in Audio Emitters Audio can be referenced by URI or `bufferView` index. `mimeType` is required when `bufferView` is used.",
+    "description": "Audio data objects define where audio data is located and what format the data is in. The data is either accessed via a bufferView or uri. `mimeType` is required when `bufferView` is used.",
     "allOf": [{ "$ref": "glTFProperty.schema.json" }],
     "properties": {
         "uri": {
@@ -14,11 +14,14 @@
         },
         "mimeType": {
             "type": "string",
-            "description": "The audio's MIME type. Required if `bufferView` is defined. Unless specified by another extension, the only supported mimeType is `audio/mpeg`.",
+            "description": "The audio's MIME type. Required if `bufferView` is defined. Unless specified by another extension, the only supported mimeTypes are `audio/mpeg` and `audio/wav`.",
             "anyOf": [
                 {
                     "enum": ["audio/mpeg"]
                 },
+                {
+                    "enum": ["audio/wav"]
+                },
                 {
                     "type": "string"
                 }

extensions/2.0/KHR_audio/schema/emitter.positional.schema.json

@@ -6,24 +6,23 @@
     "allOf": [{ "$ref": "glTFProperty.schema.json" }],
     "properties": {
         "coneInnerAngle": {
-            "description": "The angle, in radians, of a cone inside of which there will be no volume reduction.",
+            "description": "The angle, in radians, of a cone inside of which there will be no volume reduction. This angle represents the angular diameter of the cone, from side to side. If not specified, the angle of Tau radians (360 degrees) is used, which means the audio emits in all directions (not in a cone).",
             "type": "number",
             "minimum": 0.0,
-            "maximum": 6.283185307179586,
-            "default": 6.283185307179586
+            "maximum": 6.2831853071795864,
+            "default": 6.2831853071795864
         },
         "coneOuterAngle": {
-            "description": "The angle, in radians, of a cone outside of which the volume will be reduced to a constant value of`coneOuterGain`.",
+            "description": "The angle, in radians, of a cone outside of which the volume will be reduced to a constant value of `coneOuterGain`. This angle represents the angular diameter of the cone, from side to side. If not specified, the angle of Tau radians (360 degrees) is used, which means some audio will emit in all directions.",
             "type": "number",
             "minimum": 0.0,
-            "maximum": 6.283185307179586,
-            "default": 6.283185307179586
+            "maximum": 6.2831853071795864,
+            "default": 6.2831853071795864
         },
         "coneOuterGain": {
-            "description": "The gain of the audio emitter set when outside the cone defined by the `coneOuterAngle` property. It is a linear value (not dB).",
+            "description": "The linear volume gain of the audio emitter set when outside the cone defined by the `coneOuterAngle` property. It is a linear value (not dB). If not specified, the cone outer gain is `0.0`, meaning the audio will be silent outside of the cone.",
             "type": "number",
             "minimum": 0.0,
-            "maximum": 1.0,
             "default": 0.0
         },
         "distanceModel": {
@@ -46,21 +45,21 @@
             "default": "inverse"
         },
         "maxDistance": {
-            "description": "The maximum distance between the emitter and listener, after which the volume will not be reduced any further. `maximumDistance` may only be applied when the distanceModel is set to linear. Otherwise, it should be ignored.",
+            "description": "The maximum distance between the emitter and listener, after which the volume will not be reduced any further. If zero or not specified, the audio emitter does not have a maximum distance, and it can be heard from any distance.",
             "type": "number",
             "minimum": 0.0,
-            "exclusiveMinimum": true,
-            "default": 10000.0
+            "default": 0.0
         },
         "refDistance": {
-            "description": "A reference distance for reducing volume as the emitter moves further from the listener. For distances less than this, the volume is not reduced.",
+            "description": "A reference distance for reducing volume as the emitter moves further from the listener. For distances less than this, the volume is not reduced. This value cannot be zero or a negative number. If not specified, the default value is `1.0`.",
             "type": "number",
             "minimum": 0.0,
+            "exclusiveMinimum": true,
             "default": 1.0
         },
         "rolloffFactor": {
             "type": "number",
-            "description": "Describes how quickly the volume is reduced as the emitter moves away from listener. When distanceModel is set to linear, the maximum value is 1 otherwise there is no upper limit.",
+            "description": "Describes how quickly the volume is reduced as the emitter moves away from listener. When distanceModel is set to linear, the maximum value is 1. Otherwise, there is no upper limit to the rolloff factor. If not specified, the default value is `1.0`.",
             "minimum": 0.0,
             "default": 1.0
         },

extensions/2.0/KHR_audio/schema/emitter.schema.json

@@ -2,20 +2,20 @@
     "$schema": "http://json-schema.org/draft-04/schema",
     "title": "KHR_audio Audio Emitter",
     "type": "object",
-    "description": "A positional or global audio emitter.",
+    "description": "Audio emitters define how audio sources are played back. Emitter properties are defined at the document level and are references by nodes. Audio may be played globally or positionally. Positional audio has further properties that define how audio volume scales with distance and angle.",
     "allOf": [{ "$ref": "glTFProperty.schema.json" }],
     "properties": {
         "type": {
             "type": "string",
             "description": "Specifies the audio emitter type.",
             "anyOf": [
                 {
-                    "enum": ["positional"],
-                    "description": "Positional audio emitters."
+                    "enum": ["global"],
+                    "description": "Global audio emitters are not affected by the position of audio listeners. All `positional` properties may not be defined on global audio emitters."
                 },
                 {
-                    "enum": ["global"],
-                    "description": "Global audio emitters are not affected by the position of audio listeners."
+                    "enum": ["positional"],
+                    "description": "Positional audio emitters play audio at a position in the scene. The properties are defined in the `positional` object."
                 },
                 {
                     "type": "string"

extensions/2.0/KHR_audio/schema/node.KHR_audio.schema.json

@@ -1,19 +1,19 @@
 {
-	"$schema": "http://json-schema.org/draft-04/schema",
-	"title": "KHR_audio glTF Node Extension",
-	"type": "object",
-	"allOf": [{ "$ref": "glTFProperty.schema.json" }],
-	"properties": {
-		"emitter": {
-			"description": "The id of the positional audio emitter referenced by this node.",
-			"allOf": [
-				{
-					"$ref": "glTFid.schema.json"
-				}
-			]
-		},
-		"extensions": {},
-		"extras": {}
-	},
-	"required": ["emitter"]
+    "$schema": "http://json-schema.org/draft-04/schema",
+    "title": "KHR_audio glTF Node Extension",
+    "type": "object",
+    "allOf": [{ "$ref": "glTFProperty.schema.json" }],
+    "properties": {
+        "emitter": {
+            "description": "The id of the positional audio emitter referenced by this node.",
+            "allOf": [
+                {
+                    "$ref": "glTFid.schema.json"
+                }
+            ]
+        },
+        "extensions": {},
+        "extras": {}
+    },
+    "required": ["emitter"]
 }

extensions/2.0/KHR_audio/schema/source.schema.json

@@ -2,7 +2,7 @@
     "$schema": "http://json-schema.org/draft-04/schema",
     "title": "KHR_audio Audio Source",
     "type": "object",
-    "description": "A source audio clip with defined properties about the behavior of that audio.",
+    "description": "Audio sources reference audio data and define playback properties for it. Audio sources may be used by zero to many audio emitters.",
     "allOf": [{ "$ref": "glTFProperty.schema.json" }],
     "properties": {
         "autoPlay": {