From 53b1b0f2b39b52326acbc5e737322233205c12ec Mon Sep 17 00:00:00 2001 From: Aaron Franke Date: Wed, 17 Jul 2024 10:33:34 -0700 Subject: [PATCH] Add "shapeType" property to positional audio emitters --- extensions/2.0/KHR_audio_emitter/README.md | 83 ++++++++++--------- ...dio_emitter.emitter.positional.schema.json | 18 ++++ 2 files changed, 62 insertions(+), 39 deletions(-) diff --git a/extensions/2.0/KHR_audio_emitter/README.md b/extensions/2.0/KHR_audio_emitter/README.md index 5b7d9dc..ee5e2dd 100644 --- a/extensions/2.0/KHR_audio_emitter/README.md +++ b/extensions/2.0/KHR_audio_emitter/README.md @@ -37,9 +37,7 @@ Audio emitter objects may be added to 3D nodes for positional audio or to the sc "gain": 0.8, "sources": [0, 1], "positional": { - "coneInnerAngle": 6.283185307179586, - "coneOuterAngle": 6.283185307179586, - "coneOuterGain": 0.0, + "shapeType": "omnidirectional", "distanceModel": "inverse", "maxDistance": 10.0, "refDistance": 1.0, @@ -140,17 +138,17 @@ When storing audio data in a buffer view, the `mimeType` field must be specified Note that in tools that process glTF files, but do not implement the `KHR_audio_emitter` extension, external files referenced via the `uri` field may not be properly copied to their final destination or baked into the final binary glTF file. In these cases, using the `bufferView` property may be a better choice assuming the referenced `bufferView` index is not changed by the tool. The `uri` field might be a better choice when you want to be able to quickly change the referenced audio asset. -#### `bufferView` +#### Buffer View -The index of the bufferView that contains the audio data. Use this instead of the audio source's uri property. +The `"bufferView"` property is the integer index of the bufferView that contains the audio data. If present, use this instead of the audio source's uri property. -#### `mimeType` +#### MIME Type -The audio's MIME type. Required if `bufferView` is defined. Unless specified by another extension, the only supported mimeType is `audio/mpeg`. +The `"mimeType"` property is a string that specifies 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`. -#### `uri` +#### URI -The uri of the audio file. Relative paths are relative to the .gltf file. +The `"uri"` property is a string for the uri of the audio file. Relative paths are relative to the .gltf file. ### Audio Sources @@ -165,23 +163,23 @@ Audio sources reference audio data and define playback properties for it. Audio | **autoPlay** | `boolean` | Whether or not to play the specified audio when the glTF is loaded. | false | | **audio** | `number` | The index of the audio data assigned to this clip. | Required, no default | -#### `gain` +#### Gain -Unitless linear multiplier against original audio file volume used for determining audio source loudness. If not specified, the audio source volume gain is `1.0`. +The `"gain"` property is a number that is a unitless linear multiplier against original audio file volume used for determining audio source loudness. If not specified, the audio source volume gain is `1.0`. This value is linear, a value of `0.0` is no volume, `0.5` is half volume, `1.0` is the original volume, `2.0` is double the volume, etc. The final volume of the audio is a combination of this value, the audio emitter's gain, and if the audio emitter is positional, the relative positions of the emitter and listener. -#### `loop` +#### Loop -Whether or not to loop the specified audio when finished. If `false` or not specified, the audio source does not loop. +The `"loop"` property is a boolean that specifies whether or not to loop the specified audio when finished. If `false` or not specified, the audio source does not loop. -#### `autoPlay` +#### Auto Play -Whether or not to play the specified audio when the glTF is loaded. If `false` or not specified, the audio source does not play automatically. +The `"autoPlay"` property is a boolean that specifies whether or not to play the specified audio when the glTF is loaded. If `false` or not specified, the audio source does not play automatically. -#### `audio` +#### Audio -The index of the audio data in the "audio" array assigned to this audio source. This property is required. +The `"audio"` property is an integer index of the audio data in the "audio" array assigned to this audio source. This property is required. ### Audio Emitter @@ -196,26 +194,26 @@ Audio emitters define how audio sources are played back. Emitter properties are | **sources** | `number[]` | An array of audio source indices used by the audio emitter. This array may be empty. | [] | | **positional** | `object` | A sub-JSON containing the positional audio emitter properties. | {} | -#### `type` +#### Type -Specifies the audio emitter type. This property is required. +The `"type"` property is a string that 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 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` +#### Gain -Unitless linear multiplier against audio source volume used for determining audio emitter loudness. If not specified, the audio emitter volume gain is `1.0`. +The `"gain"` property is a number that is a unitless linear multiplier against audio source volume used for determining audio emitter loudness. If not specified, the audio emitter volume gain is `1.0`. This value is linear, a value of `0.0` is no volume, `0.5` is half volume, `1.0` is the original volume, `2.0` is double the volume, etc. The final volume of the audio is a combination of this value, the audio source's gain, and if the audio emitter is positional, the relative positions of the emitter and listener. -#### `sources` +#### Sources -An array of audio source indices used by the audio emitter. This array may be empty. If empty or not specified, this emitter can be used to define how audio should emit from a node, but not which audio source to play. +The `"sources"` property is an array of integer indices of audio sources in the "sources" array used by the audio emitter. This array may be empty. If empty or not specified, this emitter can be used to define how audio should emit from a node, but not which audio source to play. -#### `positional` +#### Positional -A sub-JSON object containing the positional audio emitter properties. This may only be defined if `type` is set to `positional`. +The `"positional"` property is a sub-JSON object containing the positional audio emitter properties. This may only be defined if `type` is set to `positional`. ### Positional Audio Emitter Properties @@ -225,6 +223,7 @@ When the audio emitter type is set to `positional`, additional properties may be | | Type | Description | Default value | | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| **shapeType** | `string` | The shape of the audio emitter. May be `omnidirectional`, `cone`, or a value specified by another extension. | `"omnidirectional"` | | **coneInnerAngle** | `number` | The anglular diameter of a cone inside of which there will be no angular volume reduction. | 6.2831853... (τ or 2π rad, 360 deg) | | **coneOuterAngle** | `number` | The anglular diameter of a cone outside of which the volume will be reduced to a constant value of `coneOuterGain`. | 6.2831853... (τ or 2π rad, 360 deg) | | **coneOuterGain** | `number` | The linear volume gain of the audio emitter set when outside the cone defined by the `coneOuterAngle` property. | 0.0 | @@ -233,21 +232,27 @@ When the audio emitter type is set to `positional`, additional properties may be | **refDistance** | `number` | A reference distance for reducing volume as the emitter moves further from the listener. | 1.0 | | **rolloffFactor** | `number` | Describes how quickly the volume is reduced as the emitter moves away from listener. | 1.0 | -#### `coneInnerAngle` +#### Shape Type -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 (`6.283185307179586476925286766559` or 360 degrees) is used, which means the audio emits in all directions (not in a cone). +The `"shapeType"` property is a string that defines shape type of the audio emitter. May be `"omnidirectional"`, `"cone"`, or a value specified by another extension. If not specified, the default shape is `omnidirectional`. -#### `coneOuterAngle` +If the shape is `"omnidirectional"`, the `"coneInnerAngle"`, `"coneOuterAngle"`, and `"coneOuterGain"` properties are ignored. -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 (`6.283185307179586476925286766559` or 360 degrees) is used, which means some audio will emit in all directions. +#### Cone Inner Angle -#### `coneOuterGain` +The `"coneInnerAngle"` property is a number that defines 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 (`6.283185307179586476925286766559` or 360 degrees) is used, which means the audio emits in all directions (not in a 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. +#### Cone Outer Angle -#### `distanceModel` +The `"coneOuterAngle"` property is a number that defines 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 (`6.283185307179586476925286766559` or 360 degrees) is used, which means some audio will emit in all directions. -Specifies the distance model for the audio emitter. +#### Cone Outer Gain + +The `"coneOuterGain"` property is a number that defines 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. + +#### Distance Model + +The `"distanceModel"` property is a string that specifies the distance model for the audio emitter. - `linear` A linear distance model calculating the gain induced by the distance according to: `1.0 - rolloffFactor * (distance - refDistance) / (maxDistance - refDistance)` @@ -256,19 +261,19 @@ Specifies the distance model for the audio emitter. - `exponential` An exponential distance model calculating the gain induced by the distance according to: `pow((Math.max(distance, refDistance) / refDistance, -rolloffFactor))` -#### `maxDistance` +#### Max Distance -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. +The `"maxDistance"` property is a number that defines 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. For the linear distance model, the max distance must be greater than the ref distance. For all distance models, max distance cannot be a negative number. -#### `refDistance` +#### Ref Distance -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`. +The `"refDistance"` property is a number that defines 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`. -#### `rolloffFactor` +#### Rolloff Factor -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.0`. Otherwise, there is no upper limit to the rolloff factor. If not specified, the default value is `1.0`. +The `"rolloffFactor"` property is a number that 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.0`. Otherwise, there is no upper limit to the rolloff factor. If not specified, the default value is `1.0`. ### Using Audio Emitters diff --git a/extensions/2.0/KHR_audio_emitter/schema/glTF.KHR_audio_emitter.emitter.positional.schema.json b/extensions/2.0/KHR_audio_emitter/schema/glTF.KHR_audio_emitter.emitter.positional.schema.json index d078d30..a0f4fc9 100644 --- a/extensions/2.0/KHR_audio_emitter/schema/glTF.KHR_audio_emitter.emitter.positional.schema.json +++ b/extensions/2.0/KHR_audio_emitter/schema/glTF.KHR_audio_emitter.emitter.positional.schema.json @@ -6,6 +6,24 @@ "description": "Positional audio emitter properties.", "allOf": [{ "$ref": "glTFProperty.schema.json" }], "properties": { + "shapeType": { + "type": "string", + "description": "Shape in which emitter emits audio (omnidirectional, cone, custom).", + "anyOf": [ + { + "const": "omnidirectional", + "description": "Emitter emits audio in all directions." + }, + { + "const": "cone", + "description": "Emitter emits audio in a cone defined by coneInnerAngle, coneOuterAngle, and coneOuterGain." + }, + { + "type": "string" + } + ], + "default": "omnidirectional" + }, "coneInnerAngle": { "type": "number", "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).",