Gamepad Haptics PCM Extension

1. Introduction

1.1. Terminology

This specification uses the terms GamepadHapticActuator and gamepad task source as defined in the Gamepad specification.

It uses the term AudioBuffer as defined in the Web Audio API specification.

2. GamepadHapticActuator Extension

This specification extends the GamepadHapticActuator interface with a method for playing PCM audio data as haptic feedback.

partial interface GamepadHapticActuator {
  Promise<boolean> play(AudioBuffer sound);
};

2.1. play

The play(sound) method plays PCM audio data from an AudioBuffer through the gamepad’s haptic actuator.

When invoked, the user agent MUST run the following steps:

1. Let document be the current settings object’s relevant global object’s associated Document.

2. If document is null or document is not fully active or document’s visibility state is "hidden", return a promise rejected with an "InvalidStateError" DOMException.

3. If sound’s length is 0, return a promise resolved with true.

4. If this.[[playingEffectPromise]] is not null:

   1. Let effectPromise be this.[[playingEffectPromise]].

   2. Set this.[[playingEffectPromise]] to null.

   3. Queue a global task on the gamepad task source with the relevant global object of this to resolve effectPromise with "preempted".

5. Let [[playingEffectPromise]] be a new promise.

6. Run the following steps in parallel:

   1. Send the PCM data from sound to the haptic actuator for playback. If the actuator does not support PCM playback, queue a global task on the gamepad task source with the relevant global object of this to resolve [[playingEffectPromise]] with false, and abort these steps.

   2. When the playback completes successfully, queue a global task on the gamepad task source with the relevant global object of this to resolve [[playingEffectPromise]] with true.

   3. If an error occurs during playback, queue a global task on the gamepad task source with the relevant global object of this to resolve [[playingEffectPromise]] with false.

7. Return [[playingEffectPromise]].

NOTE: The sampleRate of the AudioBuffer may not match the native sample rate of the haptic actuator. In this case, the user agent SHOULD resample the audio data to match the actuator’s native sample rate.

const audioCtx = new AudioContext();
const sampleRate = audioCtx.sampleRate;
const buffer = audioCtx.createBuffer(1, sampleRate * 0.5, sampleRate);

// Fill with a 150Hz sine wave for 0.5 seconds
const channelData = buffer.getChannelData(0);
for (let i = 0; i < buffer.length; i++) {
  channelData[i] = Math.sin(2 * Math.PI * 150 * i / sampleRate);
}

const gamepad = navigator.getGamepads()[0];
const success = await gamepad.vibrationActuator.play(buffer);
if (success) {
  console.log("Haptic waveform played successfully");
} else {
  console.log("PCM haptic playback failed or is not supported");
}

3. Security and Privacy Considerations

This specification does not introduce any new security or privacy considerations beyond those described in the Gamepad and Web Audio API specifications.

The play() method requires the same user activation and visibility conditions as the existing playEffect() method to prevent abuse of haptic hardware by background pages.