| … | … | @@ -2,7 +2,23 @@ |
| 2 | 2 | |
| 3 | 3 | ## Contributors |
| 4 | 4 | |
| 5 | | ## Example |
| 5 | * Robert Long, Element Inc. |
| 6 | |
| 7 | ## Status |
| 8 | |
| 9 | Open Metaverse Interoperability Group Stage 1 Proposal |
| 10 | |
| 11 | ## Dependencies |
| 12 | |
| 13 | Written against the glTF 2.0 spec. |
| 14 | |
| 15 | ## Overview |
| 16 | |
| 17 | This extension allows for the addition of spatialized and non-spatialized audio to glTF scenes. |
| 18 | |
| 19 | Audio emitter objects may be added to 3D nodes for positional audio or to the scene for environmental or ambient audio such as background music. |
| 20 | |
| 21 | ### Example: |
| 6 | 22 | |
| 7 | 23 | ```json |
| 8 | 24 | { |
| … | … | @@ -69,27 +85,170 @@ |
| 69 | 85 | ] |
| 70 | 86 | } |
| 71 | 87 | ``` |
| 72 | | # OMI_audio_emitter |
| 73 | 88 | |
| 74 | | ## Contributors |
| 89 | ## glTF Schema Updates |
| 75 | 90 | |
| 76 | | * Robert Long, Element Inc. |
| 91 | This extension consists of two primary data structures: Audio Sources and Audio Emitters. Both sources and emitters are defined on an `OMI_audio_emitter` object added to the `extensions` |
| 92 | object on the document root. |
| 77 | 93 | |
| 78 | | ## Status |
| 94 | The extension must be added to the file's `extensionsUsed` array and because it is optional, it does not need to be added to the `extensionsRequired` array. |
| 79 | 95 | |
| 80 | | Open Metaverse Interoperability Group Stage 1 Proposal |
| 96 | #### Example: |
| 81 | 97 | |
| 82 | | ## Dependencies |
| 98 | ```json |
| 99 | { |
| 100 | "asset": { |
| 101 | "version": "2.0" |
| 102 | } |
| 103 | "extensionsUsed" : [ |
| 104 | "OMI_audio_emitter" |
| 105 | ], |
| 106 | "scenes": [...], |
| 107 | "nodes": [...], |
| 108 | "extensions": { |
| 109 | "OMI_audio_emitter": { |
| 110 | "audioSources": [...], |
| 111 | "audioEmitters": [...] |
| 112 | } |
| 113 | } |
| 114 | } |
| 115 | ``` |
| 83 | 116 | |
| 84 | | Written against the glTF 2.0 spec. |
| 117 | ### Audio Sources |
| 85 | 118 | |
| 86 | | ## Overview |
| 119 | Audio source objects define audio data to be used in audio emitters. Multiple audio emitters may use the same audio source. |
| 87 | 120 | |
| 88 | | TODO |
| 121 | Audio sources can store their data in either a buffer view or reference an external file via uri. |
| 89 | 122 | |
| 90 | | ## glTF Schema Updates |
| 123 | When storing audio data in a buffer view, the `mimeType` field must be specified. Currently the only supported mime type is `audio/mpeg`. |
| 124 | |
| 125 | #### `bufferView` |
| 126 | |
| 127 | The index of the bufferView that contains the audio data. Use this instead of the image's uri property. |
| 128 | |
| 129 | #### `mimeType` |
| 130 | |
| 131 | The audio's MIME type. Required if `bufferView` is defined. Unless specified by another extension, the only supported mimeType is audio/mpeg. |
| 132 | |
| 133 | #### `uri` |
| 134 | |
| 135 | The uri of the audio file. Relative paths are relative to the glTF file. |
| 136 | |
| 137 | #### MP3 Audio Format |
| 138 | |
| 139 | Provides a space efficient format that can also be tuned to satisfy audio engineers. |
| 140 | |
| 141 | The MPEG3 Audio Format is commonly available and freely licensed. |
| 142 | |
| 143 | ### Audio Emitter |
| 144 | |
| 145 | #### `type` |
| 146 | |
| 147 | Specifies the audio emitter type. |
| 148 | |
| 149 | - `positional` Positional audio emitters |
| 150 | - `global ` Global audio emitters are not affected by the position of audio listeners. `coneInnerAngle`, `coneOuterAngle`, `coneOuterGain`, `distanceModel`, `maxDistance`, `refDistance`, and `rolloffFactor` should all be ignored when set. |
| 151 | |
| 152 | #### `gain` |
| 153 | |
| 154 | Unitless multiplier against original source volume for determining emitter loudness. |
| 155 | |
| 156 | #### `loop` |
| 157 | |
| 158 | Whether or not to loop the specified audio clip when finished. |
| 159 | |
| 160 | #### `autoPlay` |
| 161 | |
| 162 | Whether or not to play the specified audio clip when this scene is loaded. |
| 163 | |
| 164 | #### `source` |
| 165 | |
| 166 | The id of the audio source referenced by this audio emitter. |
| 167 | |
| 168 | #### `coneInnerAngle` |
| 169 | |
| 170 | The angle, in radians, of a cone inside of which there will be no volume reduction. |
| 171 | |
| 172 | #### `coneOuterAngle` |
| 173 | |
| 174 | The angle, in radians, of a cone outside of which the volume will be reduced to a constant value of`coneOuterGain`. |
| 175 | |
| 176 | #### `coneOuterGain` |
| 177 | |
| 178 | The gain of the audio emitter set when outside the cone defined by the `coneOuterAngle` property. It is a linear value (not dB). |
| 179 | |
| 180 | #### `distanceModel` |
| 181 | |
| 182 | Specifies the distance model for the audio emitter. |
| 183 | |
| 184 | - `linear` A linear distance model calculating the gain induced by the distance according to: |
| 185 | `1 - rolloffFactor * (distance - refDistance) / (maxDistance - refDistance)` |
| 186 | - `inverse ` (default) An inverse distance model calculating the gain induced by the distance according to: |
| 187 | `refDistance / (refDistance + rolloffFactor * (Math.max(distance, refDistance) - refDistance))` |
| 188 | - `exponential` An exponential distance model calculating the gain induced by the distance according to: |
| 189 | `pow((Math.max(distance, refDistance) / refDistance, -rolloffFactor)` |
| 190 | |
| 191 | #### `maxDistance` |
| 192 | |
| 193 | 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. |
| 194 | |
| 195 | #### `refDistance` |
| 196 | |
| 197 | A reference distance for reducing volume as the emitter moves further from the listener. For distances less than this, the volume is not reduced. |
| 198 | |
| 199 | #### `rolloffFactor` |
| 200 | |
| 201 | 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. |
| 202 | |
| 203 | ### Using Audio Emitters |
| 204 | |
| 205 | Audio emitters of type `global` may be added to scenes using the following syntax: |
| 206 | |
| 207 | ```json |
| 208 | { |
| 209 | "scenes": [ |
| 210 | { |
| 211 | "extensions": { |
| 212 | "OMI_audio_emitter": { |
| 213 | "audioEmitters": [0, 1] |
| 214 | } |
| 215 | } |
| 216 | } |
| 217 | ] |
| 218 | } |
| 219 | ``` |
| 220 | |
| 221 | Audio emitters of type `positional` may be added to nodes using the following syntax: |
| 222 | |
| 223 | ```json |
| 224 | { |
| 225 | "nodes": [ |
| 226 | { |
| 227 | "extensions": { |
| 228 | "OMI_audio_emitter": { |
| 229 | "audioEmitter": 2 |
| 230 | } |
| 231 | } |
| 232 | } |
| 233 | ] |
| 234 | } |
| 235 | ``` |
| 236 | |
| 237 | Note that multiple global audio emitters are allowed on the scene, but only a single audio emitter may be added to a node. |
| 238 | |
| 239 | <!-- include audio formula for rolloff --> |
| 240 | |
| 241 | <!-- include audio formula for gain --> |
| 242 | |
| 243 | <!-- include audio formula for cone --> |
| 244 | |
| 245 | ### Audio Gain Units |
| 246 | |
| 247 | |
| 248 | |
| 249 | ### Units for Rotations |
| 91 | 250 | |
| 92 | | TODO |
| 251 | Radians are used for rotations matching glTF2. |
| 93 | 252 | |
| 94 | 253 | ### JSON Schema |
| 95 | 254 | |
| … | … | @@ -98,7 +257,9 @@ TODO |
| 98 | 257 | ## Known Implementations |
| 99 | 258 | |
| 100 | 259 | * TODO: List of known implementations, with links to each if available. |
| 260 | * |
| 101 | 261 | |
| 102 | 262 | ## Resources |
| 103 | 263 | |
| 104 | | * TODO: Resources, if any. |
| 264 | Prior Art: |
| 265 | * [W3C Web Audio API](https://www.w3.org/TR/webaudio/) |