Feat/audio buffer source node/override start method (#297)

maciejmakowski2003 · Maciej Makowski · web-flow · commit b6a3c40e3f0d · 2025-02-13T13:44:43.000+01:00
* feat: implemented overridden buffer source start method

* feat: added pause feature to example app

* chore: update API coverage

---------

Co-authored-by: Maciej Makowski &lt;maciej.makowski2608@gmail.com&gt;
diff --git a/apps/common-app/src/examples/AudioFile/AudioFile.tsx b/apps/common-app/src/examples/AudioFile/AudioFile.tsx
@@ -12,23 +12,14 @@ import { ActivityIndicator } from 'react-native';
 const AudioFile: FC = () => {
   const [isPlaying, setIsPlaying] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
-  const [audioBuffer, setAudioBuffer] = useState<AudioBuffer | null>(null);
-
-  const audioContextRef = useRef<AudioContext | null>(null);
-  const audioBufferSourceNodeRef = useRef<AudioBufferSourceNode | null>(null);
 
-  const setup = () => {
-    if (!audioContextRef.current) {
-      audioContextRef.current = new AudioContext();
-    }
+  const [audioBuffer, setAudioBuffer] = useState<AudioBuffer | null>(null);
 
-    audioBufferSourceNodeRef.current =
-      audioContextRef.current.createBufferSource();
+  const [startTime, setStartTime] = useState(0);
+  const [offset, setOffset] = useState(0);
 
-    audioBufferSourceNodeRef.current.connect(
-      audioContextRef.current.destination
-    );
-  };
+  const audioContextRef = useRef<AudioContext | null>(null);
+  const bufferSourceRef = useRef<AudioBufferSourceNode | null>(null);
 
   const handleSetAudioSourceFromFile = async () => {
     try {
@@ -38,7 +29,7 @@ const AudioFile: FC = () => {
       });
 
       if (result.canceled === false) {
-        audioBufferSourceNodeRef.current?.stop();
+        bufferSourceRef.current?.stop();
         setIsPlaying(false);
 
         setIsLoading(true);
@@ -62,19 +53,24 @@ const AudioFile: FC = () => {
   }, []);
 
   const handlePress = () => {
-    if (!audioBuffer) {
+    if (!audioBuffer || !audioContextRef.current) {
       return;
     }
 
     if (isPlaying) {
-      audioBufferSourceNodeRef.current?.stop();
+      const stopTime = audioContextRef.current.currentTime;
+      bufferSourceRef.current?.stop(stopTime);
+      setOffset((prev) => prev + stopTime - startTime);
     } else {
-      setup();
-      audioBufferSourceNodeRef.current!.buffer = audioBuffer;
-      audioBufferSourceNodeRef.current?.start();
+      bufferSourceRef.current = audioContextRef.current.createBufferSource();
+      bufferSourceRef.current.buffer = audioBuffer;
+      bufferSourceRef.current.connect(audioContextRef.current.destination);
+
+      setStartTime(audioContextRef.current.currentTime);
+      bufferSourceRef.current.start(startTime, offset);
     }
 
-    setIsPlaying(!isPlaying);
+    setIsPlaying((prev) => !prev);
   };
 
   useEffect(() => {
diff --git a/apps/common-app/src/examples/AudioVisualizer/AudioVisualizer.tsx b/apps/common-app/src/examples/AudioVisualizer/AudioVisualizer.tsx
@@ -24,14 +24,19 @@ const AudioVisualizer: React.FC = () => {
   const [times, setTimes] = useState<number[]>(new Array(FFT_SIZE).fill(127));
   const [freqs, setFreqs] = useState<number[]>(new Array(FFT_SIZE / 2).fill(0));
 
+  const [startTime, setStartTime] = useState(0);
+  const [offset, setOffset] = useState(0);
+
   const audioContextRef = useRef<AudioContext | null>(null);
   const analyserRef = useRef<AnalyserNode | null>(null);
   const bufferSourceRef = useRef<AudioBufferSourceNode | null>(null);
   const audioBufferRef = useRef<AudioBuffer | null>(null);
 
   const handlePlayPause = () => {
     if (isPlaying) {
-      bufferSourceRef.current?.stop();
+      const stopTime = audioContextRef.current!.currentTime;
+      bufferSourceRef.current?.stop(stopTime);
+      setOffset((prev) => prev + stopTime - startTime);
     } else {
       if (!audioContextRef.current || !analyserRef.current) {
         return;
@@ -41,7 +46,8 @@ const AudioVisualizer: React.FC = () => {
       bufferSourceRef.current.buffer = audioBufferRef.current;
       bufferSourceRef.current.connect(analyserRef.current);
 
-      bufferSourceRef.current.start();
+      setStartTime(audioContextRef.current.currentTime);
+      bufferSourceRef.current.start(startTime, offset);
 
       requestAnimationFrame(draw);
     }
diff --git a/docs/web-audio-coverage.md b/docs/web-audio-coverage.md
@@ -7,14 +7,17 @@ Some of the noticeable implementation details that are still in progress or not
 - Support of different number of channels (current approach in most of the audio-graph nodes assumes working with two channel audio)
 - Multi-input for each node and input mixing (Although specification suggests that most of the nodes can cave only one input or output, common use-cases proves otherwise). Only node that mixes multiple inputs is `DestinationNode`.
 
-## ✅ Completed (**11** out of 32)
+## ✅ Completed (**12** out of 32)
 
 <details>
  <summary><b>AnalyserNode</b></summary>
 </details>
 <details>
   <summary><b>AudioBuffer</b></summary>
 </details>
+<details>
+  <summary><b>AudioBufferSourceNode</b></summary>
+</details>
 <details>
  <summary><b>AudioDestinationNode</b></summary>
 </details>
@@ -43,7 +46,7 @@ Some of the noticeable implementation details that are still in progress or not
  <summary><b>StereoPannerNode</b></summary>
 </details>
 
-## 🚧 In Progress (**3** out of 32)
+## 🚧 In Progress (**2** out of 32)
 
 <details>
   <summary><b>AudioContext</b></summary>
@@ -67,25 +70,6 @@ Some of the noticeable implementation details that are still in progress or not
 
 </details>
 
-<details>
-  <summary><b>AudioBufferSourceNode</b></summary>
-
-<div style="padding: 16px; padding-left: 42px;">
-
-| Property 🔹/ Method 🔘 | state |
-| ---------------------- | ----- |
-| 🔹 buffer              | ✅    |
-| 🔹 detune              | ✅    |
-| 🔹 loop                | ✅    |
-| 🔹 loopStart           | ✅    |
-| 🔹 loopEnd             | ✅    |
-| 🔹 playBackRate        | ✅    |
-| 🔘 start(overridden)   | ❌    |
-
-</div>
-
-</details>
-
 <details>
   <summary><b>BaseAudioContext</b></summary>
 
diff --git a/packages/react-native-audio-api/common/cpp/HostObjects/AudioBufferSourceNodeHostObject.h b/packages/react-native-audio-api/common/cpp/HostObjects/AudioBufferSourceNodeHostObject.h
@@ -28,6 +28,12 @@ class AudioBufferSourceNodeHostObject
     addSetters(
         JSI_EXPORT_PROPERTY_SETTER(AudioBufferSourceNodeHostObject, loop),
         JSI_EXPORT_PROPERTY_SETTER(AudioBufferSourceNodeHostObject, buffer));
+
+    // start method is overridden in this class
+    functions_->erase("start");
+
+    addFunctions(
+        JSI_EXPORT_FUNCTION(AudioBufferSourceNodeHostObject, start));
   }
 
   JSI_PROPERTY_GETTER(loop) {
@@ -111,6 +117,18 @@ class AudioBufferSourceNodeHostObject
         std::static_pointer_cast<AudioBufferSourceNode>(node_);
     audioBufferSourceNode->setLoopEnd(value.getNumber());
   }
+
+  JSI_HOST_FUNCTION(start) {
+    auto when = args[0].getNumber();
+    auto offset = args[1].getNumber();
+    auto duration = args[2].getNumber();
+
+    auto audioBufferSourceNode =
+      std::static_pointer_cast<AudioBufferSourceNode>(node_);
+    audioBufferSourceNode->start(when, offset, duration);
+
+    return jsi::Value::undefined();
+  }
 };
 
 } // namespace audioapi
diff --git a/packages/react-native-audio-api/common/cpp/HostObjects/AudioScheduledSourceNodeHostObject.h b/packages/react-native-audio-api/common/cpp/HostObjects/AudioScheduledSourceNodeHostObject.h
@@ -20,10 +20,10 @@ class AudioScheduledSourceNodeHostObject : public AudioNodeHostObject {
   }
 
   JSI_HOST_FUNCTION(start) {
-    auto time = args[0].getNumber();
+    auto when = args[0].getNumber();
     auto audioScheduleSourceNode =
         std::static_pointer_cast<AudioScheduledSourceNode>(node_);
-    audioScheduleSourceNode->start(time);
+    audioScheduleSourceNode->start(when);
     return jsi::Value::undefined();
   }
 
diff --git a/packages/react-native-audio-api/common/cpp/core/AudioBuffer.cpp b/packages/react-native-audio-api/common/cpp/core/AudioBuffer.cpp
@@ -27,8 +27,8 @@ float AudioBuffer::getSampleRate() const {
   return bus_->getSampleRate();
 }
 
-float AudioBuffer::getDuration() const {
-  return static_cast<float>(getLength()) / getSampleRate();
+double AudioBuffer::getDuration() const {
+  return static_cast<double>(getLength()) / getSampleRate();
 }
 
 float *AudioBuffer::getChannelData(int channel) const {
diff --git a/packages/react-native-audio-api/common/cpp/core/AudioBuffer.h b/packages/react-native-audio-api/common/cpp/core/AudioBuffer.h
@@ -17,7 +17,7 @@ class AudioBuffer : public std::enable_shared_from_this<AudioBuffer> {
 
   [[nodiscard]] size_t getLength() const;
   [[nodiscard]] float getSampleRate() const;
-  [[nodiscard]] float getDuration() const;
+  [[nodiscard]] double getDuration() const;
 
   [[nodiscard]] int getNumberOfChannels() const;
   [[nodiscard]] float *getChannelData(int channel) const;
diff --git a/packages/react-native-audio-api/common/cpp/core/AudioBufferSourceNode.cpp b/packages/react-native-audio-api/common/cpp/core/AudioBufferSourceNode.cpp
@@ -80,6 +80,19 @@ void AudioBufferSourceNode::setBuffer(
   alignedBus_->sum(buffer_->bus_.get());
 }
 
+void AudioBufferSourceNode::start(double when, double offset, double duration) {
+  AudioScheduledSourceNode::start(when);
+
+  offset = std::min(offset, buffer_->getDuration());
+  if (loop_) {
+    offset = std::min(offset, loopEnd_);
+  }
+
+  vReadIndex_ = static_cast<double>(buffer_->getSampleRate() * offset);
+
+  AudioScheduledSourceNode::stop(when + duration);
+}
+
 void AudioBufferSourceNode::processNode(
     AudioBus *processingBus,
     int framesToProcess) {
diff --git a/packages/react-native-audio-api/common/cpp/core/AudioBufferSourceNode.h b/packages/react-native-audio-api/common/cpp/core/AudioBufferSourceNode.h
@@ -18,18 +18,17 @@ class AudioBufferSourceNode : public AudioScheduledSourceNode {
   [[nodiscard]] bool getLoop() const;
   [[nodiscard]] double getLoopStart() const;
   [[nodiscard]] double getLoopEnd() const;
-
   [[nodiscard]] std::shared_ptr<AudioParam> getDetuneParam() const;
   [[nodiscard]] std::shared_ptr<AudioParam> getPlaybackRateParam() const;
-
   [[nodiscard]] std::shared_ptr<AudioBuffer> getBuffer() const;
 
   void setLoop(bool loop);
   void setLoopStart(double loopStart);
   void setLoopEnd(double loopEnd);
-
   void setBuffer(const std::shared_ptr<AudioBuffer> &buffer);
 
+  void start(double when, double offset, double duration);
+
  protected:
   void processNode(AudioBus *processingBus, int framesToProcess) override;
 
diff --git a/packages/react-native-audio-api/common/cpp/core/AudioScheduledSourceNode.cpp b/packages/react-native-audio-api/common/cpp/core/AudioScheduledSourceNode.cpp
@@ -15,13 +15,13 @@ AudioScheduledSourceNode::AudioScheduledSourceNode(BaseAudioContext *context)
   numberOfInputs_ = 0;
 }
 
-void AudioScheduledSourceNode::start(double time) {
+void AudioScheduledSourceNode::start(double when) {
   playbackState_ = PlaybackState::SCHEDULED;
-  startTime_ = time;
+  startTime_ = when;
 }
 
-void AudioScheduledSourceNode::stop(double time) {
-  stopTime_ = time;
+void AudioScheduledSourceNode::stop(double when) {
+  stopTime_ = when;
 }
 
 bool AudioScheduledSourceNode::isUnscheduled() {
diff --git a/packages/react-native-audio-api/common/cpp/core/AudioScheduledSourceNode.h b/packages/react-native-audio-api/common/cpp/core/AudioScheduledSourceNode.h
@@ -19,8 +19,8 @@ class AudioScheduledSourceNode : public AudioNode {
   enum class PlaybackState { UNSCHEDULED, SCHEDULED, PLAYING, FINISHED };
   explicit AudioScheduledSourceNode(BaseAudioContext *context);
 
-  void start(double time);
-  void stop(double time);
+  void start(double when);
+  void stop(double when);
 
   bool isUnscheduled();
   bool isScheduled();
diff --git a/packages/react-native-audio-api/src/core/AudioBufferSourceNode.ts b/packages/react-native-audio-api/src/core/AudioBufferSourceNode.ts
@@ -3,6 +3,7 @@ import AudioScheduledSourceNode from './AudioScheduledSourceNode';
 import BaseAudioContext from './BaseAudioContext';
 import AudioBuffer from './AudioBuffer';
 import AudioParam from './AudioParam';
+import { InvalidStateError, RangeError } from '../errors';
 
 export default class AudioBufferSourceNode extends AudioScheduledSourceNode {
   readonly playbackRate: AudioParam;
@@ -55,4 +56,41 @@ export default class AudioBufferSourceNode extends AudioScheduledSourceNode {
   public set loopEnd(value: number) {
     (this.node as IAudioBufferSourceNode).loopEnd = value;
   }
+
+  public start(when: number = 0, offset: number = 0, duration?: number): void {
+    if (when < 0) {
+      throw new RangeError(
+        `when must be a finite non-negative number: ${when}`
+      );
+    }
+
+    if (offset < 0) {
+      throw new RangeError(
+        `offset must be a finite non-negative number: ${when}`
+      );
+    }
+
+    if (duration && duration < 0) {
+      throw new RangeError(
+        `duration must be a finite non-negative number: ${when}`
+      );
+    }
+
+    if (this.hasBeenStarted) {
+      throw new InvalidStateError('Cannot call start more than once');
+    }
+
+    this.hasBeenStarted = true;
+
+    if (duration) {
+      (this.node as IAudioBufferSourceNode).start(when, offset, duration);
+      return;
+    }
+
+    (this.node as IAudioBufferSourceNode).start(
+      when,
+      offset,
+      this.buffer!.duration
+    );
+  }
 }
diff --git a/packages/react-native-audio-api/src/core/AudioScheduledSourceNode.ts b/packages/react-native-audio-api/src/core/AudioScheduledSourceNode.ts
@@ -3,12 +3,12 @@ import AudioNode from './AudioNode';
 import { InvalidStateError, RangeError } from '../errors';
 
 export default class AudioScheduledSourceNode extends AudioNode {
-  private hasBeenStarted: boolean = false;
+  protected hasBeenStarted: boolean = false;
 
   public start(when: number = 0): void {
     if (when < 0) {
       throw new RangeError(
-        `Time must be a finite non-negative number: ${when}`
+        `when must be a finite non-negative number: ${when}`
       );
     }
 
@@ -23,7 +23,7 @@ export default class AudioScheduledSourceNode extends AudioNode {
   public stop(when: number = 0): void {
     if (when < 0) {
       throw new RangeError(
-        `Time must be a finite non-negative number: ${when}`
+        `when must be a finite non-negative number: ${when}`
       );
     }
 
diff --git a/packages/react-native-audio-api/src/index.ts b/packages/react-native-audio-api/src/index.ts
@@ -257,6 +257,14 @@ export class AudioBufferSourceNode extends AudioScheduledSourceNode {
   public set loopEnd(value: number) {
     (this.node as globalThis.AudioBufferSourceNode).loopEnd = value;
   }
+
+  public start(when?: number, offset?: number, duration?: number): void {
+    (this.node as globalThis.AudioBufferSourceNode).start(
+      when,
+      offset,
+      duration
+    );
+  }
 }
 
 export class AudioDestinationNode extends AudioNode {}
diff --git a/packages/react-native-audio-api/src/interfaces.ts b/packages/react-native-audio-api/src/interfaces.ts

Original file line number	Diff line number	Diff line change
`@@ -20,10 +20,10 @@ class AudioScheduledSourceNodeHostObject : public AudioNodeHostObject {`
`20`	`20`	`}`
`21`	`21`
`22`	`22`	`JSI_HOST_FUNCTION(start) {`
`23`		`- auto time = args[0].getNumber();`
	`23`	`+ auto when = args[0].getNumber();`
`24`	`24`	`auto audioScheduleSourceNode =`
`25`	`25`	`std::static_pointer_cast<AudioScheduledSourceNode>(node_);`
`26`		`- audioScheduleSourceNode->start(time);`
	`26`	`+ audioScheduleSourceNode->start(when);`
`27`	`27`	`return jsi::Value::undefined();`
`28`	`28`	`}`
`29`	`29`
Original file line number	Diff line number	Diff line change
`@@ -27,8 +27,8 @@ float AudioBuffer::getSampleRate() const {`
`27`	`27`	`return bus_->getSampleRate();`
`28`	`28`	`}`
`29`	`29`
`30`		`-float AudioBuffer::getDuration() const {`
`31`		`- return static_cast<float>(getLength()) / getSampleRate();`
	`30`	`+double AudioBuffer::getDuration() const {`
	`31`	`+ return static_cast<double>(getLength()) / getSampleRate();`
`32`	`32`	`}`
`33`	`33`
`34`	`34`	`float *AudioBuffer::getChannelData(int channel) const {`
Original file line number	Diff line number	Diff line change
`@@ -15,13 +15,13 @@ AudioScheduledSourceNode::AudioScheduledSourceNode(BaseAudioContext *context)`
`15`	`15`	`numberOfInputs_ = 0;`
`16`	`16`	`}`
`17`	`17`
`18`		`-void AudioScheduledSourceNode::start(double time) {`
	`18`	`+void AudioScheduledSourceNode::start(double when) {`
`19`	`19`	`playbackState_ = PlaybackState::SCHEDULED;`
`20`		`- startTime_ = time;`
	`20`	`+ startTime_ = when;`
`21`	`21`	`}`
`22`	`22`
`23`		`-void AudioScheduledSourceNode::stop(double time) {`
`24`		`- stopTime_ = time;`
	`23`	`+void AudioScheduledSourceNode::stop(double when) {`
	`24`	`+ stopTime_ = when;`
`25`	`25`	`}`
`26`	`26`
`27`	`27`	`bool AudioScheduledSourceNode::isUnscheduled() {`