react-native-audio-api 0.13.0-nightly-79cb732-20260630 → 0.13.0

package/android/build.gradle

@@ -216,6 +216,7 @@ android {
       "**/librrc_root.so",
       "**/libjscexecutor.so",
       "**/libv8executor.so",
+      "**/libworklets.so",
       "**/libreanimated.so"
     ]
   }

package/android/src/main/cpp/audioapi/android/core/utils/AndroidFileWriterBackend.cpp

@@ -63,8 +63,8 @@ void AndroidFileWriterBackend::cleanupPreallocatedInputPool() {
 }
 
 void AndroidFileWriterBackend::writeAudioData(void *data, int numFrames) {
-  if (offloader_ == nullptr || freeSlots_ == nullptr || inputBufferBytesPerSlot_ == 0 ||
-      inputBuffers_.empty()) {
+  if (!isFileOpen() || offloader_ == nullptr || freeSlots_ == nullptr ||
+      inputBufferBytesPerSlot_ == 0 || inputBuffers_.empty()) {
     return;
   }
 

package/android/src/main/cpp/audioapi/android/core/utils/ffmpegBackend/FFmpegFileWriter.cpp

@@ -108,7 +108,9 @@ CloseFileResult FFmpegAudioFileWriter::closeFile() {
     return CloseFileResult::Err("File is not open");
   }
 
-  // Joins the worker before draining/finalizing the encoder below.
+  isFileOpen_.store(false, std::memory_order_release);
+
+  // Drains the worker queue before flushing/finalizing the encoder below.
   cleanupPreallocatedInputPool();
 
   result = processFifo(true);
@@ -466,10 +468,12 @@ CloseFileResult FFmpegAudioFileWriter::finalizeOutput() {
     avio_closep(&formatCtx_->pb);
   }
 
-  double durationInSeconds = getCurrentDuration();
+  double durationInSeconds = 0.0;
+  if (encoderCtx_ != nullptr && encoderCtx_->sample_rate > 0) {
+    durationInSeconds = static_cast<double>(nextPts_) / encoderCtx_->sample_rate;
+  }
 
   filePath_ = "";
-  isFileOpen_.store(false, std::memory_order_release);
 
   return CloseFileResult::Ok({fileSizeInMB, durationInSeconds});
 }

package/android/src/main/cpp/audioapi/android/core/utils/miniaudioBackend/MiniAudioFileWriter.cpp

@@ -156,11 +156,11 @@ CloseFileResult MiniAudioFileWriter::closeFile() {
     return CloseFileResult ::Err("File is not open");
   }
 
-  // Joins the worker before the encoder teardown below.
-  cleanupPreallocatedInputPool();
-
   isFileOpen_.store(false, std::memory_order_release);
 
+  // Drains the worker queue before the encoder teardown below.
+  cleanupPreallocatedInputPool();
+
   if (encoder_ != nullptr) {
     ma_encoder_uninit(encoder_.get());
     encoder_.reset();

package/android/src/main/java/com/swmansion/audioapi/AudioAPIModule.kt

@@ -109,6 +109,8 @@ class AudioAPIModule(
 
   override fun getDevicePreferredSampleRate(): Double = MediaSessionManager.getDevicePreferredSampleRate()
 
+  override fun isFfmpegEnabled(): Boolean = !BuildConfig.RN_AUDIO_API_FFMPEG_DISABLED
+
   override fun setAudioSessionActivity(
     enabled: Boolean,
     promise: Promise?,

package/android/src/oldarch/NativeAudioAPIModuleSpec.java

@@ -43,6 +43,10 @@ public abstract class NativeAudioAPIModuleSpec extends ReactContextBaseJavaModul
   @DoNotStrip
   public abstract double getDevicePreferredSampleRate();
 
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  @DoNotStrip
+  public abstract boolean isFfmpegEnabled();
+
   @ReactMethod
   @DoNotStrip
   public abstract void setAudioSessionActivity(boolean enabled, Promise promise);

package/common/cpp/audioapi/HostObjects/BaseAudioContextHostObject.cpp

@@ -23,7 +23,7 @@
 #include <audioapi/HostObjects/utils/JsEnumParser.h>
 #include <audioapi/HostObjects/utils/NodeOptionsParser.h>
 #include <audioapi/core/BaseAudioContext.h>
-#include <audioapi/core/utils/AudioDecoding.hpp>
+#include <audioapi/core/utils/AudioDecoding.h>
 
 #include <memory>
 #include <vector>

package/common/cpp/audioapi/HostObjects/utils/AudioDecoderHostObject.cpp

@@ -1,6 +1,6 @@
 #include <audioapi/HostObjects/sources/AudioBufferHostObject.h>
 #include <audioapi/HostObjects/utils/AudioDecoderHostObject.h>
-#include <audioapi/core/utils/AudioDecoding.hpp>
+#include <audioapi/core/utils/AudioDecoding.h>
 #include <audioapi/jsi/JsiPromise.h>
 
 #include <jsi/jsi.h>

package/common/cpp/audioapi/HostObjects/utils/AudioFileUtilsHostObject.cpp

@@ -1,40 +1,19 @@
 #include <audioapi/HostObjects/utils/AudioFileUtilsHostObject.h>
+#include <audioapi/HostObjects/utils/NodeOptionsParser.h>
+#include <audioapi/core/utils/AudioDecoding.h>
 #include <audioapi/core/utils/AudioFileConcatenator.h>
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-#include <audioapi/libs/ffmpeg/FFmpegDecoding.h>
-#endif // RN_AUDIO_API_FFMPEG_DISABLED
-#include <audioapi/core/utils/AudioDecoding.hpp>
 #include <audioapi/jsi/JsiPromise.h>
-#include <audioapi/libs/miniaudio/MiniAudioDecoding.h>
 
 #include <jsi/jsi.h>
 #include <cstdint>
+#include <map>
 #include <memory>
-#include <optional>
 #include <string>
 #include <utility>
 #include <vector>
 
 namespace audioapi {
 
-namespace {
-
-std::optional<double> probeDurationWithDecoder(const uint8_t *data, size_t size, int sampleRate) {
-  auto duration =
-      audiodecoding::probeDuration<miniaudio_decoder::MiniAudioDecoder>(data, size, sampleRate);
-  if (duration.has_value()) {
-    return duration;
-  }
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-  duration = audiodecoding::probeDuration<ffmpeg_decoder::FFmpegDecoder>(data, size, sampleRate);
-  return duration;
-#else
-  return std::nullopt;
-#endif // RN_AUDIO_API_FFMPEG_DISABLED
-}
-
-} // namespace
-
 AudioFileUtilsHostObject::AudioFileUtilsHostObject(
     jsi::Runtime *runtime,
     const std::shared_ptr<react::CallInvoker> &callInvoker) {
@@ -85,38 +64,67 @@ JSI_HOST_FUNCTION_IMPL(AudioFileUtilsHostObject, concatAudioFiles) {
 }
 
 JSI_HOST_FUNCTION_IMPL(AudioFileUtilsHostObject, probeDuration) {
-  if (count < 1 || !args[0].isObject()) {
-    throw jsi::JSError(runtime, "probeDuration expects an ArrayBuffer.");
+  if (count < 1) {
+    throw jsi::JSError(runtime, "probeDuration expects an ArrayBuffer or URL/path string.");
   }
 
-  auto arrayBufferObject = args[0].asObject(runtime);
-  if (!arrayBufferObject.isArrayBuffer(runtime)) {
-    throw jsi::JSError(runtime, "probeDuration expects an ArrayBuffer.");
+  const auto sampleRate =
+      count > 1 && args[1].isNumber() ? static_cast<int>(args[1].getNumber()) : 0;
+
+  if (args[0].isObject() && args[0].asObject(runtime).isArrayBuffer(runtime)) {
+    auto arrayBuffer = args[0].asObject(runtime).getArrayBuffer(runtime);
+    const auto *data = arrayBuffer.data(runtime);
+    const auto size = arrayBuffer.size(runtime);
+
+    auto promise = promiseVendor_->createAsyncPromise(
+        [bytes = std::vector<uint8_t>(data, data + size), sampleRate]() -> PromiseResolver {
+          auto result =
+              audiodecoding::probeDurationWithMemory(bytes.data(), bytes.size(), sampleRate);
+          if (result.is_err()) {
+            return [](jsi::Runtime &runtime) -> std::variant<jsi::Value, std::string> {
+              return jsi::Value::null();
+            };
+          }
+
+          return [duration = static_cast<double>(result.unwrap())](
+                     jsi::Runtime &runtime) -> std::variant<jsi::Value, std::string> {
+            return jsi::Value(duration);
+          };
+        });
+
+    return promise;
   }
 
-  auto arrayBuffer = arrayBufferObject.getArrayBuffer(runtime);
-  const auto *data = arrayBuffer.data(runtime);
-  const auto size = arrayBuffer.size(runtime);
+  if (args[0].isString()) {
+    const auto pathOrUrl = args[0].asString(runtime).utf8(runtime);
 
-  const auto sampleRate =
-      count > 1 && args[1].isNumber() ? static_cast<int>(args[1].getNumber()) : 0;
+    std::map<std::string, std::string> headers;
+    if (count > 2 && args[2].isObject()) {
+      headers = audioapi::option_parser::parseHttpHeaders(runtime, args[2].asObject(runtime));
+    }
 
-  auto promise = promiseVendor_->createAsyncPromise(
-      [bytes = std::vector<uint8_t>(data, data + size), sampleRate]() -> PromiseResolver {
-        auto duration = probeDurationWithDecoder(bytes.data(), bytes.size(), sampleRate);
-        if (!duration.has_value()) {
-          return [](jsi::Runtime &runtime) -> std::variant<jsi::Value, std::string> {
-            return jsi::Value::null();
+    auto promise = promiseVendor_->createAsyncPromise(
+        [pathOrUrl, sampleRate, headers = std::move(headers)]() -> PromiseResolver {
+          auto result = audiodecoding::isHttpUrl(pathOrUrl)
+              ? audiodecoding::probeDurationWithUrl(pathOrUrl, sampleRate, headers)
+              : audiodecoding::probeDurationWithFilePath(pathOrUrl);
+
+          if (result.is_err()) {
+            return [](jsi::Runtime &runtime) -> std::variant<jsi::Value, std::string> {
+              return jsi::Value::null();
+            };
+          }
+
+          return [duration = static_cast<double>(result.unwrap())](
+                     jsi::Runtime &runtime) -> std::variant<jsi::Value, std::string> {
+            return jsi::Value(duration);
           };
-        }
+        });
 
-        return [duration = duration.value()](
-                   jsi::Runtime &runtime) -> std::variant<jsi::Value, std::string> {
-          return jsi::Value(duration);
-        };
-      });
+    return promise;
+  }
 
-  return promise;
+  throw jsi::JSError(runtime, "probeDuration expects an ArrayBuffer or URL/path string.");
 }
 
 } // namespace audioapi

package/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h

@@ -6,15 +6,46 @@
 #include <cstddef>
 #include <cstdio>
 #include <limits>
+#include <map>
 #include <memory>
+#include <string>
 #include <vector>
 
 #include <audioapi/HostObjects/effects/PeriodicWaveHostObject.h>
 #include <audioapi/HostObjects/sources/AudioBufferHostObject.h>
-#include <audioapi/core/utils/AudioDecoding.hpp>
+#include <audioapi/core/utils/AudioDecoding.h>
 #include <audioapi/types/NodeOptions.h>
 
 namespace audioapi::option_parser {
+
+inline std::map<std::string, std::string> parseHttpHeaders(
+    jsi::Runtime &runtime,
+    const jsi::Object &headersObject) {
+  std::map<std::string, std::string> headers;
+  const auto propertyNames = headersObject.getPropertyNames(runtime);
+  const auto count = propertyNames.size(runtime);
+  for (size_t i = 0; i < count; ++i) {
+    const auto keyValue = propertyNames.getValueAtIndex(runtime, i);
+    if (!keyValue.isString()) {
+      continue;
+    }
+    const auto key = keyValue.asString(runtime).utf8(runtime);
+    const auto value = headersObject.getProperty(runtime, key.c_str());
+    if (value.isString()) {
+      headers.emplace(key, value.asString(runtime).utf8(runtime));
+    }
+  }
+  return headers;
+}
+
+inline void mergeHttpHeaders(
+    std::map<std::string, std::string> &target,
+    const std::map<std::string, std::string> &incoming) {
+  for (const auto &[key, value] : incoming) {
+    target[key] = value;
+  }
+}
+
 inline AudioNodeOptions parseAudioNodeOptions(
     jsi::Runtime &runtime,
     const jsi::Object &optionsObject) {
@@ -320,12 +351,29 @@ inline AudioFileSourceOptions parseAudioFileSourceOptions(
 
   auto sourceValue = optionsObject.getProperty(runtime, "source");
   if (sourceValue.isString()) {
-    options.filePath = sourceValue.asString(runtime).utf8(runtime);
-    options.requiresFFmpeg =
-        audiodecoding::pathHasExtension(options.filePath, {".mp4", ".m4a", ".aac", ".m3u8"});
+    const auto path = sourceValue.asString(runtime).utf8(runtime);
+    if (audiodecoding::isHttpUrl(path)) {
+      options.sourceUrl = path;
+      options.requiresFFmpeg = true;
+    } else {
+      options.filePath = path;
+      options.requiresFFmpeg =
+          audiodecoding::pathHasExtension(path, {".mp4", ".m4a", ".aac", ".m3u8"});
+    }
   } else if (sourceValue.isObject()) {
     auto sourceObj = sourceValue.asObject(runtime);
-    if (sourceObj.isArrayBuffer(runtime)) {
+    if (sourceObj.hasProperty(runtime, "uri")) {
+      const auto uriValue = sourceObj.getProperty(runtime, "uri");
+      if (uriValue.isString()) {
+        options.sourceUrl = uriValue.asString(runtime).utf8(runtime);
+        options.requiresFFmpeg = true;
+      }
+      const auto sourceHeadersValue = sourceObj.getProperty(runtime, "headers");
+      if (sourceHeadersValue.isObject()) {
+        mergeHttpHeaders(
+            options.httpHeaders, parseHttpHeaders(runtime, sourceHeadersValue.asObject(runtime)));
+      }
+    } else if (sourceObj.isArrayBuffer(runtime)) {
       auto arrayBuffer = sourceObj.getArrayBuffer(runtime);
       auto *data = arrayBuffer.data(runtime);
       auto size = arrayBuffer.size(runtime);
@@ -336,11 +384,17 @@ inline AudioFileSourceOptions parseAudioFileSourceOptions(
     }
   }
 
+  const auto headersValue = optionsObject.getProperty(runtime, "headers");
+  if (headersValue.isObject()) {
+    mergeHttpHeaders(
+        options.httpHeaders, parseHttpHeaders(runtime, headersValue.asObject(runtime)));
+  }
+
 #if RN_AUDIO_API_FFMPEG_DISABLED
   if (options.requiresFFmpeg) {
     throw jsi::JSError(
         runtime,
-        "AudioFileSourceNode: source format (.mp4, .m4a, .aac, .m3u8) requires FFmpeg, "
+        "AudioFileSourceNode: remote URLs and formats (.mp4, .m4a, .aac, .m3u8) require FFmpeg, "
         "which is disabled in this build.");
   }
 #endif

package/common/cpp/audioapi/core/BaseAudioContext.cpp

@@ -21,7 +21,7 @@
 #include <audioapi/core/sources/StreamerNode.h>
 #endif // RN_AUDIO_API_FFMPEG_DISABLED
 #include <audioapi/core/sources/WorkletSourceNode.h>
-#include <audioapi/core/utils/AudioDecoding.hpp>
+#include <audioapi/core/utils/AudioDecoding.h>
 #include <audioapi/core/utils/AudioGraphManager.h>
 #include <audioapi/core/utils/worklets/SafeIncludes.h>
 #include <audioapi/events/AudioEventHandlerRegistry.h>

package/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp

@@ -43,9 +43,12 @@ AudioFileSourceNode::AudioFileSourceNode(
 
   const bool useFilePath = !options.filePath.empty();
   const bool useData = !options.data.empty();
+  const bool useUrl = !options.sourceUrl.empty();
 
-  if (!useFilePath && !useData) {
-    assert(false && "AudioFileSourceNode requires either a file path or memory data to initialize");
+  if (!useFilePath && !useData && !useUrl) {
+    assert(
+        false &&
+        "AudioFileSourceNode requires a file path, remote URL, or memory data to initialize");
     return;
   }
 
@@ -103,6 +106,8 @@ bool AudioFileSourceNode::initDecoder(
   SeekDecoderDaemonOptions daemonOptions{
       .requiresFFmpeg = options.requiresFFmpeg,
       .filePath = std::move(options.filePath),
+      .sourceUrl = std::move(options.sourceUrl),
+      .httpHeaders = std::move(options.httpHeaders),
       .memoryData = std::move(options.data),
       .contextSampleRate = context->getSampleRate(),
       .loop = options.loop};

package/common/cpp/audioapi/core/utils/AudioDecoding.cpp

@@ -1,4 +1,4 @@
-#include <audioapi/core/utils/AudioDecoding.hpp>
+#include <audioapi/core/utils/AudioDecoding.h>
 #include <audioapi/libs/base64/base64.h>
 #include <audioapi/libs/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/libs/miniaudio/MiniAudioDecoding.h>
@@ -9,8 +9,10 @@
 
 #include <algorithm>
 #include <cctype>
+#include <cmath>
 #include <cstdint>
 #include <cstring>
+#include <map>
 #include <memory>
 #include <string>
 #include <utility>
@@ -108,6 +110,90 @@ bool pathHasExtension(const std::string &path, const std::vector<std::string> &e
       extensions, [&pathLower](const std::string &ext) { return pathLower.ends_with(ext); });
 }
 
+bool isHttpUrl(const std::string &path) {
+  return path.starts_with("http://") || path.starts_with("https://");
+}
+
+bool isValidDuration(float duration) {
+  return duration >= 0.0F && std::isfinite(duration);
+}
+
+AudioDurationResult probeDurationWithFilePath(const std::string &path) {
+  if (needsFFmpegByPath(path)) {
+#if !RN_AUDIO_API_FFMPEG_DISABLED
+    ffmpeg_decoder::FFmpegDecoder decoder;
+    const auto openResult = decoder.openFile(0, path);
+    if (openResult.is_err()) {
+      return Err("Failed to open file with FFmpeg decoder: " + openResult.unwrap_err());
+    }
+    auto result = resolveDurationFromDecoder(decoder);
+    decoder.close();
+    return result;
+#else
+    return Err("FFmpeg is disabled, cannot inspect duration with file path");
+#endif // RN_AUDIO_API_FFMPEG_DISABLED
+  }
+
+  miniaudio_decoder::MiniAudioDecoder decoder;
+  const auto openResult = decoder.openFile(0, path);
+  if (openResult.is_err()) {
+    return Err("Failed to open file with miniaudio decoder: " + openResult.unwrap_err());
+  }
+  auto result = resolveDurationFromDecoder(decoder);
+  decoder.close();
+  return result;
+}
+
+AudioDurationResult probeDurationWithMemory(const void *data, size_t size, int sampleRate) {
+  const int sr = sampleRate != 0 ? sampleRate : 0;
+
+  {
+    miniaudio_decoder::MiniAudioDecoder decoder;
+    const auto openResult = decoder.openMemory(sr, data, size);
+    if (openResult.is_ok()) {
+      auto result = resolveDurationFromDecoder(decoder);
+      decoder.close();
+      if (result.is_ok()) {
+        return result;
+      }
+    }
+  }
+
+#if !RN_AUDIO_API_FFMPEG_DISABLED
+  ffmpeg_decoder::FFmpegDecoder decoder;
+  const auto openResult = decoder.openMemory(sr, data, size);
+  if (openResult.is_err()) {
+    return Err("Failed to probe duration from memory: " + openResult.unwrap_err());
+  }
+  auto result = resolveDurationFromDecoder(decoder);
+  decoder.close();
+  return result;
+#else
+  return Err("Failed to probe duration from memory");
+#endif // RN_AUDIO_API_FFMPEG_DISABLED
+}
+
+AudioDurationResult probeDurationWithUrl(
+    const std::string &url,
+    int sampleRate,
+    const std::map<std::string, std::string> &headers) {
+#if !RN_AUDIO_API_FFMPEG_DISABLED
+  ffmpeg_decoder::FFmpegDecoder decoder;
+  const auto openResult = decoder.openUrl(sampleRate, url, headers);
+  if (openResult.is_err()) {
+    return Err("Failed to open URL with FFmpeg decoder: " + openResult.unwrap_err());
+  }
+  auto result = resolveDurationFromDecoder(decoder);
+  decoder.close();
+  return result;
+#else
+  (void)url;
+  (void)sampleRate;
+  (void)headers;
+  return Err("FFmpeg is disabled, cannot probe duration from URL");
+#endif // RN_AUDIO_API_FFMPEG_DISABLED
+}
+
 AudioBufferResult decodeWithFilePath(const std::string &path, float sampleRate) {
   const int sr = static_cast<int>(sampleRate);
 

package/common/cpp/audioapi/core/utils/{AudioDecoding.hpp → AudioDecoding.h}

@@ -5,15 +5,15 @@
 #include <audioapi/utils/AudioBuffer.hpp>
 #include <audioapi/utils/Result.hpp>
 #include <cstddef>
+#include <map>
 #include <memory>
-#include <optional>
 #include <string>
-#include <type_traits>
 #include <vector>
 
 namespace audioapi::audiodecoding {
 
 using AudioBufferResult = Result<std::shared_ptr<AudioBuffer>, std::string>;
+using AudioDurationResult = Result<float, std::string>;
 
 [[nodiscard]] AudioBufferResult decodeWithFilePath(const std::string &path, float sampleRate);
 [[nodiscard]] AudioBufferResult
@@ -30,6 +30,18 @@ decodeWithMemoryBlock(const void *data, size_t size, float sampleRate);
     const std::string &path,
     const std::vector<std::string> &extensions);
 
+[[nodiscard]] bool isHttpUrl(const std::string &path);
+[[nodiscard]] bool isValidDuration(float duration);
+
+[[nodiscard]] inline AudioDurationResult resolveDurationFromDecoder(
+    decoding::IncrementalAudioDecoder &decoder) {
+  const float duration = decoder.getDurationInSeconds();
+  if (!isValidDuration(duration)) {
+    return Err("Audio duration metadata is unavailable");
+  }
+  return Ok(duration);
+}
+
 [[nodiscard]] inline bool needsFFmpeg(AudioFormat format) {
   return format == AudioFormat::MP4 || format == AudioFormat::M4A || format == AudioFormat::AAC;
 }
@@ -42,15 +54,12 @@ decodeWithMemoryBlock(const void *data, size_t size, float sampleRate);
   return static_cast<float>(static_cast<int16_t>((byte2 << CHAR_BIT) | byte1)) / INT16_MAX;
 }
 
-template <typename D>
-  requires std::is_base_of_v<decoding::IncrementalAudioDecoder, D>
-std::optional<double> probeDuration(const void *data, size_t size, int outputSampleRate) {
-  D decoder;
-  const auto openResult = decoder.openMemory(outputSampleRate, data, size);
-  if (openResult.is_err()) {
-    return std::nullopt;
-  }
-  return static_cast<double>(decoder.getDurationInSeconds());
-}
+[[nodiscard]] AudioDurationResult probeDurationWithFilePath(const std::string &path);
+[[nodiscard]] AudioDurationResult
+probeDurationWithMemory(const void *data, size_t size, int sampleRate = 0);
+[[nodiscard]] AudioDurationResult probeDurationWithUrl(
+    const std::string &url,
+    int sampleRate = 0,
+    const std::map<std::string, std::string> &headers = {});
 
 } // namespace audioapi::audiodecoding

package/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp

@@ -18,7 +18,7 @@ SeekDecoderDaemon::SeekDecoderDaemon(
       commandReceiver_(std::move(commandReceiver)),
       frameSender_(std::move(frameSender)),
       frameReceiverForDrain_(std::move(frameReceiver)) {
-  if (options.requiresFFmpeg) {
+  if (options.requiresFFmpeg || !options.sourceUrl.empty()) {
 #if !RN_AUDIO_API_FFMPEG_DISABLED
     decoder_ = std::make_unique<ffmpeg_decoder::FFmpegDecoder>();
 #endif
@@ -30,9 +30,9 @@ SeekDecoderDaemon::SeekDecoderDaemon(
 
   int contextSampleRate = static_cast<int>(options.contextSampleRate);
 
-  // Check in AudioFileSourceNode constructor ensures that at least one of filePath or memoryData is provided,
-  // so we can attempt to open the decoder with either without additional checks here.
-  if (!options.filePath.empty()) {
+  if (!options.sourceUrl.empty()) {
+    openResult = decoder_->openUrl(contextSampleRate, options.sourceUrl, options.httpHeaders);
+  } else if (!options.filePath.empty()) {
     openResult = decoder_->openFile(contextSampleRate, options.filePath);
   } else {
     openResult = decoder_->openMemory(

package/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.h

@@ -10,6 +10,7 @@
 #include <audioapi/utils/SpscChannel.hpp>
 #include <array>
 #include <atomic>
+#include <map>
 #include <memory>
 #include <optional>
 #include <string>
@@ -21,6 +22,8 @@ struct SeekDecoderDaemonOptions {
   bool requiresFFmpeg;
   // source
   std::string filePath;
+  std::string sourceUrl;
+  std::map<std::string, std::string> httpHeaders;
   std::vector<uint8_t> memoryData;
   // playback
   float contextSampleRate;

package/common/cpp/audioapi/libs/decoding/IncrementalAudioDecoder.h

@@ -3,6 +3,7 @@
 #include <audioapi/utils/Macros.h>
 #include <audioapi/utils/Result.hpp>
 #include <cstddef>
+#include <map>
 #include <string>
 
 namespace audioapi::decoding {
@@ -24,6 +25,16 @@ class IncrementalAudioDecoder {
   /// @return Ok(None) on success or Err(message) on failure.
   [[nodiscard]] virtual DecoderResult openFile(int outputSampleRate, const std::string &path) = 0;
 
+  /// @brief Opens a remote HTTP(S) URL for incremental decoding via FFmpeg.
+  /// @param outputSampleRate The output sample rate.
+  /// @param url The remote URL (http:// or https://).
+  /// @param headers Optional HTTP request headers (e.g. Authorization).
+  /// @return Ok(None) on success or Err(message) on failure.
+  [[nodiscard]] virtual DecoderResult openUrl(
+      int outputSampleRate,
+      const std::string &url,
+      const std::map<std::string, std::string> &headers = {}) = 0;
+
   /// @brief Opens a memory block for decoding.
   /// @param outputSampleRate The output sample rate.
   /// @param data The data to decode.