Merge pull request #239 from aaronfranke/audio-pitch-speed

KHR_audio_emitter: Add pitchSpeed and make audio source's data optional
omigroup · Jan 3, 2025 · b48a264 · b48a264
2 parents a82567f + 758ef2d
commit b48a264
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 7 deletions.
diff --git a/extensions/2.0/KHR_audio_emitter/README.md b/extensions/2.0/KHR_audio_emitter/README.md
@@ -156,19 +156,26 @@ Audio sources reference audio data and define playback properties for it. Audio
 
 #### Property Summary
 
-|              | Type      | Description                                                                                               | Default value        |
-| ------------ | --------- | --------------------------------------------------------------------------------------------------------- | -------------------- |
-| **gain**     | `number`  | Unitless linear multiplier against original audio file volume used for determining audio source loudness. | 1.0                  |
-| **loop**     | `boolean` | Whether or not to loop the specified audio when finished.                                                 | false                |
-| **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 |
+|                | Type      | Description                                                                                               | Default value |
+| -------------- | --------- | --------------------------------------------------------------------------------------------------------- | ------------- |
+| **gain**       | `number`  | Unitless linear multiplier against original audio file volume used for determining audio source loudness. | 1.0           |
+| **pitchSpeed** | `number`  | Multiplier for combined pitch and playback speed without resampling.                                      | 1.0           |
+| **loop**       | `boolean` | Whether or not to loop the specified audio when finished.                                                 | false         |
+| **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.                                                        | No audio      |
 
 #### Gain
 
 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.
 
+#### Pitch Speed
+
+The `"pitchSpeed"` property is a number that is a multiplier for combined pitch and playback speed without resampling. If not specified, the pitch speed is `1.0`.
+
+For example, a value of `2.0` would double the playback speed of the audio, which doubles all frequencies in the audio, doubling the pitch.
+
 #### 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.
@@ -179,7 +186,9 @@ The `"autoPlay"` property is a boolean that specifies whether or not to play the
 
 #### Audio
 
-The `"audio"` property is an integer 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. If not specified, the audio source does not have an audio clip.
+
+This value is recommended to be set to a valid index in the "audio" array, or else no audio can be played from this source. However, omitting this field allows the audio source to be used as a placeholder for future audio assignment. Additionally, other extensions may define their own audio data properties.
 
 ### Audio Emitter
 
@@ -373,6 +382,7 @@ The following JSON pointers are defined representing mutable properties defined
 | `/extensions/KHR_audio_emitter/sources/{}/autoPlay`                   | `bool`            |
 | `/extensions/KHR_audio_emitter/sources/{}/gain`                       | `float`           |
 | `/extensions/KHR_audio_emitter/sources/{}/loop`                       | `bool`            |
+| `/extensions/KHR_audio_emitter/sources/{}/pitchSpeed`                 | `float`           |
 
 Additionally, the following JSON pointers are defined for read-only properties:
 

diff --git a/extensions/2.0/KHR_audio_emitter/schema/glTF.KHR_audio_emitter.source.schema.json b/extensions/2.0/KHR_audio_emitter/schema/glTF.KHR_audio_emitter.source.schema.json
@@ -17,6 +17,11 @@
             "minimum": 0.0,
             "default": 1.0
         },
+        "pitchSpeed": {
+            "type": "number",
+            "description": "Multiplier for combined pitch and playback speed without resampling.",
+            "default": 1.0
+        },
         "loop": {
             "type": "boolean",
             "description": "Whether or not to loop the specified audio when finished.",