From 160cd03645b8c3e81858e93e30ef30a008f8f25b Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Mon, 20 Jul 2026 15:16:17 +0200
Subject: [PATCH 01/12] refactor: remove ffmpeg decoding and use OS apis

---
 .../build-compilation-dependencies/SKILL.md   |   2 +
 CLAUDE.md                                     |   2 +-
 .../src/examples/AudioFile/AudioPlayer.ts     |   2 -
 apps/fabric-example/ios/Podfile.lock          |   2 +-
 .../other/disabling-prebuilt-libraries.mdx    |   2 +-
 .../audiodocs/docs/other/runtime-flags.mdx    |   8 +-
 packages/audiodocs/docs/sources/audio-tag.mdx |   2 +-
 packages/audiodocs/docs/utils/decoding.mdx    |   5 +-
 packages/react-native-audio-api/.clangd       |  24 +
 .../react-native-audio-api/RNAudioAPI.podspec |   2 +-
 .../src/main/cpp/audioapi/AndroidDecoding.cpp | 500 ++++++++++++++++++
 .../src/main/cpp/audioapi/AndroidDecoding.h   |  45 ++
 .../src/main/cpp/audioapi/CMakeLists.txt      |   1 +
 .../HostObjects/utils/NodeOptionsParser.h     |  12 +-
 .../core/sources/AudioFileSourceNode.cpp      |   4 -
 .../core/sources/AudioFileSourceNode.h        |   6 +-
 .../cpp/audioapi/core/types/AudioFormat.h     |   8 -
 .../cpp/audioapi/core/utils/AudioDecoding.cpp | 168 +++---
 .../cpp/audioapi/core/utils/AudioDecoding.h   |  13 +-
 .../core/utils/decoding/SeekDecoderDaemon.cpp |  57 +-
 .../core/utils/decoding/SeekDecoderDaemon.h   |   5 +-
 .../decoding/IncrementalAudioDecoder.h        |   0
 .../common/cpp/audioapi/decoding/OSDecoding.h |  26 +
 .../cpp/audioapi/decoding/OsDecoderBase.h     |  66 +++
 .../audioapi/libs/ffmpeg/FFmpegDecoding.cpp   | 148 +-----
 .../cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h |  26 +-
 .../libs/miniaudio/MiniAudioDecoding.h        |   3 +-
 .../ios/audioapi/ios/core/utils/IOSDecoding.h |  46 ++
 .../audioapi/ios/core/utils/IOSDecoding.mm    | 357 +++++++++++++
 .../react-native-audio-api/src/utils/flags.ts |   7 +-
 .../src/utils/remoteHttpSource.ts             |   2 +-
 .../test-app-screen/src/AudioBufferTest.ts    |  53 +-
 packages/test-app-screen/src/AudioTagTest.ts  |  30 +-
 33 files changed, 1273 insertions(+), 361 deletions(-)
 create mode 100644 packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp
 create mode 100644 packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h
 delete mode 100644 packages/react-native-audio-api/common/cpp/audioapi/core/types/AudioFormat.h
 rename packages/react-native-audio-api/common/cpp/audioapi/{libs => }/decoding/IncrementalAudioDecoder.h (100%)
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/OSDecoding.h
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/OsDecoderBase.h
 create mode 100644 packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
 create mode 100644 packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm

diff --git a/.claude/skills/build-compilation-dependencies/SKILL.md b/.claude/skills/build-compilation-dependencies/SKILL.md
index d8868f273..a8ae88792 100644
--- a/.claude/skills/build-compilation-dependencies/SKILL.md
+++ b/.claude/skills/build-compilation-dependencies/SKILL.md
@@ -29,6 +29,8 @@ react-native-audio-api/
 │   │   └── src/main/cpp/audioapi/
 │   │       └── CMakeLists.txt          # Actual Android C++ build target
 │   ├── common/cpp/audioapi/            # Shared C++ (used by all platforms)
+│   │   ├── decoding/                   # Incremental + OS decoder contracts (no external deps)
+│   │   ├── libs/                       # Third-party wrappers (FFmpeg, miniaudio, pffft, …)
 │   │   └── external/                   # Prebuilt binaries per platform
 │   │       ├── android/                # .a static libs (Opus, Ogg, Vorbis, OpenSSL)
 │   │       ├── iphoneos/               # iOS device .a libs
diff --git a/CLAUDE.md b/CLAUDE.md
index aec80112e..63161b2ea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,7 @@ packages/custom-node-generator/    # Code generation tooling
 ### Layers (from JS to hardware)
 
 1. **TypeScript API** (`src/`) — node implementations (`src/core/`), browser passthrough (`src/web-core/`), platform system APIs (`src/system/`), TurboModule specs (`src/specs/`), hooks, events, utils
-2. **C++ Engine** (`common/cpp/audioapi/`) — node engine (`core/`), SIMD DSP (`dsp/`), JSI HostObjects, audio events, prebuilt external libraries (`external/`)
+2. **C++ Engine** (`common/cpp/audioapi/`) — node engine (`core/`), incremental/OS decoding (`decoding/`), SIMD DSP (`dsp/`), JSI HostObjects, audio events, third-party wrappers (`libs/` — FFmpeg, miniaudio, etc.), prebuilt binaries (`external/`)
 3. **Android Native** (`android/`) — CMake + Gradle, Kotlin module, C++ JNI glue (`src/main/cpp/`), Oboe 1.9.3 audio I/O
 4. **iOS Native** (`ios/audioapi/ios/`) — Objective-C++ (`.mm`), CocoaPods (`RNAudioAPI.podspec`), CoreAudio I/O
 
diff --git a/apps/common-app/src/examples/AudioFile/AudioPlayer.ts b/apps/common-app/src/examples/AudioFile/AudioPlayer.ts
index d58d8f962..805a1a918 100644
--- a/apps/common-app/src/examples/AudioFile/AudioPlayer.ts
+++ b/apps/common-app/src/examples/AudioFile/AudioPlayer.ts
@@ -73,8 +73,6 @@ class AudioPlayer {
       }
     };
 
-    this.sourceNode.playbackRate.linearRampToValueAtTime(2, this.audioContext.currentTime + 5);
-
     this.sourceNode.start(
       this.audioContext.currentTime,
       this.currentElapsedTime
diff --git a/apps/fabric-example/ios/Podfile.lock b/apps/fabric-example/ios/Podfile.lock
index 6389ddb14..613b233a4 100644
--- a/apps/fabric-example/ios/Podfile.lock
+++ b/apps/fabric-example/ios/Podfile.lock
@@ -2597,7 +2597,7 @@ SPEC CHECKSUMS:
   ReactCodegen: d07ee3c8db75b43d1cbe479ae6affebf9925c733
   ReactCommon: fe2a3af8975e63efa60f95fca8c34dc85deee360
   ReactNativeDependencies: 4d5ce2683b6d74f7c686bf90a88c7d381295cf3c
-  RNAudioAPI: 6bba1527c091e2702e3d879de7564ef1ccf30a78
+  RNAudioAPI: 8a7e83b96d9be33bad7591400bb21c6e8b119222
   RNAudioWorklets: febe470be646585d9b8b0de320a5fb8684cb012c
   RNGestureHandler: 187c5c7936abf427bc4d22d6c3b1ac80ad1f63c0
   RNReanimated: 3a204af3747842859392545d41d443b9c5e428a3
diff --git a/packages/audiodocs/docs/other/disabling-prebuilt-libraries.mdx b/packages/audiodocs/docs/other/disabling-prebuilt-libraries.mdx
index a3a87ed39..9a96ae731 100644
--- a/packages/audiodocs/docs/other/disabling-prebuilt-libraries.mdx
+++ b/packages/audiodocs/docs/other/disabling-prebuilt-libraries.mdx
@@ -17,7 +17,7 @@ The available flags are independent and can be combined:
 
 | Flag | What it removes | What stops working |
 | :---: | :---- | :---- |
-| `disableFFmpeg` | FFmpeg shared libraries (`libavcodec`, `libavformat`, `libavutil`, `libswresample`) | Streaming, remote playback/metadata, `.aac` / `.mp4` / `.m4a` decode, M4A concat, **Android** non-WAV recording — see [Runtime flags](/docs/other/runtime-flags#where-ffmpeg-is-used) |
+| `disableFFmpeg` | FFmpeg shared libraries (`libavcodec`, `libavformat`, `libavutil`, `libswresample`) | Remote URL streaming / HLS, remote URL metadata, M4A concat, **Android** non-WAV recording — see [Runtime flags](/docs/other/runtime-flags#where-ffmpeg-is-used) |
 | `disableStaticExternalLibs` | Static libs: `libopus`, `libopusfile`, `libogg`, `libvorbis`, `libvorbisenc`, `libvorbisfile` | Decoding `ogg`, `opus`, `oga` files |
 
 :::info
diff --git a/packages/audiodocs/docs/other/runtime-flags.mdx b/packages/audiodocs/docs/other/runtime-flags.mdx
index 7cbe0364b..6383a2418 100644
--- a/packages/audiodocs/docs/other/runtime-flags.mdx
+++ b/packages/audiodocs/docs/other/runtime-flags.mdx
@@ -29,16 +29,14 @@ if (!isFfmpegEnabled()) {
 
 | Area | API | Requires FFmpeg for |
 | :---: | :---: | :---- |
-| Streaming | [`Audio tag`](/docs/sources/audio-tag) | HLS playback |
-| Playback | `createFileSource`, [`<Audio>`](/docs/sources/audio-tag) | Remote URL streaming, HLS (`.m3u8`), local `.mp4` / `.m4a` / `.aac`. Without FFmpeg, remote sources are downloaded and decoded with miniaudio where supported. |
-| Decoding | [`decodeAudioData`](/docs/utils/decoding#decodeaudiodata) | `.aac`, `.mp4`, `.m4a` (and remote URLs for any format) |
+| Streaming | [`Audio tag`](/docs/sources/audio-tag), `createFileSource` | Remote URL streaming (HTTP byte ranges) and HLS (`.m3u8`) |
 | Metadata | [`getAudioDuration`](/docs/utils/decoding#getaudioduration), [`<Audio>`](/docs/sources/audio-tag) `preload="metadata"` | Remote `http(s):` URL duration probing |
 | Recording | [`AudioRecorder`](/docs/inputs/audio-recorder) file output | **Android only:** `M4A`, `FLAC`, and `CAF` (WAV uses miniaudio). iOS uses system AVFoundation instead. |
 | File utils | [`concatAudioFiles`](/docs/utils/file-concatenation#concataudiofiles) | M4A concatenation (WAV uses miniaudio) |
 
-Formats such as `.mp3`, `.wav`, and `.flac` are often handled by miniaudio for **local** decode paths and for **downloaded** remote sources when FFmpeg is disabled.
+Batch decoding ([`decodeAudioData`](/docs/utils/decoding#decodeaudiodata)) uses OS APIs on mobile (and miniaudio for formats like Ogg/Opus) — not FFmpeg. Without FFmpeg, remote progressive sources can still be fully downloaded in JS and decoded that way; HLS and in-place URL streaming remain unavailable.
 
-When `isFfmpegEnabled()` returns `false`, the features in the table above are unavailable or fall back to errors. On **Android**, [`AudioRecorder`](/docs/inputs/audio-recorder) file output is limited to **WAV**.
+When `isFfmpegEnabled()` returns `false`, the streaming/metadata features in the table above are unavailable or fall back to errors. On **Android**, [`AudioRecorder`](/docs/inputs/audio-recorder) file output is limited to **WAV**.
 
 ### Disabling FFmpeg
 
diff --git a/packages/audiodocs/docs/sources/audio-tag.mdx b/packages/audiodocs/docs/sources/audio-tag.mdx
index fbbb78933..315d3e716 100644
--- a/packages/audiodocs/docs/sources/audio-tag.mdx
+++ b/packages/audiodocs/docs/sources/audio-tag.mdx
@@ -168,4 +168,4 @@ const MyAudioTagWrapper : React.FC = () => {
 
 ## Remarks
 
-- **FFmpeg:** HLS and several compressed formats require an FFmpeg build for URL streaming. Without FFmpeg, remote sources are downloaded and decoded with miniaudio where supported. See [Runtime flags](/docs/other/runtime-flags#where-ffmpeg-is-used).
+- **FFmpeg:** Remote URL streaming (HTTP byte ranges) and HLS require an FFmpeg build. Without FFmpeg, remote progressive sources are downloaded fully and decoded with OS APIs / miniaudio where supported. See [Runtime flags](/docs/other/runtime-flags#where-ffmpeg-is-used).
diff --git a/packages/audiodocs/docs/utils/decoding.mdx b/packages/audiodocs/docs/utils/decoding.mdx
index ac39bbfeb..2c4c8b5da 100644
--- a/packages/audiodocs/docs/utils/decoding.mdx
+++ b/packages/audiodocs/docs/utils/decoding.mdx
@@ -23,8 +23,9 @@ Supported file formats:
 - aac
 - m4a
 - mp4
-
-On mobile, `.aac`, `.mp4`, and `.m4a` are decoded with FFmpeg — see [Runtime flags](/docs/other/runtime-flags#where-ffmpeg-is-used) for more info.
+- aif
+- aiff
+- caf (ios)
 :::
 
 ## Methods
diff --git a/packages/react-native-audio-api/.clangd b/packages/react-native-audio-api/.clangd
index e735c6397..c28e3d1f5 100644
--- a/packages/react-native-audio-api/.clangd
+++ b/packages/react-native-audio-api/.clangd
@@ -9,3 +9,27 @@ CompileFlags:
 Diagnostics:
   ClangTidy:
     FastCheckFilter: Loose
+
+# Android: prefer the NDK compile database from a local Gradle/CMake configure.
+# Run common/cpp/clangd/setup-platform-headers.sh after changing NDK / SDK paths.
+---
+If:
+  PathMatch: .*/android/.*\.(c|cc|cpp|cxx|h|hh|hpp|hxx)$
+CompileFlags:
+  CompilationDatabase: android/.cxx/tools/debug/arm64-v8a
+
+# iOS / ObjC++: iPhoneOS SDK (unversioned Xcode symlink) so system frameworks resolve.
+---
+If:
+  PathMatch: .*/ios/.*\.(c|cc|cpp|cxx|h|hh|hpp|hxx|m|mm)$
+CompileFlags:
+  Add:
+    - -xobjective-c++
+    - -std=c++20
+    - -fobjc-arc
+    - --target=arm64-apple-ios15.0
+    - -isysroot
+    - /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk
+    - -F/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks
+    - -Icommon/cpp
+    - -Iios
diff --git a/packages/react-native-audio-api/RNAudioAPI.podspec b/packages/react-native-audio-api/RNAudioAPI.podspec
index ebf5e2ea4..ed96ed58d 100644
--- a/packages/react-native-audio-api/RNAudioAPI.podspec
+++ b/packages/react-native-audio-api/RNAudioAPI.podspec
@@ -56,7 +56,7 @@ Pod::Spec.new do |s|
     end
   end
 
-  s.ios.frameworks = 'Accelerate', 'AVFoundation', 'MediaPlayer'
+  s.ios.frameworks = 'Accelerate', 'AVFoundation', 'AudioToolbox', 'MediaPlayer'
 
   s.prepare_command = <<-CMD
     chmod +x scripts/download-prebuilt-binaries.sh
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp b/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp
new file mode 100644
index 000000000..412b1373c
--- /dev/null
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp
@@ -0,0 +1,500 @@
+#include <audioapi/AndroidDecoding.h>
+
+#include <audioapi/dsp/r8brain/Resampler.hpp>
+#include <audioapi/utils/AudioBuffer.hpp>
+
+#include <media/NdkMediaCodec.h>
+#include <media/NdkMediaExtractor.h>
+#include <media/NdkMediaFormat.h>
+
+#include <unistd.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <map>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace audioapi::android_decoder {
+namespace {
+
+// Codec output PCM encodings (android.media.AudioFormat constants).
+constexpr int kEncodingPcm16 = 2;
+constexpr int kEncodingPcm8 = 3;
+constexpr int kEncodingPcmFloat = 4;
+constexpr int kResampleMaxInFrames = 4096;
+constexpr int64_t kCodecTimeoutUs = 5000;
+// Bail out of the drain loop if MediaCodec keeps saying "try again" after EOS
+// input without ever flagging EOS output (defensive against a stuck codec).
+constexpr int kMaxTryAgainAfterEos = 200;
+
+struct MediaExtractorDeleter {
+  void operator()(AMediaExtractor *extractor) const {
+    if (extractor != nullptr) {
+      AMediaExtractor_delete(extractor);
+    }
+  }
+};
+
+struct MediaCodecDeleter {
+  void operator()(AMediaCodec *codec) const {
+    if (codec != nullptr) {
+      AMediaCodec_stop(codec);
+      AMediaCodec_delete(codec);
+    }
+  }
+};
+
+struct FileDeleter {
+  void operator()(FILE *file) const {
+    if (file != nullptr) {
+      fclose(file);
+    }
+  }
+};
+
+using MediaExtractorPtr = std::unique_ptr<AMediaExtractor, MediaExtractorDeleter>;
+using MediaCodecPtr = std::unique_ptr<AMediaCodec, MediaCodecDeleter>;
+using FilePtr = std::unique_ptr<FILE, FileDeleter>;
+
+} // namespace
+
+// Native reader state, reached through AndroidDecoder::impl_. Kept out of the
+// shared header so NDK types never leak into cross-platform code.
+struct AndroidDecoderState {
+  // Declaration order matters: destroy codec before extractor, and keep the
+  // temp file alive until after the extractor releases its fd (members destroy
+  // in reverse order).
+  FilePtr tempFile;
+  MediaExtractorPtr extractor;
+  MediaCodecPtr codec;
+
+  int nativeSampleRate = 0;
+  int outputRate = 0;
+  int channels = 0;
+  int pcmEncoding = kEncodingPcm16;
+  double durationSeconds = 0.0;
+
+  // Decoded PCM at the codec's native rate, interleaved float, waiting to be
+  // served (no resampling) or fed into the resampler.
+  std::vector<float> nativeLeftover;
+  size_t nativeCursor = 0;
+  // Resampled PCM at the requested output rate, interleaved float.
+  std::vector<float> outLeftover;
+  size_t outCursor = 0;
+
+  bool inputEnded = false;
+  bool outputEnded = false;
+  int tryAgainAfterEos = 0;
+
+  // Present only when native rate differs from the requested output rate.
+  std::unique_ptr<r8b::MultiChannelResampler> resampler;
+  std::unique_ptr<AudioBuffer> resampleIn;
+  std::unique_ptr<AudioBuffer> resampleOut;
+};
+
+namespace {
+
+void compactConsumed(std::vector<float> &buffer, size_t &cursor) {
+  if (cursor == 0) {
+    return;
+  }
+  if (cursor >= buffer.size()) {
+    buffer.clear();
+  } else {
+    buffer.erase(buffer.begin(), buffer.begin() + static_cast<std::ptrdiff_t>(cursor));
+  }
+  cursor = 0;
+}
+
+void appendNativePcm(AndroidDecoderState &state, const uint8_t *bytes, size_t byteCount) {
+  compactConsumed(state.nativeLeftover, state.nativeCursor);
+  auto &pcm = state.nativeLeftover;
+  if (state.pcmEncoding == kEncodingPcmFloat) {
+    const size_t sampleCount = byteCount / sizeof(float);
+    const auto *samples = reinterpret_cast<const float *>(bytes);
+    pcm.insert(pcm.end(), samples, samples + sampleCount);
+    return;
+  }
+  if (state.pcmEncoding == kEncodingPcm8) {
+    for (size_t i = 0; i < byteCount; ++i) {
+      pcm.push_back((static_cast<float>(bytes[i]) - 128.0f) / 128.0f);
+    }
+    return;
+  }
+  const size_t sampleCount = byteCount / sizeof(int16_t);
+  const auto *pcm16 = reinterpret_cast<const int16_t *>(bytes);
+  for (size_t i = 0; i < sampleCount; ++i) {
+    pcm.push_back(static_cast<float>(pcm16[i]) / 32768.0f);
+  }
+}
+
+// Advances the codec one step: feeds at most one input packet and drains at
+// most one output buffer into nativeLeftover. Sets outputEnded at EOS.
+void pumpCodec(AndroidDecoderState &state) {
+  if (state.outputEnded) {
+    return;
+  }
+
+  auto *codec = state.codec.get();
+  auto *extractor = state.extractor.get();
+
+  if (!state.inputEnded) {
+    const ssize_t inIndex = AMediaCodec_dequeueInputBuffer(codec, kCodecTimeoutUs);
+    if (inIndex >= 0) {
+      size_t bufSize = 0;
+      uint8_t *buf = AMediaCodec_getInputBuffer(codec, static_cast<size_t>(inIndex), &bufSize);
+      const ssize_t sampleSize =
+          buf != nullptr ? AMediaExtractor_readSampleData(extractor, buf, bufSize) : -1;
+      if (sampleSize < 0) {
+        AMediaCodec_queueInputBuffer(
+            codec, static_cast<size_t>(inIndex), 0, 0, 0, AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM);
+        state.inputEnded = true;
+      } else {
+        const int64_t pts = AMediaExtractor_getSampleTime(extractor);
+        AMediaCodec_queueInputBuffer(
+            codec, static_cast<size_t>(inIndex), 0, static_cast<size_t>(sampleSize), pts, 0);
+        AMediaExtractor_advance(extractor);
+      }
+    }
+  }
+
+  AMediaCodecBufferInfo info{};
+  const ssize_t outIndex = AMediaCodec_dequeueOutputBuffer(codec, &info, kCodecTimeoutUs);
+  if (outIndex >= 0) {
+    state.tryAgainAfterEos = 0;
+    if (info.size > 0) {
+      size_t outBufSize = 0;
+      uint8_t *outBuf =
+          AMediaCodec_getOutputBuffer(codec, static_cast<size_t>(outIndex), &outBufSize);
+      if (outBuf != nullptr) {
+        appendNativePcm(state, outBuf + info.offset, static_cast<size_t>(info.size));
+      }
+    }
+    AMediaCodec_releaseOutputBuffer(codec, static_cast<size_t>(outIndex), false);
+    if ((info.flags & AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM) != 0) {
+      state.outputEnded = true;
+    }
+  } else if (outIndex == AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED) {
+    AMediaFormat *outFormat = AMediaCodec_getOutputFormat(codec);
+    AMediaFormat_getInt32(outFormat, AMEDIAFORMAT_KEY_SAMPLE_RATE, &state.nativeSampleRate);
+    AMediaFormat_getInt32(outFormat, AMEDIAFORMAT_KEY_CHANNEL_COUNT, &state.channels);
+    if (!AMediaFormat_getInt32(outFormat, "pcm-encoding", &state.pcmEncoding)) {
+      state.pcmEncoding = kEncodingPcm16;
+    }
+    AMediaFormat_delete(outFormat);
+  } else if (outIndex == AMEDIACODEC_INFO_TRY_AGAIN_LATER) {
+    if (state.inputEnded && ++state.tryAgainAfterEos > kMaxTryAgainAfterEos) {
+      state.outputEnded = true;
+    }
+  }
+}
+
+size_t availableFrames(const std::vector<float> &buffer, size_t cursor, int channels) {
+  if (channels <= 0 || cursor >= buffer.size()) {
+    return 0;
+  }
+  return (buffer.size() - cursor) / static_cast<size_t>(channels);
+}
+
+// Pulls native PCM through the resampler, appending output-rate PCM to
+// outLeftover. Returns the number of output frames produced; 0 means true EOF
+// (native stream exhausted). The resampler has warm-up latency and may emit 0
+// frames for a small input block, so we keep feeding until it produces output
+// or the codec is drained — returning 0 early would be misread as end-of-stream
+// by callers (and could trigger a loop-to-start seek).
+size_t produceResampled(AndroidDecoderState &state) {
+  const int ch = state.channels;
+
+  while (true) {
+    while (availableFrames(state.nativeLeftover, state.nativeCursor, ch) == 0 &&
+           !state.outputEnded) {
+      pumpCodec(state);
+    }
+
+    const size_t availIn = availableFrames(state.nativeLeftover, state.nativeCursor, ch);
+    if (availIn == 0) {
+      return 0; // Codec fully drained and no leftover: genuine EOF.
+    }
+
+    const auto inFrames = static_cast<int>(std::min<size_t>(availIn, kResampleMaxInFrames));
+    state.resampleIn->deinterleaveFrom(
+        state.nativeLeftover.data() + state.nativeCursor, static_cast<size_t>(inFrames));
+    state.nativeCursor += static_cast<size_t>(inFrames) * static_cast<size_t>(ch);
+
+    const int outFrames = state.resampler->process(*state.resampleIn, inFrames, *state.resampleOut);
+    if (outFrames <= 0) {
+      // Resampler still warming up: feed more input rather than signalling EOF.
+      continue;
+    }
+
+    compactConsumed(state.outLeftover, state.outCursor);
+    const size_t base = state.outLeftover.size();
+    state.outLeftover.resize(base + static_cast<size_t>(outFrames) * static_cast<size_t>(ch));
+    state.resampleOut->interleaveTo(
+        state.outLeftover.data() + base, static_cast<size_t>(outFrames));
+    return static_cast<size_t>(outFrames);
+  }
+}
+
+// Selects the audio track, starts the codec, reads duration, and builds the
+// resampler when the requested output rate differs from the native rate.
+decoding::DecoderResult configureState(AndroidDecoderState &state, int outputSampleRate) {
+  auto *extractor = state.extractor.get();
+  const int trackCount = AMediaExtractor_getTrackCount(extractor);
+  int audioTrack = -1;
+  AMediaFormat *format = nullptr;
+
+  for (int i = 0; i < trackCount; ++i) {
+    AMediaFormat *candidate = AMediaExtractor_getTrackFormat(extractor, i);
+    const char *mime = nullptr;
+    if (AMediaFormat_getString(candidate, AMEDIAFORMAT_KEY_MIME, &mime) && mime != nullptr &&
+        std::strncmp(mime, "audio/", 6) == 0) {
+      audioTrack = i;
+      format = candidate;
+      break;
+    }
+    AMediaFormat_delete(candidate);
+  }
+
+  if (audioTrack < 0 || format == nullptr) {
+    return Err("AndroidDecoder: no audio track found");
+  }
+
+  if (AMediaExtractor_selectTrack(extractor, audioTrack) != AMEDIA_OK) {
+    AMediaFormat_delete(format);
+    return Err("AndroidDecoder: selectTrack failed");
+  }
+
+  const char *mime = nullptr;
+  AMediaFormat_getString(format, AMEDIAFORMAT_KEY_MIME, &mime);
+  AMediaFormat_getInt32(format, AMEDIAFORMAT_KEY_SAMPLE_RATE, &state.nativeSampleRate);
+  AMediaFormat_getInt32(format, AMEDIAFORMAT_KEY_CHANNEL_COUNT, &state.channels);
+  int64_t durationUs = 0;
+  AMediaFormat_getInt64(format, AMEDIAFORMAT_KEY_DURATION, &durationUs);
+
+  AMediaCodec *codec = AMediaCodec_createDecoderByType(mime != nullptr ? mime : "audio/mp4a-latm");
+  if (codec == nullptr) {
+    AMediaFormat_delete(format);
+    return Err("AndroidDecoder: createDecoderByType failed");
+  }
+  if (AMediaCodec_configure(codec, format, nullptr, nullptr, 0) != AMEDIA_OK) {
+    AMediaCodec_delete(codec);
+    AMediaFormat_delete(format);
+    return Err("AndroidDecoder: configure failed");
+  }
+  AMediaFormat_delete(format);
+
+  if (AMediaCodec_start(codec) != AMEDIA_OK) {
+    AMediaCodec_delete(codec);
+    return Err("AndroidDecoder: start failed");
+  }
+  state.codec.reset(codec);
+
+  if (state.channels <= 0) {
+    state.channels = 1;
+  }
+  if (state.nativeSampleRate <= 0) {
+    state.nativeSampleRate = 44100;
+  }
+
+  state.outputRate = outputSampleRate > 0 ? outputSampleRate : state.nativeSampleRate;
+  state.durationSeconds = durationUs > 0 ? static_cast<double>(durationUs) / 1e6 : 0.0;
+
+  if (state.outputRate != state.nativeSampleRate) {
+    state.resampler = std::make_unique<r8b::MultiChannelResampler>(
+        state.nativeSampleRate, state.outputRate, state.channels, kResampleMaxInFrames);
+    state.resampleIn = std::make_unique<AudioBuffer>(
+        static_cast<size_t>(kResampleMaxInFrames),
+        state.channels,
+        static_cast<float>(state.nativeSampleRate));
+    state.resampleOut = std::make_unique<AudioBuffer>(
+        static_cast<size_t>(std::max(1, state.resampler->getMaxOutLen())),
+        state.channels,
+        static_cast<float>(state.outputRate));
+  }
+
+  return Ok(None);
+}
+
+} // namespace
+
+AndroidDecoder::AndroidDecoder() = default;
+
+AndroidDecoder::~AndroidDecoder() {
+  close();
+}
+
+decoding::DecoderResult AndroidDecoder::openUrl(
+    int /*outputSampleRate*/,
+    const std::string & /*url*/,
+    const std::map<std::string, std::string> & /*headers*/) {
+  return Err("AndroidDecoder::openUrl is not supported (use FFmpeg for remote streams)");
+}
+
+decoding::DecoderResult AndroidDecoder::openFile(int outputSampleRate, const std::string &path) {
+  close();
+  if (path.empty()) {
+    return Err("AndroidDecoder::openFile failed: path is empty");
+  }
+
+  auto state = std::make_unique<AndroidDecoderState>();
+  state->extractor.reset(AMediaExtractor_new());
+  if (state->extractor == nullptr) {
+    return Err("AndroidDecoder::openFile: AMediaExtractor_new failed");
+  }
+
+  if (AMediaExtractor_setDataSource(state->extractor.get(), path.c_str()) != AMEDIA_OK) {
+    return Err("AndroidDecoder::openFile setDataSource failed");
+  }
+
+  auto configured = configureState(*state, outputSampleRate);
+  if (configured.is_err()) {
+    return configured;
+  }
+
+  outputChannels_ = state->channels;
+  outputSampleRate_ = state->outputRate;
+  durationSeconds_ = state->durationSeconds;
+  framePosition_ = 0;
+  impl_ = std::move(state);
+  open_ = true;
+  return Ok(None);
+}
+
+decoding::DecoderResult
+AndroidDecoder::openMemory(int outputSampleRate, const void *data, size_t size) {
+  close();
+  if (data == nullptr || size == 0) {
+    return Err("AndroidDecoder::openMemory failed: empty input");
+  }
+
+  auto state = std::make_unique<AndroidDecoderState>();
+
+  // Use an anonymous temp file + fd. AMediaExtractor_setDataSourceFd is API 21+,
+  // so this path works for minSdk 21/24 without needing AMediaDataSource (API 28).
+  state->tempFile.reset(tmpfile());
+  if (state->tempFile == nullptr || fwrite(data, 1, size, state->tempFile.get()) != size) {
+    return Err("AndroidDecoder::openMemory: temp file write failed");
+  }
+  fflush(state->tempFile.get());
+  const int fd = fileno(state->tempFile.get());
+  if (fd < 0) {
+    return Err("AndroidDecoder::openMemory: fileno failed");
+  }
+
+  state->extractor.reset(AMediaExtractor_new());
+  if (state->extractor == nullptr) {
+    return Err("AndroidDecoder::openMemory: AMediaExtractor_new failed");
+  }
+
+  const media_status_t status =
+      AMediaExtractor_setDataSourceFd(state->extractor.get(), fd, 0, static_cast<off64_t>(size));
+  if (status != AMEDIA_OK) {
+    return Err("AndroidDecoder::openMemory setDataSourceFd failed");
+  }
+
+  auto configured = configureState(*state, outputSampleRate);
+  if (configured.is_err()) {
+    return configured;
+  }
+
+  outputChannels_ = state->channels;
+  outputSampleRate_ = state->outputRate;
+  durationSeconds_ = state->durationSeconds;
+  framePosition_ = 0;
+  impl_ = std::move(state);
+  open_ = true;
+  return Ok(None);
+}
+
+size_t AndroidDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
+  if (!open_ || impl_ == nullptr || outInterleaved == nullptr || frameCount == 0 ||
+      outputChannels_ <= 0) {
+    return 0;
+  }
+
+  auto &state = *impl_;
+  const int ch = outputChannels_;
+  const bool resample = state.resampler != nullptr;
+  size_t filled = 0; // frames
+
+  while (filled < frameCount) {
+    std::vector<float> &served = resample ? state.outLeftover : state.nativeLeftover;
+    size_t &cursor = resample ? state.outCursor : state.nativeCursor;
+
+    const size_t avail = availableFrames(served, cursor, ch);
+    if (avail > 0) {
+      const size_t take = std::min(avail, frameCount - filled);
+      std::memcpy(
+          outInterleaved + filled * static_cast<size_t>(ch),
+          served.data() + cursor,
+          take * static_cast<size_t>(ch) * sizeof(float));
+      cursor += take * static_cast<size_t>(ch);
+      filled += take;
+      continue;
+    }
+
+    if (resample) {
+      if (produceResampled(state) == 0) {
+        break; // EOF: native exhausted and codec ended.
+      }
+    } else {
+      if (state.outputEnded) {
+        break;
+      }
+      pumpCodec(state);
+    }
+  }
+
+  framePosition_ += static_cast<int64_t>(filled);
+  return filled;
+}
+
+decoding::DecoderResult AndroidDecoder::seekToTime(double seconds) {
+  if (!open_ || impl_ == nullptr || impl_->extractor == nullptr) {
+    return Err("AndroidDecoder::seekToTime failed: decoder is not open");
+  }
+  if (!std::isfinite(seconds) || seconds < 0.0) {
+    return Err("AndroidDecoder::seekToTime failed: seconds is not finite");
+  }
+
+  auto &state = *impl_;
+  const auto seekUs = static_cast<int64_t>(std::llround(seconds * 1e6));
+  if (AMediaExtractor_seekTo(state.extractor.get(), seekUs, AMEDIAEXTRACTOR_SEEK_CLOSEST_SYNC) !=
+      AMEDIA_OK) {
+    return Err("AndroidDecoder::seekToTime: AMediaExtractor_seekTo failed");
+  }
+  if (state.codec != nullptr) {
+    AMediaCodec_flush(state.codec.get());
+  }
+
+  state.nativeLeftover.clear();
+  state.nativeCursor = 0;
+  state.outLeftover.clear();
+  state.outCursor = 0;
+  state.inputEnded = false;
+  state.outputEnded = false;
+  state.tryAgainAfterEos = 0;
+
+  // Reset resampler state so pre-seek samples don't smear into the new position.
+  if (state.resampler != nullptr) {
+    state.resampler = std::make_unique<r8b::MultiChannelResampler>(
+        state.nativeSampleRate, state.outputRate, state.channels, kResampleMaxInFrames);
+  }
+
+  framePosition_ =
+      static_cast<int64_t>(std::llround(seconds * static_cast<double>(outputSampleRate_)));
+  return Ok(None);
+}
+
+void AndroidDecoder::releaseImpl() {
+  impl_.reset();
+}
+
+} // namespace audioapi::android_decoder
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h b/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h
new file mode 100644
index 000000000..f1e1b19e6
--- /dev/null
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h
@@ -0,0 +1,45 @@
+#pragma once
+
+#include <audioapi/decoding/OsDecoderBase.h>
+#include <audioapi/utils/Macros.h>
+
+#include <cstddef>
+#include <map>
+#include <memory>
+#include <string>
+
+namespace audioapi::android_decoder {
+
+struct AndroidDecoderState;
+
+/**
+ * Android MediaExtractor + MediaCodec incremental decoder.
+ *
+ * Opens local files or in-memory buffers and pulls interleaved float PCM on
+ * demand. `openUrl` / HLS are not supported (callers keep those on FFmpeg).
+ */
+class AndroidDecoder : public OsDecoderBase {
+ public:
+  AndroidDecoder();
+  ~AndroidDecoder() override;
+  DELETE_COPY_AND_MOVE(AndroidDecoder);
+
+  [[nodiscard]] decoding::DecoderResult openFile(int outputSampleRate, const std::string &path)
+      override;
+  [[nodiscard]] decoding::DecoderResult
+  openMemory(int outputSampleRate, const void *data, size_t size) override;
+  [[nodiscard]] decoding::DecoderResult openUrl(
+      int outputSampleRate,
+      const std::string &url,
+      const std::map<std::string, std::string> &headers = {}) override;
+  [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
+  [[nodiscard]] decoding::DecoderResult seekToTime(double seconds) override;
+
+ private:
+  void releaseImpl() override;
+
+  // Opaque NDK state (defined in AndroidDecoding.cpp).
+  std::unique_ptr<AndroidDecoderState> impl_;
+};
+
+} // namespace audioapi::android_decoder
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/CMakeLists.txt b/packages/react-native-audio-api/android/src/main/cpp/audioapi/CMakeLists.txt
index 04d808875..7be6ed2d9 100644
--- a/packages/react-native-audio-api/android/src/main/cpp/audioapi/CMakeLists.txt
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/CMakeLists.txt
@@ -102,6 +102,7 @@ set(LINK_LIBRARIES
   fbjni::fbjni
   android
   log
+  mediandk
   oboe::oboe
 )
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
index f1d10866d..966d16ebe 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
@@ -348,11 +348,12 @@ inline AudioFileSourceOptions parseAudioFileSourceOptions(
     const auto path = sourceValue.asString(runtime).utf8(runtime);
     if (audiodecoding::isHttpUrl(path)) {
       options.sourceUrl = path;
+      // Remote progressive / HLS streaming uses FFmpeg's HTTP demuxer.
       options.requiresFFmpeg = true;
     } else {
       options.filePath = path;
-      options.requiresFFmpeg =
-          audiodecoding::pathHasExtension(path, {".mp4", ".m4a", ".aac", ".m3u8"});
+      // Local HLS playlists still need FFmpeg; other local formats use OS/miniaudio.
+      options.requiresFFmpeg = audiodecoding::pathHasExtension(path, {".m3u8"});
     }
   } else if (sourceValue.isObject()) {
     auto sourceObj = sourceValue.asObject(runtime);
@@ -371,10 +372,9 @@ inline AudioFileSourceOptions parseAudioFileSourceOptions(
       auto arrayBuffer = sourceObj.getArrayBuffer(runtime);
       auto *data = arrayBuffer.data(runtime);
       auto size = arrayBuffer.size(runtime);
-      auto format = audiodecoding::detectAudioFormat(data, size);
-      options.requiresFFmpeg = format == AudioFormat::MP4 || format == AudioFormat::M4A ||
-          format == AudioFormat::AAC || format == AudioFormat::M3U8;
       options.data = std::vector<uint8_t>(data, data + size);
+      // In-memory sources decode via OS / miniaudio — never FFmpeg.
+      options.requiresFFmpeg = false;
     }
   }
 
@@ -388,7 +388,7 @@ inline AudioFileSourceOptions parseAudioFileSourceOptions(
   if (options.requiresFFmpeg) {
     throw jsi::JSError(
         runtime,
-        "AudioFileSourceNode: remote URLs and formats (.mp4, .m4a, .aac, .m3u8) require FFmpeg, "
+        "AudioFileSourceNode: remote URL streaming and HLS (.m3u8) require FFmpeg, "
         "which is disabled in this build.");
   }
 #endif
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
index 03971d8f8..5e22978da 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
@@ -20,10 +20,6 @@
 #include <memory>
 #include <utility>
 
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-#include <audioapi/libs/ffmpeg/FFmpegDecoding.h>
-#endif // RN_AUDIO_API_FFMPEG_DISABLED
-
 namespace audioapi {
 
 AudioFileSourceNode::AudioFileSourceNode(
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
index c38434494..d01d534dd 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
@@ -3,16 +3,12 @@
 #include <audioapi/core/AudioNode.h>
 #include <audioapi/core/sources/AudioScheduledSourceNode.h>
 #include <audioapi/core/utils/decoding/SeekDecoderDaemon.h>
+#include <audioapi/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/dsp/WsolaTimeStretcher.h>
-#include <audioapi/libs/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/types/NodeOptions.h>
 #include <audioapi/utils/events/PositionChangedDispatcher.h>
 #include <cstddef>
 #include <thread>
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-#include <audioapi/libs/ffmpeg/FFmpegDecoding.h>
-#endif // RN_AUDIO_API_FFMPEG_DISABLED
-#include <audioapi/libs/miniaudio/MiniAudioDecoding.h>
 
 #include <array>
 #include <atomic>
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/types/AudioFormat.h b/packages/react-native-audio-api/common/cpp/audioapi/core/types/AudioFormat.h
deleted file mode 100644
index f13a26c8d..000000000
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/types/AudioFormat.h
+++ /dev/null
@@ -1,8 +0,0 @@
-#pragma once
-
-#include <cstdint>
-
-namespace audioapi {
-
-enum class AudioFormat : uint8_t { UNKNOWN, WAV, OGG, FLAC, AAC, MP3, M4A, MP4, MOV, M3U8 };
-} // namespace audioapi
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
index 47188d375..ccd0f9dcd 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
@@ -1,6 +1,7 @@
 #include <audioapi/core/utils/AudioDecoding.h>
+#include <audioapi/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/decoding/OSDecoding.h>
 #include <audioapi/libs/base64/base64.h>
-#include <audioapi/libs/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/libs/miniaudio/MiniAudioDecoding.h>
 
 #if !RN_AUDIO_API_FFMPEG_DISABLED
@@ -53,54 +54,6 @@ AudioBufferResult decodeAll(decoding::IncrementalAudioDecoder &decoder) {
   return Ok(std::move(audioBuffer));
 }
 
-// NOLINTBEGIN(readability-magic-numbers, cppcoreguidelines-avoid-magic-numbers)
-AudioFormat detectAudioFormat(const void *data, size_t size) {
-  if (size < 12) {
-    return AudioFormat::UNKNOWN;
-  }
-  const auto *bytes = static_cast<const unsigned char *>(data);
-
-  // WAV/RIFF
-  if (std::memcmp(bytes, "RIFF", 4) == 0 && std::memcmp(bytes + 8, "WAVE", 4) == 0) {
-    return AudioFormat::WAV;
-  }
-
-  // OGG
-  if (std::memcmp(bytes, "OggS", 4) == 0) {
-    return AudioFormat::OGG;
-  }
-
-  // FLAC
-  if (std::memcmp(bytes, "fLaC", 4) == 0) {
-    return AudioFormat::FLAC;
-  }
-
-  // AAC starts with 0xFF 0xF1 or 0xFF 0xF9
-  if (bytes[0] == 0xFF && (bytes[1] & 0xF6) == 0xF0) {
-    return AudioFormat::AAC;
-  }
-
-  // MP3: "ID3" or 11-bit frame sync (0xFF 0xE0)
-  if (std::memcmp(bytes, "ID3", 3) == 0) {
-    return AudioFormat::MP3;
-  }
-  if (bytes[0] == 0xFF && (bytes[1] & 0xE0) == 0xE0) {
-    return AudioFormat::MP3;
-  }
-
-  if (std::memcmp(bytes + 4, "ftyp", 4) == 0) {
-    if (std::memcmp(bytes + 8, "M4A ", 4) == 0) {
-      return AudioFormat::M4A;
-    }
-    if (std::memcmp(bytes + 8, "qt  ", 4) == 0) {
-      return AudioFormat::MOV;
-    }
-    return AudioFormat::MP4;
-  }
-  return AudioFormat::UNKNOWN;
-}
-// NOLINTEND(readability-magic-numbers, cppcoreguidelines-avoid-magic-numbers)
-
 bool pathHasExtension(const std::string &path, const std::vector<std::string> &extensions) {
   std::string pathLower = path;
   std::ranges::transform(pathLower, pathLower.begin(), [](unsigned char c) {
@@ -119,64 +72,72 @@ bool isValidDuration(float 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());
+#if RN_AUDIO_API_HAS_OS_DECODER
+  {
+    os_decoder::Decoder platformDecoder;
+    const auto platformOpen = platformDecoder.openFile(0, path);
+    if (platformOpen.is_ok()) {
+      auto result = resolveDurationFromDecoder(platformDecoder);
+      platformDecoder.close();
+      if (result.is_ok()) {
+        return result;
+      }
+    } else {
+      platformDecoder.close();
     }
-    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
   }
+#endif // RN_AUDIO_API_HAS_OS_DECODER
 
   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());
+    return Err("Cannot read duration: file could not be decoded");
   }
   auto result = resolveDurationFromDecoder(decoder);
   decoder.close();
+  if (result.is_err()) {
+    return Err("Cannot read duration: file could not be decoded");
+  }
   return result;
 }
 
 AudioDurationResult probeDurationWithMemory(const void *data, size_t size, int sampleRate) {
   const int sr = sampleRate != 0 ? sampleRate : 0;
 
+#if RN_AUDIO_API_HAS_OS_DECODER
   {
-    miniaudio_decoder::MiniAudioDecoder decoder;
-    const auto openResult = decoder.openMemory(sr, data, size);
-    if (openResult.is_ok()) {
-      auto result = resolveDurationFromDecoder(decoder);
-      decoder.close();
+    os_decoder::Decoder platformDecoder;
+    const auto platformOpen = platformDecoder.openMemory(sr, data, size);
+    if (platformOpen.is_ok()) {
+      auto result = resolveDurationFromDecoder(platformDecoder);
+      platformDecoder.close();
       if (result.is_ok()) {
         return result;
       }
+    } else {
+      platformDecoder.close();
     }
   }
+#endif // RN_AUDIO_API_HAS_OS_DECODER
 
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-  ffmpeg_decoder::FFmpegDecoder decoder;
+  miniaudio_decoder::MiniAudioDecoder decoder;
   const auto openResult = decoder.openMemory(sr, data, size);
   if (openResult.is_err()) {
-    return Err("Failed to probe duration from memory: " + openResult.unwrap_err());
+    return Err("Cannot read duration: audio data could not be decoded");
   }
   auto result = resolveDurationFromDecoder(decoder);
   decoder.close();
+  if (result.is_err()) {
+    return Err("Cannot read duration: audio data could not be decoded");
+  }
   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) {
+  // Remote URL duration probing uses FFmpeg's HTTP/HLS demuxer (byte ranges).
 #if !RN_AUDIO_API_FFMPEG_DISABLED
   ffmpeg_decoder::FFmpegDecoder decoder;
   const auto openResult = decoder.openUrl(sampleRate, url, headers);
@@ -197,57 +158,64 @@ AudioDurationResult probeDurationWithUrl(
 AudioBufferResult decodeWithFilePath(const std::string &path, float sampleRate) {
   const int sr = static_cast<int>(sampleRate);
 
-  if (needsFFmpegByPath(path)) {
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-    ffmpeg_decoder::FFmpegDecoder decoder;
-    const auto openResult = decoder.openFile(sr, path);
-    if (openResult.is_err()) {
-      return Err("Failed to open file with FFmpeg decoder: " + openResult.unwrap_err());
+#if RN_AUDIO_API_HAS_OS_DECODER
+  {
+    os_decoder::Decoder platformDecoder;
+    const auto platformOpen = platformDecoder.openFile(sr, path);
+    if (platformOpen.is_ok()) {
+      auto result = decodeAll(platformDecoder);
+      platformDecoder.close();
+      if (result.is_ok()) {
+        return result;
+      }
+    } else {
+      platformDecoder.close();
     }
-    auto result = decodeAll(decoder);
-    decoder.close();
-    return result;
-#else
-    return Err("FFmpeg is disabled, cannot decode with file path");
-#endif // RN_AUDIO_API_FFMPEG_DISABLED
   }
+#endif // RN_AUDIO_API_HAS_OS_DECODER
 
   miniaudio_decoder::MiniAudioDecoder decoder;
   const auto openResult = decoder.openFile(sr, path);
   if (openResult.is_err()) {
-    return Err("Failed to open file with miniaudio decoder: " + openResult.unwrap_err());
+    return Err("Cannot decode file: unsupported or invalid audio format");
   }
   auto result = decodeAll(decoder);
   decoder.close();
+  if (result.is_err()) {
+    return Err("Cannot decode file: unsupported or invalid audio format");
+  }
   return result;
 }
 
 AudioBufferResult decodeWithMemoryBlock(const void *data, size_t size, float sampleRate) {
   const int sr = static_cast<int>(sampleRate);
-  const AudioFormat format = detectAudioFormat(data, size);
 
-  if (needsFFmpeg(format)) {
-#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 open memory block with FFmpeg decoder: " + openResult.unwrap_err());
+#if RN_AUDIO_API_HAS_OS_DECODER
+  {
+    os_decoder::Decoder platformDecoder;
+    const auto platformOpen = platformDecoder.openMemory(sr, data, size);
+    if (platformOpen.is_ok()) {
+      auto result = decodeAll(platformDecoder);
+      platformDecoder.close();
+      if (result.is_ok()) {
+        return result;
+      }
+    } else {
+      platformDecoder.close();
     }
-    auto result = decodeAll(decoder);
-    decoder.close();
-    return result;
-#else
-    return Err("FFmpeg is disabled, cannot decode memory block");
-#endif // RN_AUDIO_API_FFMPEG_DISABLED
   }
+#endif // RN_AUDIO_API_HAS_OS_DECODER
 
   miniaudio_decoder::MiniAudioDecoder decoder;
   const auto openResult = decoder.openMemory(sr, data, size);
   if (openResult.is_err()) {
-    return Err("Failed to open memory block with miniaudio decoder: " + openResult.unwrap_err());
+    return Err("Cannot decode audio data: unsupported or invalid audio format");
   }
   auto result = decodeAll(decoder);
   decoder.close();
+  if (result.is_err()) {
+    return Err("Cannot decode audio data: unsupported or invalid audio format");
+  }
   return result;
 }
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.h
index 3518142ba..026fd5c00 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.h
@@ -1,7 +1,6 @@
 #pragma once
 
-#include <audioapi/core/types/AudioFormat.h>
-#include <audioapi/libs/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/utils/AudioBuffer.hpp>
 #include <audioapi/utils/Result.hpp>
 #include <cstddef>
@@ -24,8 +23,6 @@ decodeWithMemoryBlock(const void *data, size_t size, float sampleRate);
     int inputChannelCount,
     bool interleaved);
 
-[[nodiscard]] AudioFormat detectAudioFormat(const void *data, size_t size);
-
 [[nodiscard]] bool pathHasExtension(
     const std::string &path,
     const std::vector<std::string> &extensions);
@@ -42,14 +39,6 @@ decodeWithMemoryBlock(const void *data, size_t size, float sampleRate);
   return Ok(duration);
 }
 
-[[nodiscard]] inline bool needsFFmpeg(AudioFormat format) {
-  return format == AudioFormat::MP4 || format == AudioFormat::M4A || format == AudioFormat::AAC;
-}
-
-[[nodiscard]] inline bool needsFFmpegByPath(const std::string &path) {
-  return pathHasExtension(path, {".mp4", ".m4a", ".aac"});
-}
-
 [[nodiscard]] inline float uint8ToFloat(uint8_t byte1, uint8_t byte2) {
   return static_cast<float>(static_cast<int16_t>((byte2 << CHAR_BIT) | byte1)) / INT16_MAX;
 }
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp
index 503bd4a48..a0b53ebf5 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp
@@ -1,12 +1,28 @@
 #include <audioapi/core/utils/decoding/SeekDecoderDaemon.h>
+#include <audioapi/decoding/OSDecoding.h>
 
-#include <algorithm>
-#include <cmath>
 #include <memory>
 #include <thread>
 #include <utility>
 
 namespace audioapi {
+namespace {
+
+decoding::DecoderResult openWithDecoder(
+    decoding::IncrementalAudioDecoder &decoder,
+    const SeekDecoderDaemonOptions &options,
+    int contextSampleRate) {
+  if (!options.sourceUrl.empty()) {
+    return decoder.openUrl(contextSampleRate, options.sourceUrl, options.httpHeaders);
+  }
+  if (!options.filePath.empty()) {
+    return decoder.openFile(contextSampleRate, options.filePath);
+  }
+  return decoder.openMemory(
+      contextSampleRate, options.memoryData.data(), options.memoryData.size());
+}
+
+} // namespace
 
 SeekDecoderDaemon::SeekDecoderDaemon(
     SeekDecoderDaemonOptions options,
@@ -18,29 +34,34 @@ SeekDecoderDaemon::SeekDecoderDaemon(
       commandReceiver_(std::move(commandReceiver)),
       frameSender_(std::move(frameSender)),
       frameReceiverForDrain_(std::move(frameReceiver)) {
-  if (options.requiresFFmpeg || !options.sourceUrl.empty()) {
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-    decoder_ = std::make_unique<ffmpeg_decoder::FFmpegDecoder>();
-#endif
-  } else {
-    decoder_ = std::make_unique<miniaudio_decoder::MiniAudioDecoder>();
-  }
-
+  const int contextSampleRate = static_cast<int>(options.contextSampleRate);
   decoding::DecoderResult openResult = Err("Failed to initialize decoder");
 
-  int contextSampleRate = static_cast<int>(options.contextSampleRate);
-
+  // Remote HTTP(S) / HLS: FFmpeg owns network demux (byte ranges + playlists).
   if (!options.sourceUrl.empty()) {
-    openResult = decoder_->openUrl(contextSampleRate, options.sourceUrl, options.httpHeaders);
-  } else if (!options.filePath.empty()) {
-    openResult = decoder_->openFile(contextSampleRate, options.filePath);
+#if !RN_AUDIO_API_FFMPEG_DISABLED
+    decoder_ = std::make_unique<ffmpeg_decoder::FFmpegDecoder>();
+    openResult = openWithDecoder(*decoder_, options, contextSampleRate);
+#endif
   } else {
-    openResult = decoder_->openMemory(
-        contextSampleRate, options.memoryData.data(), options.memoryData.size());
+#if RN_AUDIO_API_HAS_OS_DECODER
+    decoder_ = std::make_unique<os_decoder::Decoder>();
+    openResult = openWithDecoder(*decoder_, options, contextSampleRate);
+
+    if (openResult.is_err()) {
+      decoder_->close();
+#endif // RN_AUDIO_API_HAS_OS_DECODER
+      decoder_ = std::make_unique<miniaudio_decoder::MiniAudioDecoder>();
+      openResult = openWithDecoder(*decoder_, options, contextSampleRate);
+#if RN_AUDIO_API_HAS_OS_DECODER
+    }
+#endif // RN_AUDIO_API_HAS_OS_DECODER
   }
 
   if (openResult.is_err()) {
-    decoder_->close();
+    if (decoder_) {
+      decoder_->close();
+    }
     sharedState_->isDaemonRunning.store(false, std::memory_order_release);
     return;
   }
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.h b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.h
index 76018a0d5..617958746 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.h
@@ -1,8 +1,8 @@
 #pragma once
 
 #include <audioapi/core/utils/Constants.h>
+#include <audioapi/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/dsp/WsolaTimeStretcher.h>
-#include <audioapi/libs/decoding/IncrementalAudioDecoder.h>
 #if !RN_AUDIO_API_FFMPEG_DISABLED
 #include <audioapi/libs/ffmpeg/FFmpegDecoding.h>
 #endif // RN_AUDIO_API_FFMPEG_DISABLED
@@ -91,7 +91,8 @@ inline constexpr auto SLEEP_DURATION_ON_FULL = std::chrono::milliseconds(10);
 
 namespace audioapi {
 
-/// @brief SeekDecoderDaemon is a dedicated thread worker that manages an audio decoder instance (FFmpeg or MiniAudio).
+/// @brief SeekDecoderDaemon is a dedicated thread worker that manages an audio
+/// decoder instance (FFmpeg for remote URLs/HLS; OS or MiniAudio for local).
 /// It listens for seek commands from the JS thread, performs seeks on the decoder,
 /// decodes audio frames, and sends decoded planar audio data back to the audio thread via a lock-free SPSC channel.
 class SeekDecoderDaemon {
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/decoding/IncrementalAudioDecoder.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h
similarity index 100%
rename from packages/react-native-audio-api/common/cpp/audioapi/libs/decoding/IncrementalAudioDecoder.h
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/OSDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/OSDecoding.h
new file mode 100644
index 000000000..138015d27
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/OSDecoding.h
@@ -0,0 +1,26 @@
+#pragma once
+
+/**
+ * Selects the OS-native incremental decoder for the current mobile target.
+ *
+ *   - Android → AndroidDecoder
+ *   - iOS     → IOSDecoder
+ *
+ * Not available on desktop / unit-test builds (RN_AUDIO_API_TEST).
+ */
+
+#if defined(__ANDROID__)
+#include <audioapi/AndroidDecoding.h>
+#define RN_AUDIO_API_HAS_OS_DECODER 1
+namespace audioapi::os_decoder {
+using Decoder = android_decoder::AndroidDecoder;
+} // namespace audioapi::os_decoder
+#elif defined(__APPLE__) && !defined(RN_AUDIO_API_TEST)
+#include <audioapi/ios/core/utils/IOSDecoding.h>
+#define RN_AUDIO_API_HAS_OS_DECODER 1
+namespace audioapi::os_decoder {
+using Decoder = ios_decoder::IOSDecoder;
+} // namespace audioapi::os_decoder
+#else
+#define RN_AUDIO_API_HAS_OS_DECODER 0
+#endif
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/OsDecoderBase.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/OsDecoderBase.h
new file mode 100644
index 000000000..728adbb85
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/OsDecoderBase.h
@@ -0,0 +1,66 @@
+#pragma once
+
+#include <audioapi/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/utils/Macros.h>
+
+#include <cstdint>
+
+namespace audioapi {
+
+/**
+ * Shared open-state for OS-native incremental decoders (iOS / Android).
+ *
+ * Owns the common metadata reset by `close()`; subclasses release platform
+ * resources in `releaseImpl()` (e.g. `impl_.reset()`).
+ */
+class OsDecoderBase : public decoding::IncrementalAudioDecoder {
+ public:
+  OsDecoderBase() = default;
+  ~OsDecoderBase() override = default;
+  DELETE_COPY_AND_MOVE(OsDecoderBase);
+
+  void close() final {
+    releaseImpl();
+    outputChannels_ = 0;
+    outputSampleRate_ = 0;
+    durationSeconds_ = 0.0;
+    framePosition_ = 0;
+    open_ = false;
+  }
+
+  [[nodiscard]] bool isOpen() const final {
+    return open_;
+  }
+
+  [[nodiscard]] int outputChannels() const final {
+    return outputChannels_;
+  }
+
+  [[nodiscard]] int outputSampleRate() const final {
+    return outputSampleRate_;
+  }
+
+  [[nodiscard]] float getDurationInSeconds() const final {
+    return static_cast<float>(durationSeconds_);
+  }
+
+  [[nodiscard]] float getCurrentPositionInSeconds() const final {
+    if (outputSampleRate_ <= 0) {
+      return 0.0f;
+    }
+    return static_cast<float>(
+        static_cast<double>(framePosition_) / static_cast<double>(outputSampleRate_));
+  }
+
+ protected:
+  /// Drop platform-native decoder resources (ExtAudioFile / MediaCodec, etc.).
+  virtual void releaseImpl() = 0;
+
+  int outputChannels_ = 0;
+  int outputSampleRate_ = 0;
+  double durationSeconds_ = 0.0;
+  int64_t framePosition_ = 0;
+  bool open_ = false;
+};
+
+} // namespace audioapi
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp
index 6a762079f..ce442a45a 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp
@@ -65,40 +65,6 @@ std::string buildFfmpegHttpHeaders(const std::map<std::string, std::string> &hea
 
 } // namespace
 
-int read_packet(void *opaque, uint8_t *buf, int buf_size) {
-  auto *ctx = static_cast<MemoryIOContext *>(opaque);
-  const size_t size = ctx->data.size();
-  if (ctx->pos >= size) {
-    return AVERROR_EOF;
-  }
-  int n = std::min(buf_size, static_cast<int>(size - ctx->pos));
-  memcpy(buf, ctx->data.data() + ctx->pos, n);
-  ctx->pos += static_cast<size_t>(n);
-  return n;
-}
-
-int64_t seek_packet(void *opaque, int64_t offset, int whence) {
-  auto *ctx = static_cast<MemoryIOContext *>(opaque);
-  const size_t size = ctx->data.size();
-  switch (whence) {
-    case SEEK_SET:
-      ctx->pos = static_cast<size_t>(offset);
-      break;
-    case SEEK_CUR:
-      ctx->pos += static_cast<size_t>(offset);
-      break;
-    case SEEK_END:
-      ctx->pos = size + static_cast<size_t>(offset);
-      break;
-    case AVSEEK_SIZE:
-      return static_cast<int64_t>(size);
-    default:
-      return AVERROR(EINVAL);
-  }
-  ctx->pos = std::min(ctx->pos, size);
-  return static_cast<int64_t>(ctx->pos);
-}
-
 int findAudioStreamIndex(AVFormatContext *fmt_ctx) {
   for (unsigned i = 0; i < fmt_ctx->nb_streams; i++) {
     if (fmt_ctx->streams[i]->codecpar->codec_type == AVMEDIA_TYPE_AUDIO) {
@@ -165,10 +131,6 @@ void FFmpegDecoder::close() {
   if (fmt_ctx_ != nullptr) {
     avformat_close_input(&fmt_ctx_);
   }
-  if (avio_ctx_ != nullptr) {
-    avio_context_free(&avio_ctx_);
-  }
-  mem_io_.reset();
   leftover_.clear();
   leftover_offset_ = 0;
   audio_stream_index_ = -1;
@@ -305,50 +267,9 @@ decoding::DecoderResult FFmpegDecoder::openUrl(
 }
 
 decoding::DecoderResult
-FFmpegDecoder::openMemory(int outputSampleRate, const void *data, size_t size) {
-  close();
-  if (data == nullptr || size == 0) {
-    return Err("FFmpegDecoder::openMemory failed: input data is empty");
-  }
-  mem_io_ = std::make_unique<MemoryIOContext>();
-  mem_io_->data.assign(
-      static_cast<const uint8_t *>(data), static_cast<const uint8_t *>(data) + size);
-  mem_io_->pos = 0;
-
-  auto *io_buf = static_cast<uint8_t *>(av_malloc(decoding::IncrementalAudioDecoder::CHUNK_SIZE));
-  if (io_buf == nullptr) {
-    close();
-    return Err("FFmpegDecoder::openMemory failed: av_malloc returned null");
-  }
-  avio_ctx_ = avio_alloc_context(
-      io_buf,
-      static_cast<int>(decoding::IncrementalAudioDecoder::CHUNK_SIZE),
-      0,
-      mem_io_.get(),
-      read_packet,
-      nullptr,
-      seek_packet);
-  if (avio_ctx_ == nullptr) {
-    av_free(io_buf);
-    mem_io_.reset();
-    return Err("FFmpegDecoder::openMemory failed: avio_alloc_context returned null");
-  }
-
-  fmt_ctx_ = avformat_alloc_context();
-  if (fmt_ctx_ == nullptr) {
-    close();
-    return Err("FFmpegDecoder::openMemory failed: avformat_alloc_context returned null");
-  }
-  fmt_ctx_->pb = avio_ctx_;
-
-  const int openInputResult = avformat_open_input(&fmt_ctx_, nullptr, nullptr, nullptr);
-  if (openInputResult < 0) {
-    close();
-    return Err(
-        "FFmpegDecoder::openMemory failed: avformat_open_input failed: " +
-        parseFFmpegError(openInputResult));
-  }
-  return initializeDecodedStreams(outputSampleRate, "FFmpegDecoder::openMemory");
+FFmpegDecoder::openMemory(int /*outputSampleRate*/, const void * /*data*/, size_t /*size*/) {
+  // Batch / in-memory decode is owned by OS and miniaudio; FFmpeg is for remote URLs.
+  return Err("FFmpegDecoder::openMemory is not supported (use OS or miniaudio for memory decode)");
 }
 
 void FFmpegDecoder::appendFrameResampled(AVFrame *frame) {
@@ -544,63 +465,6 @@ size_t FFmpegDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
   return delivered;
 }
 
-static std::shared_ptr<AudioBuffer>
-buildAudioBufferFromInterleaved(std::vector<float> &interleaved, int channels, int sample_rate) {
-  if (interleaved.empty() || channels <= 0) {
-    return nullptr;
-  }
-  size_t frames = interleaved.size() / static_cast<size_t>(channels);
-  auto buf = std::make_shared<AudioBuffer>(frames, channels, static_cast<float>(sample_rate));
-  buf->deinterleaveFrom(interleaved.data(), frames);
-  return buf;
-}
-
-std::shared_ptr<AudioBuffer> decodeWithFilePath(const std::string &path, int sample_rate) {
-  FFmpegDecoder dec;
-  const auto openResult = dec.openFile(sample_rate, path);
-  if (openResult.is_err()) {
-    return nullptr;
-  }
-  std::vector<float> acc;
-  std::vector<float> tmp(
-      decoding::IncrementalAudioDecoder::CHUNK_SIZE *
-      static_cast<size_t>(std::max(1, dec.outputChannels())));
-  while (true) {
-    size_t n = dec.readPcmFrames(tmp.data(), decoding::IncrementalAudioDecoder::CHUNK_SIZE);
-    if (n == 0) {
-      break;
-    }
-    acc.insert(
-        acc.end(),
-        tmp.begin(),
-        tmp.begin() + static_cast<ptrdiff_t>(n * static_cast<size_t>(dec.outputChannels())));
-  }
-  return buildAudioBufferFromInterleaved(acc, dec.outputChannels(), dec.outputSampleRate());
-}
-
-std::shared_ptr<AudioBuffer> decodeWithMemoryBlock(const void *data, size_t size, int sample_rate) {
-  FFmpegDecoder dec;
-  const auto openResult = dec.openMemory(sample_rate, data, size);
-  if (openResult.is_err()) {
-    return nullptr;
-  }
-  std::vector<float> acc;
-  std::vector<float> tmp(
-      decoding::IncrementalAudioDecoder::CHUNK_SIZE *
-      static_cast<size_t>(std::max(1, dec.outputChannels())));
-  while (true) {
-    size_t n = dec.readPcmFrames(tmp.data(), decoding::IncrementalAudioDecoder::CHUNK_SIZE);
-    if (n == 0) {
-      break;
-    }
-    acc.insert(
-        acc.end(),
-        tmp.begin(),
-        tmp.begin() + static_cast<ptrdiff_t>(n * static_cast<size_t>(dec.outputChannels())));
-  }
-  return buildAudioBufferFromInterleaved(acc, dec.outputChannels(), dec.outputSampleRate());
-}
-
 } // namespace audioapi::ffmpeg_decoder
 
 #else
@@ -632,12 +496,6 @@ decoding::DecoderResult FFmpegDecoder::seekToTime(double) {
 size_t FFmpegDecoder::readPcmFrames(float *, size_t) {
   return 0;
 }
-std::shared_ptr<AudioBuffer> decodeWithFilePath(const std::string &, int) {
-  return nullptr;
-}
-std::shared_ptr<AudioBuffer> decodeWithMemoryBlock(const void *, size_t, int) {
-  return nullptr;
-}
 
 } // namespace audioapi::ffmpeg_decoder
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
index 50b911ec8..dc1e0eaee 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
@@ -10,12 +10,10 @@
 
 #pragma once
 
-#include <audioapi/libs/decoding/IncrementalAudioDecoder.h>
-#include <audioapi/utils/AudioBuffer.hpp>
+#include <audioapi/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/utils/Macros.h>
 #include <cstddef>
 #include <map>
-#include <memory>
 #include <string>
 #include <vector>
 
@@ -28,17 +26,12 @@ extern "C" {
 
 namespace audioapi::ffmpeg_decoder {
 
-/// Opaque IO state for openMemory — owns the audio bytes for the decoder's lifetime.
-struct MemoryIOContext {
-  std::vector<uint8_t> data;
-  size_t pos = 0;
-};
-
 /**
- * FFmpeg decoder with incremental read, analogous to ma_decoder:
- *   1) openFile, openUrl, or openMemory
- *   2) readPcmFrames repeatedly; 0 returned = end of stream
- *   3) close when done
+ * FFmpeg decoder for remote HTTP(S) / HLS (`openUrl`). Local file and memory
+ * decode use OS / miniaudio instead — `openFile` / `openMemory` remain as
+ * interface stubs (or local-file open for path-based demux when needed).
+ *
+ * Usage: openUrl → readPcmFrames repeatedly → close.
  */
 class FFmpegDecoder : public decoding::IncrementalAudioDecoder {
  public:
@@ -54,6 +47,7 @@ class FFmpegDecoder : public decoding::IncrementalAudioDecoder {
       const std::string &url,
       const std::map<std::string, std::string> &headers = {}) override;
 
+  /// Not used for batch decode (OS / miniaudio own memory). Returns an error.
   [[nodiscard]] decoding::DecoderResult
   openMemory(int outputSampleRate, const void *data, size_t size) override;
 
@@ -101,9 +95,6 @@ class FFmpegDecoder : public decoding::IncrementalAudioDecoder {
   uint8_t **resampled_data_ = nullptr;
   int max_resampled_samples_ = 0;
 
-  std::unique_ptr<MemoryIOContext> mem_io_;
-  AVIOContext *avio_ctx_ = nullptr;
-
   std::vector<float> leftover_;
   size_t leftover_offset_ = 0;
   int audio_stream_index_ = -1;
@@ -112,7 +103,4 @@ class FFmpegDecoder : public decoding::IncrementalAudioDecoder {
   size_t total_output_frames_ = 0;
 };
 
-std::shared_ptr<AudioBuffer> decodeWithMemoryBlock(const void *data, size_t size, int sample_rate);
-std::shared_ptr<AudioBuffer> decodeWithFilePath(const std::string &path, int sample_rate);
-
 } // namespace audioapi::ffmpeg_decoder
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h
index 5b32ceda6..e9384b52d 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h
@@ -1,6 +1,6 @@
 #pragma once
 
-#include <audioapi/libs/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/decoding/IncrementalAudioDecoder.h>
 #include <audioapi/libs/miniaudio/miniaudio.h>
 #include <audioapi/utils/AudioBuffer.hpp>
 #include <audioapi/utils/Macros.h>
@@ -9,7 +9,6 @@
 #include <cstdint>
 #include <map>
 #include <memory>
-#include <optional>
 #include <string>
 #include <vector>
 
diff --git a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
new file mode 100644
index 000000000..6d66be81d
--- /dev/null
+++ b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
@@ -0,0 +1,46 @@
+#pragma once
+
+#include <audioapi/decoding/OsDecoderBase.h>
+#include <audioapi/utils/Macros.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <map>
+#include <memory>
+#include <string>
+
+namespace audioapi::ios_decoder {
+
+struct IosDecoderState;
+
+/**
+ * iOS ExtAudioFile-backed incremental decoder.
+ *
+ * Opens local files or in-memory buffers and pulls interleaved float PCM on
+ * demand. `openUrl` / HLS are not supported (callers keep those on FFmpeg).
+ */
+class IOSDecoder : public OsDecoderBase {
+ public:
+  IOSDecoder();
+  ~IOSDecoder() override;
+  DELETE_COPY_AND_MOVE(IOSDecoder);
+
+  [[nodiscard]] decoding::DecoderResult openFile(int outputSampleRate, const std::string &path)
+      override;
+  [[nodiscard]] decoding::DecoderResult
+  openMemory(int outputSampleRate, const void *data, size_t size) override;
+  [[nodiscard]] decoding::DecoderResult openUrl(
+      int outputSampleRate,
+      const std::string &url,
+      const std::map<std::string, std::string> &headers = {}) override;
+  [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
+  [[nodiscard]] decoding::DecoderResult seekToTime(double seconds) override;
+
+ private:
+  void releaseImpl() override;
+
+  // Opaque Core Audio state (defined in IOSDecoding.mm).
+  std::unique_ptr<IosDecoderState> impl_;
+};
+
+} // namespace audioapi::ios_decoder
diff --git a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
new file mode 100644
index 000000000..61c32bc4b
--- /dev/null
+++ b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
@@ -0,0 +1,357 @@
+#import <AudioToolbox/AudioToolbox.h>
+#import <Foundation/Foundation.h>
+
+#include <audioapi/ios/core/utils/IOSDecoding.h>
+
+#include <algorithm>
+#include <climits>
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <type_traits>
+#include <utility>
+#include <vector>
+
+namespace audioapi::ios_decoder {
+namespace {
+
+struct ExtAudioFileDeleter {
+  void operator()(std::remove_pointer_t<ExtAudioFileRef> *file) const
+  {
+    if (file != nullptr) {
+      ExtAudioFileDispose(file);
+    }
+  }
+};
+
+struct AudioFileDeleter {
+  void operator()(std::remove_pointer_t<AudioFileID> *file) const
+  {
+    if (file != nullptr) {
+      AudioFileClose(file);
+    }
+  }
+};
+
+using ExtAudioFilePtr =
+    std::unique_ptr<std::remove_pointer_t<ExtAudioFileRef>, ExtAudioFileDeleter>;
+using AudioFilePtr = std::unique_ptr<std::remove_pointer_t<AudioFileID>, AudioFileDeleter>;
+
+} // namespace
+
+// Native reader state kept out of the shared header so Core Audio types never
+// leak into cross-platform code. Owned by IOSDecoder::impl_.
+struct IosDecoderState {
+  // Declaration order matters: ExtAudioFile wraps AudioFile for openMemory(),
+  // so extFile must be destroyed first (members destroy in reverse order).
+  AudioFilePtr audioFile;
+  ExtAudioFilePtr extFile;
+  std::vector<uint8_t> memory;
+  // File-native sample rate, used to translate seek time into file frames
+  // (ExtAudioFileSeek positions in the file's rate, not the client rate).
+  double fileSampleRate = 0.0;
+};
+
+namespace {
+
+// AudioFile read callback over the in-memory buffer owned by IosDecoderState.
+OSStatus memoryReadProc(
+    void *inClientData,
+    SInt64 inPosition,
+    UInt32 requestCount,
+    void *buffer,
+    UInt32 *actualCount)
+{
+  auto *state = static_cast<IosDecoderState *>(inClientData);
+  const auto total = static_cast<SInt64>(state->memory.size());
+  if (inPosition < 0 || inPosition > total) {
+    *actualCount = 0;
+    return kAudioFileInvalidPacketOffsetError;
+  }
+  const SInt64 available = total - inPosition;
+  const auto toCopy =
+      static_cast<UInt32>(std::min<SInt64>(static_cast<SInt64>(requestCount), available));
+  if (toCopy > 0) {
+    std::memcpy(buffer, state->memory.data() + inPosition, toCopy);
+  }
+  *actualCount = toCopy;
+  return noErr;
+}
+
+SInt64 memoryGetSizeProc(void *inClientData)
+{
+  auto *state = static_cast<IosDecoderState *>(inClientData);
+  return static_cast<SInt64>(state->memory.size());
+}
+
+// Sniffs a container hint from the leading magic bytes so AudioFile can pick the
+// right parser for in-memory data.
+// NOLINTBEGIN(readability-magic-numbers, cppcoreguidelines-avoid-magic-numbers)
+const char *guessFileTypeExtension(const void *data, size_t size)
+{
+  if (data == nullptr || size < 12) {
+    return "bin";
+  }
+  const auto *bytes = static_cast<const unsigned char *>(data);
+  if (std::memcmp(bytes, "RIFF", 4) == 0 && std::memcmp(bytes + 8, "WAVE", 4) == 0) {
+    return "wav";
+  }
+  if (std::memcmp(bytes, "fLaC", 4) == 0) {
+    return "flac";
+  }
+  if (bytes[0] == 0xFF && (bytes[1] & 0xF6) == 0xF0) {
+    return "aac";
+  }
+  if (std::memcmp(bytes, "ID3", 3) == 0 || (bytes[0] == 0xFF && (bytes[1] & 0xE0) == 0xE0)) {
+    return "mp3";
+  }
+  if (std::memcmp(bytes + 4, "ftyp", 4) == 0) {
+    return "m4a";
+  }
+  if (std::memcmp(bytes, "caff", 4) == 0) {
+    return "caf";
+  }
+  if (std::memcmp(bytes, "FORM", 4) == 0 &&
+      (std::memcmp(bytes + 8, "AIFF", 4) == 0 || std::memcmp(bytes + 8, "AIFC", 4) == 0)) {
+    return "aiff";
+  }
+  return "bin";
+}
+// NOLINTEND(readability-magic-numbers, cppcoreguidelines-avoid-magic-numbers)
+
+} // namespace
+
+IOSDecoder::IOSDecoder() = default;
+
+IOSDecoder::~IOSDecoder()
+{
+  close();
+}
+
+decoding::DecoderResult IOSDecoder::openUrl(
+    int /*outputSampleRate*/,
+    const std::string & /*url*/,
+    const std::map<std::string, std::string> & /*headers*/)
+{
+  return Err("IOSDecoder::openUrl is not supported (use FFmpeg for remote streams)");
+}
+
+// Sets the interleaved-float client format and caches channel/rate/duration.
+static decoding::DecoderResult configureExtAudioFile(
+    ExtAudioFileRef extFile,
+    int requestedSampleRate,
+    int &outChannels,
+    int &outSampleRate,
+    double &outDurationSeconds,
+    double &outFileSampleRate)
+{
+  AudioStreamBasicDescription fileFormat{};
+  UInt32 propSize = sizeof(fileFormat);
+  OSStatus status = ExtAudioFileGetProperty(
+      extFile, kExtAudioFileProperty_FileDataFormat, &propSize, &fileFormat);
+  if (status != noErr) {
+    return Err(
+        "IOSDecoder: ExtAudioFileGetProperty(FileDataFormat) failed: " + std::to_string(status));
+  }
+
+  const int channels = static_cast<int>(fileFormat.mChannelsPerFrame);
+  if (channels <= 0) {
+    return Err("IOSDecoder: invalid channel count");
+  }
+
+  const int outRate =
+      requestedSampleRate > 0 ? requestedSampleRate : static_cast<int>(fileFormat.mSampleRate);
+
+  AudioStreamBasicDescription clientFormat{};
+  clientFormat.mSampleRate = outRate;
+  clientFormat.mFormatID = kAudioFormatLinearPCM;
+  clientFormat.mFormatFlags =
+      kAudioFormatFlagIsFloat | kAudioFormatFlagIsPacked | kAudioFormatFlagsNativeEndian;
+  clientFormat.mBitsPerChannel = sizeof(float) * CHAR_BIT;
+  clientFormat.mChannelsPerFrame = static_cast<UInt32>(channels);
+  clientFormat.mFramesPerPacket = 1;
+  clientFormat.mBytesPerFrame = sizeof(float) * static_cast<UInt32>(channels);
+  clientFormat.mBytesPerPacket = clientFormat.mBytesPerFrame;
+
+  status = ExtAudioFileSetProperty(
+      extFile, kExtAudioFileProperty_ClientDataFormat, sizeof(clientFormat), &clientFormat);
+  if (status != noErr) {
+    return Err(
+        "IOSDecoder: ExtAudioFileSetProperty(ClientDataFormat) failed: " + std::to_string(status));
+  }
+
+  SInt64 fileLengthFrames = 0;
+  propSize = sizeof(fileLengthFrames);
+  status = ExtAudioFileGetProperty(
+      extFile, kExtAudioFileProperty_FileLengthFrames, &propSize, &fileLengthFrames);
+  if (status != noErr || fileLengthFrames < 0) {
+    fileLengthFrames = 0; // Unknown (e.g. raw ADTS AAC) — report duration 0.
+  }
+
+  outChannels = channels;
+  outSampleRate = outRate;
+  outFileSampleRate = fileFormat.mSampleRate;
+  outDurationSeconds = fileFormat.mSampleRate > 0
+      ? static_cast<double>(fileLengthFrames) / static_cast<double>(fileFormat.mSampleRate)
+      : 0.0;
+  return Ok(None);
+}
+
+decoding::DecoderResult IOSDecoder::openFile(int outputSampleRate, const std::string &path)
+{
+  close();
+  if (path.empty()) {
+    return Err("IOSDecoder::openFile failed: path is empty");
+  }
+
+  @autoreleasepool {
+    NSString *nsPath = [NSString stringWithUTF8String:path.c_str()];
+    if (nsPath == nil) {
+      return Err("IOSDecoder::openFile failed: invalid path encoding");
+    }
+    NSURL *url = [NSURL fileURLWithPath:nsPath];
+    ExtAudioFileRef extFile = nullptr;
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-cstyle-cast)
+    OSStatus status = ExtAudioFileOpenURL((__bridge CFURLRef)url, &extFile);
+    if (status != noErr || extFile == nullptr) {
+      return Err("IOSDecoder::openFile ExtAudioFileOpenURL failed: " + std::to_string(status));
+    }
+
+    auto state = std::make_unique<IosDecoderState>();
+    state->extFile.reset(extFile);
+    auto configured = configureExtAudioFile(
+        state->extFile.get(),
+        outputSampleRate,
+        outputChannels_,
+        outputSampleRate_,
+        durationSeconds_,
+        state->fileSampleRate);
+    if (configured.is_err()) {
+      return configured;
+    }
+
+    impl_ = std::move(state);
+    framePosition_ = 0;
+    open_ = true;
+    return Ok(None);
+  }
+}
+
+decoding::DecoderResult IOSDecoder::openMemory(int outputSampleRate, const void *data, size_t size)
+{
+  close();
+  if (data == nullptr || size == 0) {
+    return Err("IOSDecoder::openMemory failed: empty input");
+  }
+
+  auto state = std::make_unique<IosDecoderState>();
+  state->memory.assign(
+      static_cast<const uint8_t *>(data), static_cast<const uint8_t *>(data) + size);
+
+  // Wrap the owned bytes with AudioFile callbacks, then wrap that with
+  // ExtAudioFile so we get the same read/seek/convert path as openFile without
+  // touching the filesystem.
+  AudioFileTypeID hint = 0;
+  const char *ext = guessFileTypeExtension(data, size);
+  if (std::strcmp(ext, "wav") == 0) {
+    hint = kAudioFileWAVEType;
+  } else if (std::strcmp(ext, "mp3") == 0) {
+    hint = kAudioFileMP3Type;
+  } else if (std::strcmp(ext, "aac") == 0) {
+    hint = kAudioFileAAC_ADTSType;
+  } else if (std::strcmp(ext, "m4a") == 0) {
+    hint = kAudioFileM4AType;
+  } else if (std::strcmp(ext, "caf") == 0) {
+    hint = kAudioFileCAFType;
+  } else if (std::strcmp(ext, "aiff") == 0) {
+    hint = kAudioFileAIFFType;
+  } else if (std::strcmp(ext, "flac") == 0) {
+    hint = kAudioFileFLACType;
+  }
+
+  AudioFileID audioFile = nullptr;
+  OSStatus status = AudioFileOpenWithCallbacks(
+      state.get(), memoryReadProc, nullptr, memoryGetSizeProc, nullptr, hint, &audioFile);
+  if (status != noErr || audioFile == nullptr) {
+    return Err(
+        "IOSDecoder::openMemory AudioFileOpenWithCallbacks failed: " + std::to_string(status));
+  }
+  state->audioFile.reset(audioFile);
+
+  ExtAudioFileRef extFile = nullptr;
+  status =
+      ExtAudioFileWrapAudioFileID(state->audioFile.get(), static_cast<Boolean>(false), &extFile);
+  if (status != noErr || extFile == nullptr) {
+    return Err(
+        "IOSDecoder::openMemory ExtAudioFileWrapAudioFileID failed: " + std::to_string(status));
+  }
+  state->extFile.reset(extFile);
+
+  auto configured = configureExtAudioFile(
+      state->extFile.get(),
+      outputSampleRate,
+      outputChannels_,
+      outputSampleRate_,
+      durationSeconds_,
+      state->fileSampleRate);
+  if (configured.is_err()) {
+    return configured;
+  }
+
+  impl_ = std::move(state);
+  framePosition_ = 0;
+  open_ = true;
+  return Ok(None);
+}
+
+size_t IOSDecoder::readPcmFrames(float *outInterleaved, size_t frameCount)
+{
+  if (!open_ || impl_ == nullptr || impl_->extFile == nullptr || outInterleaved == nullptr ||
+      frameCount == 0 || outputChannels_ <= 0) {
+    return 0;
+  }
+
+  AudioBufferList bufferList{};
+  bufferList.mNumberBuffers = 1;
+  bufferList.mBuffers[0].mNumberChannels = static_cast<UInt32>(outputChannels_);
+  bufferList.mBuffers[0].mDataByteSize =
+      static_cast<UInt32>(frameCount * static_cast<size_t>(outputChannels_) * sizeof(float));
+  bufferList.mBuffers[0].mData = outInterleaved;
+
+  auto framesToRead = static_cast<UInt32>(frameCount);
+  const OSStatus status = ExtAudioFileRead(impl_->extFile.get(), &framesToRead, &bufferList);
+  if (status != noErr) {
+    return 0;
+  }
+  framePosition_ += framesToRead;
+  return framesToRead;
+}
+
+decoding::DecoderResult IOSDecoder::seekToTime(double seconds)
+{
+  if (!open_ || impl_ == nullptr || impl_->extFile == nullptr) {
+    return Err("IOSDecoder::seekToTime failed: decoder is not open");
+  }
+  if (!std::isfinite(seconds) || seconds < 0.0) {
+    return Err("IOSDecoder::seekToTime failed: seconds is not finite");
+  }
+
+  const auto fileFrame = static_cast<SInt64>(std::llround(seconds * impl_->fileSampleRate));
+  const OSStatus status = ExtAudioFileSeek(impl_->extFile.get(), fileFrame);
+  if (status != noErr) {
+    return Err("IOSDecoder::seekToTime ExtAudioFileSeek failed: " + std::to_string(status));
+  }
+  framePosition_ =
+      static_cast<int64_t>(std::llround(seconds * static_cast<double>(outputSampleRate_)));
+  return Ok(None);
+}
+
+void IOSDecoder::releaseImpl()
+{
+  impl_.reset();
+}
+
+} // namespace audioapi::ios_decoder
diff --git a/packages/react-native-audio-api/src/utils/flags.ts b/packages/react-native-audio-api/src/utils/flags.ts
index c1a88a603..4843b068b 100644
--- a/packages/react-native-audio-api/src/utils/flags.ts
+++ b/packages/react-native-audio-api/src/utils/flags.ts
@@ -3,9 +3,10 @@ import { NativeAudioAPIModule } from '../specs';
 /**
  * Returns whether the native build includes FFmpeg.
  *
- * When `false`, streaming, remote URL metadata, several decode/playback paths,
- * M4A concatenation, and Android non-WAV recording are unavailable. See the
- * runtime flags docs for the full feature matrix.
+ * When `false`, remote URL streaming / HLS, remote URL metadata, M4A
+ * concatenation, and Android non-WAV recording are unavailable. Batch decoding
+ * uses OS APIs / miniaudio and does not require FFmpeg. See the runtime flags
+ * docs for the full feature matrix.
  */
 export function isFfmpegEnabled(): boolean {
   return NativeAudioAPIModule.isFfmpegEnabled();
diff --git a/packages/react-native-audio-api/src/utils/remoteHttpSource.ts b/packages/react-native-audio-api/src/utils/remoteHttpSource.ts
index 3e21aee98..b46a1b56a 100644
--- a/packages/react-native-audio-api/src/utils/remoteHttpSource.ts
+++ b/packages/react-native-audio-api/src/utils/remoteHttpSource.ts
@@ -63,7 +63,7 @@ async function downloadRemoteHttpSource(
 
 /**
  * Stream via native URL when FFmpeg is enabled and byte ranges work (or HLS);
- * otherwise download fully so miniaudio can decode without FFmpeg.
+ * otherwise download fully so OS / miniaudio can decode without FFmpeg.
  */
 export async function loadRemoteHttpSource(
   url: string,
diff --git a/packages/test-app-screen/src/AudioBufferTest.ts b/packages/test-app-screen/src/AudioBufferTest.ts
index a8c8aa10a..cd6e36de6 100644
--- a/packages/test-app-screen/src/AudioBufferTest.ts
+++ b/packages/test-app-screen/src/AudioBufferTest.ts
@@ -1,9 +1,40 @@
 import { AudioContext, AudioBuffer } from "react-native-audio-api";
 import { PCM_DATA } from "./constants";
 
-const SUPPORTED_FORMATS = ['mp3', 'wav', 'aac', 'flac', 'ogg', 'opus', 'm4a', 'mp4'];
-const EXPECTED_BUFFER_DURATION = 16;
-const EXPECTED_CHANNELS = 2;
+const ESPRESSIF_STEREO =
+  'https://dl.espressif.com/dl/audio/gs-16b-2c-44100hz.';
+
+type FormatFixture = {
+  format: string;
+  url: string;
+  expectedDuration: number;
+  expectedChannels: number;
+};
+
+// Newly supported OS-path containers: aif/aiff (same AIFF bytes) and caf.
+const FORMAT_FIXTURES: FormatFixture[] = [
+  ...['mp3', 'wav', 'aac', 'flac', 'ogg', 'opus', 'm4a', 'mp4', 'aiff'].map(
+    (format) => ({
+      format,
+      url: ESPRESSIF_STEREO + format,
+      expectedDuration: 16,
+      expectedChannels: 2,
+    })
+  ),
+  {
+    // Same AIFF bytes as `.aiff` (Espressif has no `.aif` URL); decode is magic-based.
+    format: 'aif',
+    url: ESPRESSIF_STEREO + 'aiff',
+    expectedDuration: 16,
+    expectedChannels: 2,
+  },
+  {
+    format: 'caf',
+    url: 'https://samples.ffmpeg.org/A-codecs/caf/ComputerData05.caf',
+    expectedDuration: 0.51,
+    expectedChannels: 2,
+  },
+];
 
 const CHANNELS_MAP: Map<number, string> = new Map([
   [1, 'https://dl.espressif.com/dl/audio/gs-16b-1c-44100hz.mp3'],
@@ -20,9 +51,9 @@ const DURATIONS_MAP: Map<number, number> = new Map([
 ]);
 
 export const audioBufferFormatsTest = async (audioContextRef: React.RefObject<AudioContext | null>, setTestingInfo: (value: React.SetStateAction<string>) => void) => {
-  let buffers: AudioBuffer[] = [];
-  for (const format of SUPPORTED_FORMATS) {
-    const url = 'https://dl.espressif.com/dl/audio/gs-16b-2c-44100hz.' + format;
+  const buffers: { format: string; buffer: AudioBuffer }[] = [];
+  for (const fixture of FORMAT_FIXTURES) {
+    const { format, url, expectedDuration, expectedChannels } = fixture;
     setTestingInfo(`Loading audio buffer: ${format}`);
     await fetch(url, {
       headers: {
@@ -34,22 +65,22 @@ export const audioBufferFormatsTest = async (audioContextRef: React.RefObject<Au
         try {
           const audioBuffer = await audioContextRef.current!.decodeAudioData(arrayBuffer);
           console.log(`Decoded ${format} buffer:`, audioBuffer);
-          if (Math.abs(audioBuffer.duration - EXPECTED_BUFFER_DURATION) > 0.3) {
+          if (Math.abs(audioBuffer.duration - expectedDuration) > 0.3) {
             throw new Error(`Unexpected buffer duration: ${audioBuffer.duration}`);
           }
-          if (audioBuffer.numberOfChannels !== EXPECTED_CHANNELS) {
+          if (audioBuffer.numberOfChannels !== expectedChannels) {
             throw new Error(`Unexpected number of channels: ${audioBuffer.numberOfChannels}`);
           }
-          buffers.push(audioBuffer);
+          buffers.push({ format, buffer: audioBuffer });
         } catch (error) {
           setTestingInfo(`Error decoding audio buffer: ${format} - ${error}`);
         }
       })
   }
   for (let i = 0; i < buffers.length; i++) {
-    setTestingInfo(`Playing ${SUPPORTED_FORMATS[i]} buffer`);
+    setTestingInfo(`Playing ${buffers[i].format} buffer`);
     const bufferSource = audioContextRef.current!.createBufferSource();
-    bufferSource.buffer = buffers[i];
+    bufferSource.buffer = buffers[i].buffer;
     bufferSource.connect(audioContextRef.current!.destination);
     bufferSource.start();
     await new Promise(resolve => setTimeout(resolve, 4000));
diff --git a/packages/test-app-screen/src/AudioTagTest.ts b/packages/test-app-screen/src/AudioTagTest.ts
index 9cc2ce753..db7fc42bb 100644
--- a/packages/test-app-screen/src/AudioTagTest.ts
+++ b/packages/test-app-screen/src/AudioTagTest.ts
@@ -7,15 +7,24 @@ type FileSourceNode = NonNullable<
 const AUDIO_URL =
   'https://software-mansion.github.io/react-native-audio-api/audio/music/example-music-01.mp3';
 
-const SUPPORTED_FORMATS = [
-  'mp3',
-  'wav',
-  'aac',
-  'flac',
-  'ogg',
-  'opus',
-  'm4a',
-  'mp4',
+const ESPRESSIF_STEREO =
+  'https://dl.espressif.com/dl/audio/gs-16b-2c-44100hz.';
+
+const FORMAT_FIXTURES: { format: string; url: string }[] = [
+  ...['mp3', 'wav', 'aac', 'flac', 'ogg', 'opus', 'm4a', 'mp4', 'aiff'].map(
+    (format) => ({
+      format,
+      url: ESPRESSIF_STEREO + format,
+    })
+  ),
+  {
+    format: 'aif',
+    url: ESPRESSIF_STEREO + 'aiff',
+  },
+  {
+    format: 'caf',
+    url: 'https://samples.ffmpeg.org/A-codecs/caf/ComputerData05.caf',
+  },
 ];
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -176,8 +185,7 @@ export const audioTagFormatsTest = async (
   ctx: AudioContext,
   setInfo: (info: string) => void
 ) => {
-  for (const format of SUPPORTED_FORMATS) {
-    const url = `https://dl.espressif.com/dl/audio/gs-16b-2c-44100hz.${format}`;
+  for (const { format, url } of FORMAT_FIXTURES) {
     setInfo(`AudioTag formats: loading ${format}...`);
 
     try {

From 5c495c00bd188d9a5c5b1b656009c5b09ec3dc3e Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Mon, 20 Jul 2026 16:25:36 +0200
Subject: [PATCH 02/12] refactor: less code repetition in probing and decoding

---
 .../src/main/cpp/audioapi/AndroidDecoding.cpp |   8 --
 .../src/main/cpp/audioapi/AndroidDecoding.h   |   7 +-
 .../cpp/audioapi/core/utils/AudioDecoding.cpp | 120 +++++++-----------
 .../core/utils/decoding/SeekDecoderDaemon.cpp |  14 +-
 .../decoding/IncrementalAudioDecoder.h        |  18 +--
 .../audioapi/libs/ffmpeg/FFmpegDecoding.cpp   |   9 --
 .../cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h |  11 +-
 .../libs/miniaudio/MiniAudioDecoding.cpp      |   7 -
 .../libs/miniaudio/MiniAudioDecoding.h        |   7 +-
 .../ios/audioapi/ios/core/utils/IOSDecoding.h |   7 +-
 .../audioapi/ios/core/utils/IOSDecoding.mm    |   8 --
 11 files changed, 64 insertions(+), 152 deletions(-)

diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp b/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp
index 412b1373c..0c317cef5 100644
--- a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp
@@ -14,7 +14,6 @@
 #include <cstdint>
 #include <cstdio>
 #include <cstring>
-#include <map>
 #include <memory>
 #include <string>
 #include <utility>
@@ -330,13 +329,6 @@ AndroidDecoder::~AndroidDecoder() {
   close();
 }
 
-decoding::DecoderResult AndroidDecoder::openUrl(
-    int /*outputSampleRate*/,
-    const std::string & /*url*/,
-    const std::map<std::string, std::string> & /*headers*/) {
-  return Err("AndroidDecoder::openUrl is not supported (use FFmpeg for remote streams)");
-}
-
 decoding::DecoderResult AndroidDecoder::openFile(int outputSampleRate, const std::string &path) {
   close();
   if (path.empty()) {
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h b/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h
index f1e1b19e6..7b5c65de4 100644
--- a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h
@@ -4,7 +4,6 @@
 #include <audioapi/utils/Macros.h>
 
 #include <cstddef>
-#include <map>
 #include <memory>
 #include <string>
 
@@ -16,7 +15,7 @@ struct AndroidDecoderState;
  * Android MediaExtractor + MediaCodec incremental decoder.
  *
  * Opens local files or in-memory buffers and pulls interleaved float PCM on
- * demand. `openUrl` / HLS are not supported (callers keep those on FFmpeg).
+ * demand. Remote URL / HLS decoding stays on FFmpeg.
  */
 class AndroidDecoder : public OsDecoderBase {
  public:
@@ -28,10 +27,6 @@ class AndroidDecoder : public OsDecoderBase {
       override;
   [[nodiscard]] decoding::DecoderResult
   openMemory(int outputSampleRate, const void *data, size_t size) override;
-  [[nodiscard]] decoding::DecoderResult openUrl(
-      int outputSampleRate,
-      const std::string &url,
-      const std::map<std::string, std::string> &headers = {}) override;
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
   [[nodiscard]] decoding::DecoderResult seekToTime(double seconds) override;
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
index ccd0f9dcd..73df4532c 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
@@ -71,12 +71,17 @@ bool isValidDuration(float duration) {
   return duration >= 0.0F && std::isfinite(duration);
 }
 
-AudioDurationResult probeDurationWithFilePath(const std::string &path) {
+namespace {
+
+/// Tries OS decoder then miniaudio. `open` opens the given decoder for the source.
+template <typename OpenFn>
+  requires std::
+      is_invocable_r_v<decoding::DecoderResult, OpenFn, decoding::IncrementalAudioDecoder &>
+    AudioDurationResult probeDurationLocal(OpenFn &&open, const char *errorMessage) {
 #if RN_AUDIO_API_HAS_OS_DECODER
   {
     os_decoder::Decoder platformDecoder;
-    const auto platformOpen = platformDecoder.openFile(0, path);
-    if (platformOpen.is_ok()) {
+    if (open(platformDecoder).is_ok()) {
       auto result = resolveDurationFromDecoder(platformDecoder);
       platformDecoder.close();
       if (result.is_ok()) {
@@ -89,27 +94,26 @@ AudioDurationResult probeDurationWithFilePath(const std::string &path) {
 #endif // RN_AUDIO_API_HAS_OS_DECODER
 
   miniaudio_decoder::MiniAudioDecoder decoder;
-  const auto openResult = decoder.openFile(0, path);
-  if (openResult.is_err()) {
-    return Err("Cannot read duration: file could not be decoded");
+  if (open(decoder).is_err()) {
+    return Err(errorMessage);
   }
   auto result = resolveDurationFromDecoder(decoder);
   decoder.close();
   if (result.is_err()) {
-    return Err("Cannot read duration: file could not be decoded");
+    return Err(errorMessage);
   }
   return result;
 }
 
-AudioDurationResult probeDurationWithMemory(const void *data, size_t size, int sampleRate) {
-  const int sr = sampleRate != 0 ? sampleRate : 0;
-
+template <typename OpenFn>
+  requires std::
+      is_invocable_r_v<decoding::DecoderResult, OpenFn, decoding::IncrementalAudioDecoder &>
+    AudioBufferResult decodeLocal(OpenFn &&open, const char *errorMessage) {
 #if RN_AUDIO_API_HAS_OS_DECODER
   {
     os_decoder::Decoder platformDecoder;
-    const auto platformOpen = platformDecoder.openMemory(sr, data, size);
-    if (platformOpen.is_ok()) {
-      auto result = resolveDurationFromDecoder(platformDecoder);
+    if (open(platformDecoder).is_ok()) {
+      auto result = decodeAll(platformDecoder);
       platformDecoder.close();
       if (result.is_ok()) {
         return result;
@@ -121,18 +125,34 @@ AudioDurationResult probeDurationWithMemory(const void *data, size_t size, int s
 #endif // RN_AUDIO_API_HAS_OS_DECODER
 
   miniaudio_decoder::MiniAudioDecoder decoder;
-  const auto openResult = decoder.openMemory(sr, data, size);
-  if (openResult.is_err()) {
-    return Err("Cannot read duration: audio data could not be decoded");
+  if (open(decoder).is_err()) {
+    return Err(errorMessage);
   }
-  auto result = resolveDurationFromDecoder(decoder);
+  auto result = decodeAll(decoder);
   decoder.close();
   if (result.is_err()) {
-    return Err("Cannot read duration: audio data could not be decoded");
+    return Err(errorMessage);
   }
   return result;
 }
 
+} // namespace
+
+AudioDurationResult probeDurationWithFilePath(const std::string &path) {
+  return probeDurationLocal(
+      [&](decoding::IncrementalAudioDecoder &decoder) { return decoder.openFile(0, path); },
+      "Cannot read duration: file could not be decoded");
+}
+
+AudioDurationResult probeDurationWithMemory(const void *data, size_t size, int sampleRate) {
+  const int sr = sampleRate != 0 ? sampleRate : 0;
+  return probeDurationLocal(
+      [=](decoding::IncrementalAudioDecoder &decoder) {
+        return decoder.openMemory(sr, data, size);
+      },
+      "Cannot read duration: audio data could not be decoded");
+}
+
 AudioDurationResult probeDurationWithUrl(
     const std::string &url,
     int sampleRate,
@@ -157,66 +177,18 @@ AudioDurationResult probeDurationWithUrl(
 
 AudioBufferResult decodeWithFilePath(const std::string &path, float sampleRate) {
   const int sr = static_cast<int>(sampleRate);
-
-#if RN_AUDIO_API_HAS_OS_DECODER
-  {
-    os_decoder::Decoder platformDecoder;
-    const auto platformOpen = platformDecoder.openFile(sr, path);
-    if (platformOpen.is_ok()) {
-      auto result = decodeAll(platformDecoder);
-      platformDecoder.close();
-      if (result.is_ok()) {
-        return result;
-      }
-    } else {
-      platformDecoder.close();
-    }
-  }
-#endif // RN_AUDIO_API_HAS_OS_DECODER
-
-  miniaudio_decoder::MiniAudioDecoder decoder;
-  const auto openResult = decoder.openFile(sr, path);
-  if (openResult.is_err()) {
-    return Err("Cannot decode file: unsupported or invalid audio format");
-  }
-  auto result = decodeAll(decoder);
-  decoder.close();
-  if (result.is_err()) {
-    return Err("Cannot decode file: unsupported or invalid audio format");
-  }
-  return result;
+  return decodeLocal(
+      [&](decoding::IncrementalAudioDecoder &decoder) { return decoder.openFile(sr, path); },
+      "Cannot decode file: unsupported or invalid audio format");
 }
 
 AudioBufferResult decodeWithMemoryBlock(const void *data, size_t size, float sampleRate) {
   const int sr = static_cast<int>(sampleRate);
-
-#if RN_AUDIO_API_HAS_OS_DECODER
-  {
-    os_decoder::Decoder platformDecoder;
-    const auto platformOpen = platformDecoder.openMemory(sr, data, size);
-    if (platformOpen.is_ok()) {
-      auto result = decodeAll(platformDecoder);
-      platformDecoder.close();
-      if (result.is_ok()) {
-        return result;
-      }
-    } else {
-      platformDecoder.close();
-    }
-  }
-#endif // RN_AUDIO_API_HAS_OS_DECODER
-
-  miniaudio_decoder::MiniAudioDecoder decoder;
-  const auto openResult = decoder.openMemory(sr, data, size);
-  if (openResult.is_err()) {
-    return Err("Cannot decode audio data: unsupported or invalid audio format");
-  }
-  auto result = decodeAll(decoder);
-  decoder.close();
-  if (result.is_err()) {
-    return Err("Cannot decode audio data: unsupported or invalid audio format");
-  }
-  return result;
+  return decodeLocal(
+      [&](decoding::IncrementalAudioDecoder &decoder) {
+        return decoder.openMemory(sr, data, size);
+      },
+      "Cannot decode audio data: unsupported or invalid audio format");
 }
 
 AudioBufferResult decodeWithPCMInBase64(
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp
index a0b53ebf5..04d083f34 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp
@@ -8,13 +8,10 @@
 namespace audioapi {
 namespace {
 
-decoding::DecoderResult openWithDecoder(
+decoding::DecoderResult openLocalWithDecoder(
     decoding::IncrementalAudioDecoder &decoder,
     const SeekDecoderDaemonOptions &options,
     int contextSampleRate) {
-  if (!options.sourceUrl.empty()) {
-    return decoder.openUrl(contextSampleRate, options.sourceUrl, options.httpHeaders);
-  }
   if (!options.filePath.empty()) {
     return decoder.openFile(contextSampleRate, options.filePath);
   }
@@ -40,19 +37,20 @@ SeekDecoderDaemon::SeekDecoderDaemon(
   // Remote HTTP(S) / HLS: FFmpeg owns network demux (byte ranges + playlists).
   if (!options.sourceUrl.empty()) {
 #if !RN_AUDIO_API_FFMPEG_DISABLED
-    decoder_ = std::make_unique<ffmpeg_decoder::FFmpegDecoder>();
-    openResult = openWithDecoder(*decoder_, options, contextSampleRate);
+    auto ffmpegDecoder = std::make_unique<ffmpeg_decoder::FFmpegDecoder>();
+    openResult = ffmpegDecoder->openUrl(contextSampleRate, options.sourceUrl, options.httpHeaders);
+    decoder_ = std::move(ffmpegDecoder);
 #endif
   } else {
 #if RN_AUDIO_API_HAS_OS_DECODER
     decoder_ = std::make_unique<os_decoder::Decoder>();
-    openResult = openWithDecoder(*decoder_, options, contextSampleRate);
+    openResult = openLocalWithDecoder(*decoder_, options, contextSampleRate);
 
     if (openResult.is_err()) {
       decoder_->close();
 #endif // RN_AUDIO_API_HAS_OS_DECODER
       decoder_ = std::make_unique<miniaudio_decoder::MiniAudioDecoder>();
-      openResult = openWithDecoder(*decoder_, options, contextSampleRate);
+      openResult = openLocalWithDecoder(*decoder_, options, contextSampleRate);
 #if RN_AUDIO_API_HAS_OS_DECODER
     }
 #endif // RN_AUDIO_API_HAS_OS_DECODER
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h
index 3ffc3a3bd..00e59f4ee 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h
@@ -3,14 +3,13 @@
 #include <audioapi/utils/Macros.h>
 #include <audioapi/utils/Result.hpp>
 #include <cstddef>
-#include <map>
 #include <string>
 
 namespace audioapi::decoding {
 using DecoderResult = Result<NoneType, std::string>;
 /**
  * Incremental PCM decoder: openFile or openMemory → readPcmFrames in a loop → close.
- * Shared contract for FFmpeg-based and MiniAudio-based implementations.
+ * Shared contract for OS-based and MiniAudio-based implementations.
  */
 class IncrementalAudioDecoder {
  public:
@@ -25,23 +24,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.
   /// @param size The size of the data.
   /// @return Ok(None) on success or Err(message) on failure.
+  /// Default rejects; OS and MiniAudio override with real implementations.
   [[nodiscard]] virtual DecoderResult
-  openMemory(int outputSampleRate, const void *data, size_t size) = 0;
+  openMemory(int /*outputSampleRate*/, const void * /*data*/, size_t /*size*/) {
+    return Err("openMemory is not supported by this decoder");
+  }
 
   /// @brief Reads PCM frames from the decoder.
   /// @param outInterleaved The output buffer for the decoded frames.
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp
index ce442a45a..9ebc2d3bd 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp
@@ -266,12 +266,6 @@ decoding::DecoderResult FFmpegDecoder::openUrl(
   return initializeDecodedStreams(outputSampleRate, "FFmpegDecoder::openUrl");
 }
 
-decoding::DecoderResult
-FFmpegDecoder::openMemory(int /*outputSampleRate*/, const void * /*data*/, size_t /*size*/) {
-  // Batch / in-memory decode is owned by OS and miniaudio; FFmpeg is for remote URLs.
-  return Err("FFmpegDecoder::openMemory is not supported (use OS or miniaudio for memory decode)");
-}
-
 void FFmpegDecoder::appendFrameResampled(AVFrame *frame) {
   int out_samples = swr_get_out_samples(swr_, frame->nb_samples);
   if (out_samples > max_resampled_samples_) {
@@ -481,9 +475,6 @@ decoding::DecoderResult FFmpegDecoder::openUrl(
     const std::map<std::string, std::string> &) {
   return Err("FFmpeg is disabled");
 }
-decoding::DecoderResult FFmpegDecoder::openMemory(int, const void *, size_t) {
-  return Err("FFmpeg is disabled");
-}
 float FFmpegDecoder::getDurationInSeconds() const {
   return 0;
 }
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
index dc1e0eaee..3c40447c3 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
@@ -28,8 +28,7 @@ namespace audioapi::ffmpeg_decoder {
 
 /**
  * FFmpeg decoder for remote HTTP(S) / HLS (`openUrl`). Local file and memory
- * decode use OS / miniaudio instead — `openFile` / `openMemory` remain as
- * interface stubs (or local-file open for path-based demux when needed).
+ * decode use OS / miniaudio instead.
  *
  * Usage: openUrl → readPcmFrames repeatedly → close.
  */
@@ -42,14 +41,12 @@ class FFmpegDecoder : public decoding::IncrementalAudioDecoder {
   [[nodiscard]] decoding::DecoderResult openFile(int outputSampleRate, const std::string &path)
       override;
 
+  /// Opens a remote HTTP(S) / HLS URL. Not part of IncrementalAudioDecoder —
+  /// only FFmpeg owns network demux.
   [[nodiscard]] decoding::DecoderResult openUrl(
       int outputSampleRate,
       const std::string &url,
-      const std::map<std::string, std::string> &headers = {}) override;
-
-  /// Not used for batch decode (OS / miniaudio own memory). Returns an error.
-  [[nodiscard]] decoding::DecoderResult
-  openMemory(int outputSampleRate, const void *data, size_t size) override;
+      const std::map<std::string, std::string> &headers = {});
 
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.cpp
index e0d5c5364..1babec16e 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.cpp
@@ -123,13 +123,6 @@ decoding::DecoderResult MiniAudioDecoder::openFile(
   return Ok(None);
 }
 
-decoding::DecoderResult MiniAudioDecoder::openUrl(
-    int /*outputSampleRate*/,
-    const std::string & /*url*/,
-    const std::map<std::string, std::string> & /*headers*/) {
-  return Err("MiniAudioDecoder::openUrl failed: remote URLs require FFmpeg");
-}
-
 decoding::DecoderResult MiniAudioDecoder::openMemory(
     int outputSampleRate,
     const void *data,
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h
index e9384b52d..1bbfcf73e 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h
@@ -7,7 +7,6 @@
 
 #include <cstddef>
 #include <cstdint>
-#include <map>
 #include <memory>
 #include <string>
 #include <vector>
@@ -16,7 +15,7 @@ namespace audioapi::miniaudio_decoder {
 
 /**
  * MiniAudio-backed incremental decoder (Vorbis/Opus/WAV, etc. via ma_decoder + custom backends).
- * Same usage contract as ffmpeg_decoder::FFmpegDecoder.
+ * Local file / memory only — remote URLs use FFmpegDecoder::openUrl.
  */
 class MiniAudioDecoder : public decoding::IncrementalAudioDecoder {
  public:
@@ -31,10 +30,6 @@ class MiniAudioDecoder : public decoding::IncrementalAudioDecoder {
       int outputSampleRate,
       const void *data,
       size_t size) override;
-  [[nodiscard]] decoding::DecoderResult openUrl(
-      int outputSampleRate,
-      const std::string &url,
-      const std::map<std::string, std::string> &headers = {}) override;
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
   void close() override;
   [[nodiscard]] bool isOpen() const override;
diff --git a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
index 6d66be81d..a6c72d014 100644
--- a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
+++ b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
@@ -5,7 +5,6 @@
 
 #include <cstddef>
 #include <cstdint>
-#include <map>
 #include <memory>
 #include <string>
 
@@ -17,7 +16,7 @@ struct IosDecoderState;
  * iOS ExtAudioFile-backed incremental decoder.
  *
  * Opens local files or in-memory buffers and pulls interleaved float PCM on
- * demand. `openUrl` / HLS are not supported (callers keep those on FFmpeg).
+ * demand. Remote URL / HLS decoding stays on FFmpeg.
  */
 class IOSDecoder : public OsDecoderBase {
  public:
@@ -29,10 +28,6 @@ class IOSDecoder : public OsDecoderBase {
       override;
   [[nodiscard]] decoding::DecoderResult
   openMemory(int outputSampleRate, const void *data, size_t size) override;
-  [[nodiscard]] decoding::DecoderResult openUrl(
-      int outputSampleRate,
-      const std::string &url,
-      const std::map<std::string, std::string> &headers = {}) override;
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
   [[nodiscard]] decoding::DecoderResult seekToTime(double seconds) override;
 
diff --git a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
index 61c32bc4b..8ff269f29 100644
--- a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
+++ b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
@@ -131,14 +131,6 @@ SInt64 memoryGetSizeProc(void *inClientData)
   close();
 }
 
-decoding::DecoderResult IOSDecoder::openUrl(
-    int /*outputSampleRate*/,
-    const std::string & /*url*/,
-    const std::map<std::string, std::string> & /*headers*/)
-{
-  return Err("IOSDecoder::openUrl is not supported (use FFmpeg for remote streams)");
-}
-
 // Sets the interleaved-float client format and caches channel/rate/duration.
 static decoding::DecoderResult configureExtAudioFile(
     ExtAudioFileRef extFile,

From 8b955f1b6699f51fd0f647a364c740576986b6be Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Tue, 21 Jul 2026 16:44:04 +0200
Subject: [PATCH 03/12] refactor: decoder architecture

---
 .../build-compilation-dependencies/SKILL.md   |   4 +-
 .../build-details.md                          |   4 +-
 THIRD_PARTY.md                                |   2 +-
 .../react-native-audio-api/RNAudioAPI.podspec |   2 +-
 .../src/main/cpp/audioapi/CMakeLists.txt      |   2 +-
 .../{ => android}/AndroidDecoding.cpp         | 297 +++++++++++++-----
 .../audioapi/{ => android}/AndroidDecoding.h  |  17 +-
 .../android/AndroidDecodingDataSource.cpp     | 173 ++++++++++
 .../android/AndroidDecodingDataSource.h       |  52 +++
 .../BaseAudioContextHostObject.cpp            |   2 +-
 .../utils/AudioDecoderHostObject.cpp          |   2 +-
 .../utils/AudioFileUtilsHostObject.cpp        |   4 +-
 .../HostObjects/utils/NodeOptionsParser.h     |   2 +-
 .../cpp/audioapi/core/BaseAudioContext.cpp    |   2 +-
 .../core/sources/AudioFileSourceNode.cpp      |  24 +-
 .../core/sources/AudioFileSourceNode.h        |   4 +-
 .../cpp/audioapi/core/utils/AudioDecoding.cpp | 226 -------------
 .../cpp/audioapi/decoding/AudioDecoding.cpp   | 174 ++++++++++
 .../{core/utils => decoding}/AudioDecoding.h  |   8 +-
 .../AudioFileConcatenator.cpp                 | 119 +++----
 .../AudioFileConcatenator.h                   |  38 +--
 .../cpp/audioapi/decoding/DecoderFactory.cpp  | 114 +++++++
 .../cpp/audioapi/decoding/DecoderFactory.h    |  17 +
 .../cpp/audioapi/decoding/DecoderSource.h     |  65 ++++
 .../decoding/IncrementalAudioDecoder.h        |  77 -----
 .../common/cpp/audioapi/decoding/OSDecoding.h |   2 +-
 .../utils => }/decoding/SeekDecoderDaemon.cpp |  53 +---
 .../utils => }/decoding/SeekDecoderDaemon.h   |  30 +-
 .../decoding/backends/AudioDecoderBackend.h   |  36 +++
 .../backends/FfmpegDecoder.cpp}               | 137 ++++----
 .../decoding/backends/FfmpegDecoder.h         |  86 +++++
 .../backends/MiniAudioDecoder.cpp}            | 135 ++------
 .../backends/MiniAudioDecoder.h}              |  29 +-
 .../decoding/{ => backends}/OsDecoderBase.h   |  15 +-
 .../decoding/backends/RawPcmDecoder.cpp       | 167 ++++++++++
 .../decoding/backends/RawPcmDecoder.h         |  45 +++
 .../cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h | 103 ------
 .../common/cpp/test/CMakeLists.txt            |   2 +-
 .../test/src/decoding/DecoderFactoryTest.cpp  | 136 ++++++++
 .../cpp/test/src/utils/AudioDecodingTest.cpp  |  24 +-
 .../src/utils/AudioFileConcatenatorTest.cpp   |   2 +-
 .../ios/audioapi/ios/core/utils/IOSDecoding.h |  11 +-
 .../audioapi/ios/core/utils/IOSDecoding.mm    |  35 +--
 43 files changed, 1579 insertions(+), 900 deletions(-)
 rename packages/react-native-audio-api/android/src/main/cpp/audioapi/{ => android}/AndroidDecoding.cpp (61%)
 rename packages/react-native-audio-api/android/src/main/cpp/audioapi/{ => android}/AndroidDecoding.h (54%)
 create mode 100644 packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecodingDataSource.cpp
 create mode 100644 packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecodingDataSource.h
 delete mode 100644 packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioDecoding.cpp
 rename packages/react-native-audio-api/common/cpp/audioapi/{core/utils => decoding}/AudioDecoding.h (85%)
 rename packages/react-native-audio-api/common/cpp/audioapi/{core/utils => decoding}/AudioFileConcatenator.cpp (88%)
 rename packages/react-native-audio-api/common/cpp/audioapi/{core/utils => decoding}/AudioFileConcatenator.h (79%)
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.cpp
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.h
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
 delete mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h
 rename packages/react-native-audio-api/common/cpp/audioapi/{core/utils => }/decoding/SeekDecoderDaemon.cpp (75%)
 rename packages/react-native-audio-api/common/cpp/audioapi/{core/utils => }/decoding/SeekDecoderDaemon.h (84%)
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/AudioDecoderBackend.h
 rename packages/react-native-audio-api/common/cpp/audioapi/{libs/ffmpeg/FFmpegDecoding.cpp => decoding/backends/FfmpegDecoder.cpp} (76%)
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.h
 rename packages/react-native-audio-api/common/cpp/audioapi/{libs/miniaudio/MiniAudioDecoding.cpp => decoding/backends/MiniAudioDecoder.cpp} (52%)
 rename packages/react-native-audio-api/common/cpp/audioapi/{libs/miniaudio/MiniAudioDecoding.h => decoding/backends/MiniAudioDecoder.h} (54%)
 rename packages/react-native-audio-api/common/cpp/audioapi/decoding/{ => backends}/OsDecoderBase.h (77%)
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
 create mode 100644 packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.h
 delete mode 100644 packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
 create mode 100644 packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp

diff --git a/.claude/skills/build-compilation-dependencies/SKILL.md b/.claude/skills/build-compilation-dependencies/SKILL.md
index a8ae88792..eb13ffad2 100644
--- a/.claude/skills/build-compilation-dependencies/SKILL.md
+++ b/.claude/skills/build-compilation-dependencies/SKILL.md
@@ -29,7 +29,7 @@ react-native-audio-api/
 │   │   └── src/main/cpp/audioapi/
 │   │       └── CMakeLists.txt          # Actual Android C++ build target
 │   ├── common/cpp/audioapi/            # Shared C++ (used by all platforms)
-│   │   ├── decoding/                   # Incremental + OS decoder contracts (no external deps)
+│   │   ├── decoding/                   # Decoder factory, backends, SeekDecoderDaemon, AudioDecoding, AudioFileConcatenator
 │   │   ├── libs/                       # Third-party wrappers (FFmpeg, miniaudio, pffft, …)
 │   │   └── external/                   # Prebuilt binaries per platform
 │   │       ├── android/                # .a static libs (Opus, Ogg, Vorbis, OpenSSL)
@@ -198,7 +198,7 @@ The `build/` directory is deleted after each run.
 ### Key design decisions
 - Completely standalone — no Gradle, no Xcode, no prebuilt Android libraries needed
 - Sources resolved from `node_modules` (symlinked to `packages/` in yarn workspaces)
-- HostObjects, worklets nodes, AudioContext, and FFmpegDecoding are excluded from the test build
+- HostObjects, worklets nodes, AudioContext, and FfmpegDecoder are excluded from the test build
 - Compile definitions: `RN_AUDIO_API_ENABLE_WORKLETS=0`, `RN_AUDIO_API_TEST=1`, `RN_AUDIO_API_FFMPEG_DISABLED=1`
 - Google Test auto-fetched via `FetchContent` if not installed locally
 - New test files in `test/src/**/*.cpp` are picked up automatically by glob — no CMakeLists edit needed
diff --git a/.claude/skills/build-compilation-dependencies/build-details.md b/.claude/skills/build-compilation-dependencies/build-details.md
index 3ace17990..01df06ca9 100644
--- a/.claude/skills/build-compilation-dependencies/build-details.md
+++ b/.claude/skills/build-compilation-dependencies/build-details.md
@@ -125,7 +125,7 @@ file(GLOB_RECURSE COMMON_CPP_SOURCES CONFIGURE_DEPENDS "${COMMON_CPP_DIR}/audioa
 ```cmake
 if(RN_AUDIO_API_FFMPEG_DISABLED)
   list(REMOVE_ITEM COMMON_CPP_SOURCES
-    "${COMMON_CPP_DIR}/audioapi/libs/ffmpeg/FFmpegDecoding.cpp"
+    "${COMMON_CPP_DIR}/audioapi/decoding/backends/FfmpegDecoder.cpp"
   )
 endif()
 ```
@@ -262,7 +262,7 @@ This means **tests build against the installed/published version of the library*
 list(FILTER RNAUDIOAPI_SRC EXCLUDE REGEX ".*/audioapi/HostObjects/.*\\.cpp$")  # no JSI in tests
 list(FILTER RNAUDIOAPI_SRC EXCLUDE REGEX ".*/Worklet.*Node\\.cpp$")            # worklets not compiled
 list(REMOVE_ITEM RNAUDIOAPI_SRC ... "AudioContext.cpp")                         # needs real audio I/O
-list(REMOVE_ITEM RNAUDIOAPI_SRC ... "FFmpegDecoding.cpp")                       # FFmpeg disabled in tests
+list(REMOVE_ITEM RNAUDIOAPI_SRC ... "FfmpegDecoder.cpp")                       # FFmpeg disabled in tests
 ```
 
 ### Compile definitions always set in tests
diff --git a/THIRD_PARTY.md b/THIRD_PARTY.md
index 325da230b..5bd078df6 100644
--- a/THIRD_PARTY.md
+++ b/THIRD_PARTY.md
@@ -16,7 +16,7 @@ Copyright (c) The WebKit Authors
 In addition we utilize FFmpeg library under GNU Lesser General Public License (LGPL) version 2.1 or later
 
 - Source: https://github.com/FFmpeg/FFmpeg/releases/tag/n8.0
-- Used in audio decoding module [packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp](https://github.com/software-mansion/react-native-audio-api/blob/main/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp)
+- Used in audio decoding module [packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp](https://github.com/software-mansion/react-native-audio-api/blob/main/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp)
 - Instruction for relinking: [packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/INSTRUCTIONS.md](https://github.com/software-mansion/react-native-audio-api/blob/main/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/INSTRUCTIONS.md)
 
 Other LGPL components may be included as dependencies.
diff --git a/packages/react-native-audio-api/RNAudioAPI.podspec b/packages/react-native-audio-api/RNAudioAPI.podspec
index ed96ed58d..f0906f5a5 100644
--- a/packages/react-native-audio-api/RNAudioAPI.podspec
+++ b/packages/react-native-audio-api/RNAudioAPI.podspec
@@ -30,7 +30,7 @@ Pod::Spec.new do |s|
 
   s.subspec "audioapi" do |ss|
     ss.source_files = "common/cpp/audioapi/**/*.{cpp,c,h,hpp}", "common/cpp/test/src/graph/AudioThreadGuard.cpp"
-    ss.exclude_files = $RN_AUDIO_API_FFMPEG_DISABLED ? ["common/cpp/audioapi/libs/ffmpeg/**"] : []
+    ss.exclude_files = $RN_AUDIO_API_FFMPEG_DISABLED ? ["common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp"] : []
     ss.header_dir = "audioapi"
     ss.header_mappings_dir = "common/cpp/audioapi"
 
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/CMakeLists.txt b/packages/react-native-audio-api/android/src/main/cpp/audioapi/CMakeLists.txt
index 7be6ed2d9..3d2ce6da0 100644
--- a/packages/react-native-audio-api/android/src/main/cpp/audioapi/CMakeLists.txt
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/CMakeLists.txt
@@ -19,7 +19,7 @@ endforeach()
 
 if (RN_AUDIO_API_FFMPEG_DISABLED)
   list(REMOVE_ITEM COMMON_CPP_SOURCES
-    "${COMMON_CPP_DIR}/audioapi/libs/ffmpeg/FFmpegDecoding.cpp"
+    "${COMMON_CPP_DIR}/audioapi/decoding/backends/FfmpegDecoder.cpp"
   )
 endif()
 
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
similarity index 61%
rename from packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp
rename to packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
index 0c317cef5..8b3444125 100644
--- a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.cpp
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
@@ -1,8 +1,10 @@
-#include <audioapi/AndroidDecoding.h>
+#include <audioapi/android/AndroidDecoding.h>
+#include <audioapi/android/AndroidDecodingDataSource.h>
 
 #include <audioapi/dsp/r8brain/Resampler.hpp>
 #include <audioapi/utils/AudioBuffer.hpp>
 
+#include <android/api-level.h>
 #include <media/NdkMediaCodec.h>
 #include <media/NdkMediaExtractor.h>
 #include <media/NdkMediaFormat.h>
@@ -61,18 +63,45 @@ using MediaExtractorPtr = std::unique_ptr<AMediaExtractor, MediaExtractorDeleter
 using MediaCodecPtr = std::unique_ptr<AMediaCodec, MediaCodecDeleter>;
 using FilePtr = std::unique_ptr<FILE, FileDeleter>;
 
+decoding::DecoderResult attachMemoryExtractorViaTempFile(
+    AMediaExtractor *extractor,
+    FilePtr &tempFile,
+    const std::vector<uint8_t> &data) {
+  tempFile.reset(tmpfile());
+  if (tempFile == nullptr || fwrite(data.data(), 1, data.size(), tempFile.get()) != data.size()) {
+    return Err("AndroidDecoder::open: temp file write failed");
+  }
+  fflush(tempFile.get());
+  const int fd = fileno(tempFile.get());
+  if (fd < 0) {
+    return Err("AndroidDecoder::open: fileno failed");
+  }
+
+  if (AMediaExtractor_setDataSourceFd(extractor, fd, 0, static_cast<off64_t>(data.size())) !=
+      AMEDIA_OK) {
+    return Err("AndroidDecoder::open setDataSourceFd failed");
+  }
+  return Ok(None);
+}
+
 } // namespace
 
 // Native reader state, reached through AndroidDecoder::impl_. Kept out of the
 // shared header so NDK types never leak into cross-platform code.
 struct AndroidDecoderState {
-  // Declaration order matters: destroy codec before extractor, and keep the
-  // temp file alive until after the extractor releases its fd (members destroy
-  // in reverse order).
+  // Declaration order matters: destroy codec before extractor; keep encoded
+  // bytes / temp file / data source alive until the extractor is torn down.
+  std::vector<uint8_t> encodedMemory;
+  MemoryDataSourceContext memorySourceContext{};
   FilePtr tempFile;
+  AndroidMemoryDataSource dataSource;
   MediaExtractorPtr extractor;
   MediaCodecPtr codec;
 
+  int audioTrackIndex = -1;
+  std::string codecMime;
+  // Requested client rate from open() (0 = follow codec native rate).
+  int requestedOutputSampleRate = 0;
   int nativeSampleRate = 0;
   int outputRate = 0;
   int channels = 0;
@@ -133,6 +162,66 @@ void appendNativePcm(AndroidDecoderState &state, const uint8_t *bytes, size_t by
   }
 }
 
+void setupResamplerIfNeeded(AndroidDecoderState &state) {
+  if (state.channels <= 0) {
+    state.channels = 1;
+  }
+  if (state.nativeSampleRate <= 0) {
+    state.nativeSampleRate = 44100;
+  }
+
+  state.outputRate = state.requestedOutputSampleRate > 0 ? state.requestedOutputSampleRate
+                                                         : state.nativeSampleRate;
+
+  if (state.outputRate == state.nativeSampleRate) {
+    state.resampler.reset();
+    state.resampleIn.reset();
+    state.resampleOut.reset();
+    return;
+  }
+
+  state.resampler = std::make_unique<r8b::MultiChannelResampler>(
+      state.nativeSampleRate, state.outputRate, state.channels, kResampleMaxInFrames);
+  state.resampleIn = std::make_unique<AudioBuffer>(
+      static_cast<size_t>(kResampleMaxInFrames),
+      state.channels,
+      static_cast<float>(state.nativeSampleRate));
+  state.resampleOut = std::make_unique<AudioBuffer>(
+      static_cast<size_t>(std::max(1, state.resampler->getMaxOutLen())),
+      state.channels,
+      static_cast<float>(state.outputRate));
+}
+
+// Applies MediaCodec output format. When rate/channels change vs track metadata
+// (common with AAC), rebuilds the resampler and drops PCM produced under the
+// previous layout so leftover samples are not misinterpreted.
+void applyCodecOutputFormat(AndroidDecoderState &state, AMediaFormat *outFormat) {
+  const int previousChannels = state.channels;
+  const int previousNativeRate = state.nativeSampleRate;
+
+  AMediaFormat_getInt32(outFormat, AMEDIAFORMAT_KEY_SAMPLE_RATE, &state.nativeSampleRate);
+  AMediaFormat_getInt32(outFormat, AMEDIAFORMAT_KEY_CHANNEL_COUNT, &state.channels);
+  if (!AMediaFormat_getInt32(outFormat, "pcm-encoding", &state.pcmEncoding)) {
+    state.pcmEncoding = kEncodingPcm16;
+  }
+  if (state.channels <= 0) {
+    state.channels = previousChannels > 0 ? previousChannels : 1;
+  }
+  if (state.nativeSampleRate <= 0) {
+    state.nativeSampleRate = previousNativeRate > 0 ? previousNativeRate : 44100;
+  }
+
+  if (state.channels == previousChannels && state.nativeSampleRate == previousNativeRate) {
+    return;
+  }
+
+  state.nativeLeftover.clear();
+  state.nativeCursor = 0;
+  state.outLeftover.clear();
+  state.outCursor = 0;
+  setupResamplerIfNeeded(state);
+}
+
 // Advances the codec one step: feeds at most one input packet and drains at
 // most one output buffer into nativeLeftover. Sets outputEnded at EOS.
 void pumpCodec(AndroidDecoderState &state) {
@@ -181,12 +270,10 @@ void pumpCodec(AndroidDecoderState &state) {
     }
   } else if (outIndex == AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED) {
     AMediaFormat *outFormat = AMediaCodec_getOutputFormat(codec);
-    AMediaFormat_getInt32(outFormat, AMEDIAFORMAT_KEY_SAMPLE_RATE, &state.nativeSampleRate);
-    AMediaFormat_getInt32(outFormat, AMEDIAFORMAT_KEY_CHANNEL_COUNT, &state.channels);
-    if (!AMediaFormat_getInt32(outFormat, "pcm-encoding", &state.pcmEncoding)) {
-      state.pcmEncoding = kEncodingPcm16;
+    if (outFormat != nullptr) {
+      applyCodecOutputFormat(state, outFormat);
+      AMediaFormat_delete(outFormat);
     }
-    AMediaFormat_delete(outFormat);
   } else if (outIndex == AMEDIACODEC_INFO_TRY_AGAIN_LATER) {
     if (state.inputEnded && ++state.tryAgainAfterEos > kMaxTryAgainAfterEos) {
       state.outputEnded = true;
@@ -208,15 +295,27 @@ size_t availableFrames(const std::vector<float> &buffer, size_t cursor, int chan
 // or the codec is drained — returning 0 early would be misread as end-of-stream
 // by callers (and could trigger a loop-to-start seek).
 size_t produceResampled(AndroidDecoderState &state) {
-  const int ch = state.channels;
-
   while (true) {
+    const int ch = state.channels;
+
     while (availableFrames(state.nativeLeftover, state.nativeCursor, ch) == 0 &&
            !state.outputEnded) {
       pumpCodec(state);
     }
 
-    const size_t availIn = availableFrames(state.nativeLeftover, state.nativeCursor, ch);
+    // Format change during pump may drop the resampler when native rate now
+    // matches the requested output rate — hand control back to the native path.
+    if (state.resampler == nullptr) {
+      if (availableFrames(state.nativeLeftover, state.nativeCursor, state.channels) > 0 ||
+          !state.outputEnded) {
+        return 1;
+      }
+      return 0;
+    }
+
+    // Format may have changed during pumpCodec; re-read channel count.
+    const int channels = state.channels;
+    const size_t availIn = availableFrames(state.nativeLeftover, state.nativeCursor, channels);
     if (availIn == 0) {
       return 0; // Codec fully drained and no leftover: genuine EOF.
     }
@@ -224,7 +323,7 @@ size_t produceResampled(AndroidDecoderState &state) {
     const auto inFrames = static_cast<int>(std::min<size_t>(availIn, kResampleMaxInFrames));
     state.resampleIn->deinterleaveFrom(
         state.nativeLeftover.data() + state.nativeCursor, static_cast<size_t>(inFrames));
-    state.nativeCursor += static_cast<size_t>(inFrames) * static_cast<size_t>(ch);
+    state.nativeCursor += static_cast<size_t>(inFrames) * static_cast<size_t>(channels);
 
     const int outFrames = state.resampler->process(*state.resampleIn, inFrames, *state.resampleOut);
     if (outFrames <= 0) {
@@ -234,19 +333,20 @@ size_t produceResampled(AndroidDecoderState &state) {
 
     compactConsumed(state.outLeftover, state.outCursor);
     const size_t base = state.outLeftover.size();
-    state.outLeftover.resize(base + static_cast<size_t>(outFrames) * static_cast<size_t>(ch));
+    state.outLeftover.resize(base + static_cast<size_t>(outFrames) * static_cast<size_t>(channels));
     state.resampleOut->interleaveTo(
         state.outLeftover.data() + base, static_cast<size_t>(outFrames));
     return static_cast<size_t>(outFrames);
   }
 }
 
-// Selects the audio track, starts the codec, reads duration, and builds the
-// resampler when the requested output rate differs from the native rate.
-decoding::DecoderResult configureState(AndroidDecoderState &state, int outputSampleRate) {
+// Selects the audio track and reads container metadata. MediaCodec is started
+// lazily on the first read/seek so probeDuration() avoids codec spin-up cost.
+decoding::DecoderResult configureExtractorMetadata(
+    AndroidDecoderState &state,
+    int outputSampleRate) {
   auto *extractor = state.extractor.get();
-  const int trackCount = AMediaExtractor_getTrackCount(extractor);
-  int audioTrack = -1;
+  const auto trackCount = static_cast<int>(AMediaExtractor_getTrackCount(extractor));
   AMediaFormat *format = nullptr;
 
   for (int i = 0; i < trackCount; ++i) {
@@ -254,30 +354,52 @@ decoding::DecoderResult configureState(AndroidDecoderState &state, int outputSam
     const char *mime = nullptr;
     if (AMediaFormat_getString(candidate, AMEDIAFORMAT_KEY_MIME, &mime) && mime != nullptr &&
         std::strncmp(mime, "audio/", 6) == 0) {
-      audioTrack = i;
+      state.audioTrackIndex = i;
       format = candidate;
       break;
     }
     AMediaFormat_delete(candidate);
   }
 
-  if (audioTrack < 0 || format == nullptr) {
+  if (state.audioTrackIndex < 0 || format == nullptr) {
     return Err("AndroidDecoder: no audio track found");
   }
 
-  if (AMediaExtractor_selectTrack(extractor, audioTrack) != AMEDIA_OK) {
+  if (AMediaExtractor_selectTrack(extractor, state.audioTrackIndex) != AMEDIA_OK) {
     AMediaFormat_delete(format);
     return Err("AndroidDecoder: selectTrack failed");
   }
 
   const char *mime = nullptr;
   AMediaFormat_getString(format, AMEDIAFORMAT_KEY_MIME, &mime);
+  state.codecMime = mime != nullptr ? mime : "audio/mp4a-latm";
   AMediaFormat_getInt32(format, AMEDIAFORMAT_KEY_SAMPLE_RATE, &state.nativeSampleRate);
   AMediaFormat_getInt32(format, AMEDIAFORMAT_KEY_CHANNEL_COUNT, &state.channels);
   int64_t durationUs = 0;
   AMediaFormat_getInt64(format, AMEDIAFORMAT_KEY_DURATION, &durationUs);
+  AMediaFormat_delete(format);
+
+  state.durationSeconds = durationUs > 0 ? static_cast<double>(durationUs) / 1e6 : 0.0;
+  state.requestedOutputSampleRate = outputSampleRate;
+  setupResamplerIfNeeded(state);
+  return Ok(None);
+}
+
+decoding::DecoderResult ensureCodecStarted(AndroidDecoderState &state) {
+  if (state.codec != nullptr) {
+    return Ok(None);
+  }
+  if (state.extractor == nullptr || state.audioTrackIndex < 0) {
+    return Err("AndroidDecoder: extractor is not configured");
+  }
+
+  AMediaFormat *format =
+      AMediaExtractor_getTrackFormat(state.extractor.get(), state.audioTrackIndex);
+  if (format == nullptr) {
+    return Err("AndroidDecoder: getTrackFormat failed");
+  }
 
-  AMediaCodec *codec = AMediaCodec_createDecoderByType(mime != nullptr ? mime : "audio/mp4a-latm");
+  AMediaCodec *codec = AMediaCodec_createDecoderByType(state.codecMime.c_str());
   if (codec == nullptr) {
     AMediaFormat_delete(format);
     return Err("AndroidDecoder: createDecoderByType failed");
@@ -293,32 +415,34 @@ decoding::DecoderResult configureState(AndroidDecoderState &state, int outputSam
     AMediaCodec_delete(codec);
     return Err("AndroidDecoder: start failed");
   }
+
   state.codec.reset(codec);
+  state.inputEnded = false;
+  state.outputEnded = false;
+  state.tryAgainAfterEos = 0;
+  return Ok(None);
+}
 
-  if (state.channels <= 0) {
-    state.channels = 1;
-  }
-  if (state.nativeSampleRate <= 0) {
-    state.nativeSampleRate = 44100;
+decoding::DecoderResult attachMemoryExtractor(
+    AndroidDecoderState &state,
+    const std::vector<uint8_t> &data) {
+  state.extractor.reset(AMediaExtractor_new());
+  if (state.extractor == nullptr) {
+    return Err("AndroidDecoder::open: AMediaExtractor_new failed");
   }
 
-  state.outputRate = outputSampleRate > 0 ? outputSampleRate : state.nativeSampleRate;
-  state.durationSeconds = durationUs > 0 ? static_cast<double>(durationUs) / 1e6 : 0.0;
-
-  if (state.outputRate != state.nativeSampleRate) {
-    state.resampler = std::make_unique<r8b::MultiChannelResampler>(
-        state.nativeSampleRate, state.outputRate, state.channels, kResampleMaxInFrames);
-    state.resampleIn = std::make_unique<AudioBuffer>(
-        static_cast<size_t>(kResampleMaxInFrames),
-        state.channels,
-        static_cast<float>(state.nativeSampleRate));
-    state.resampleOut = std::make_unique<AudioBuffer>(
-        static_cast<size_t>(std::max(1, state.resampler->getMaxOutLen())),
-        state.channels,
-        static_cast<float>(state.outputRate));
+  AMediaExtractor *extractor = state.extractor.get();
+  if (android_get_device_api_level() >= kMediaDataSourceMinApiLevel) {
+    std::vector<uint8_t> owned = data;
+    return attachMemoryExtractorViaDataSource(
+        extractor,
+        state.dataSource,
+        state.encodedMemory,
+        state.memorySourceContext,
+        std::move(owned));
   }
 
-  return Ok(None);
+  return attachMemoryExtractorViaTempFile(extractor, state.tempFile, data);
 }
 
 } // namespace
@@ -329,23 +453,23 @@ AndroidDecoder::~AndroidDecoder() {
   close();
 }
 
-decoding::DecoderResult AndroidDecoder::openFile(int outputSampleRate, const std::string &path) {
+decoding::DecoderResult AndroidDecoder::open(const decoding::LocalFileSource &source) {
   close();
-  if (path.empty()) {
-    return Err("AndroidDecoder::openFile failed: path is empty");
+  if (source.path.empty()) {
+    return Err("AndroidDecoder::open failed: path is empty");
   }
 
   auto state = std::make_unique<AndroidDecoderState>();
   state->extractor.reset(AMediaExtractor_new());
   if (state->extractor == nullptr) {
-    return Err("AndroidDecoder::openFile: AMediaExtractor_new failed");
+    return Err("AndroidDecoder::open: AMediaExtractor_new failed");
   }
 
-  if (AMediaExtractor_setDataSource(state->extractor.get(), path.c_str()) != AMEDIA_OK) {
-    return Err("AndroidDecoder::openFile setDataSource failed");
+  if (AMediaExtractor_setDataSource(state->extractor.get(), source.path.c_str()) != AMEDIA_OK) {
+    return Err("AndroidDecoder::open setDataSource failed");
   }
 
-  auto configured = configureState(*state, outputSampleRate);
+  auto configured = configureExtractorMetadata(*state, source.sampleRate);
   if (configured.is_err()) {
     return configured;
   }
@@ -359,39 +483,19 @@ decoding::DecoderResult AndroidDecoder::openFile(int outputSampleRate, const std
   return Ok(None);
 }
 
-decoding::DecoderResult
-AndroidDecoder::openMemory(int outputSampleRate, const void *data, size_t size) {
+decoding::DecoderResult AndroidDecoder::open(const decoding::EncodedMemorySource &source) {
   close();
-  if (data == nullptr || size == 0) {
-    return Err("AndroidDecoder::openMemory failed: empty input");
+  if (source.data.empty()) {
+    return Err("AndroidDecoder::open failed: empty input");
   }
 
   auto state = std::make_unique<AndroidDecoderState>();
 
-  // Use an anonymous temp file + fd. AMediaExtractor_setDataSourceFd is API 21+,
-  // so this path works for minSdk 21/24 without needing AMediaDataSource (API 28).
-  state->tempFile.reset(tmpfile());
-  if (state->tempFile == nullptr || fwrite(data, 1, size, state->tempFile.get()) != size) {
-    return Err("AndroidDecoder::openMemory: temp file write failed");
-  }
-  fflush(state->tempFile.get());
-  const int fd = fileno(state->tempFile.get());
-  if (fd < 0) {
-    return Err("AndroidDecoder::openMemory: fileno failed");
-  }
-
-  state->extractor.reset(AMediaExtractor_new());
-  if (state->extractor == nullptr) {
-    return Err("AndroidDecoder::openMemory: AMediaExtractor_new failed");
+  if (auto attached = attachMemoryExtractor(*state, source.data); attached.is_err()) {
+    return attached;
   }
 
-  const media_status_t status =
-      AMediaExtractor_setDataSourceFd(state->extractor.get(), fd, 0, static_cast<off64_t>(size));
-  if (status != AMEDIA_OK) {
-    return Err("AndroidDecoder::openMemory setDataSourceFd failed");
-  }
-
-  auto configured = configureState(*state, outputSampleRate);
+  auto configured = configureExtractorMetadata(*state, source.sampleRate);
   if (configured.is_err()) {
     return configured;
   }
@@ -412,11 +516,29 @@ size_t AndroidDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
   }
 
   auto &state = *impl_;
-  const int ch = outputChannels_;
-  const bool resample = state.resampler != nullptr;
+  if (ensureCodecStarted(state).is_err()) {
+    return 0;
+  }
+
   size_t filled = 0; // frames
+  const int initialChannels = state.channels;
 
   while (filled < frameCount) {
+    // Keep OsDecoderBase metadata aligned with codec output (may change on
+    // AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED).
+    outputChannels_ = state.channels;
+    outputSampleRate_ = state.outputRate;
+    if (outputChannels_ <= 0) {
+      break;
+    }
+    // Avoid mixing channel layouts inside a single caller buffer.
+    if (filled > 0 && state.channels != initialChannels) {
+      outputChannels_ = initialChannels;
+      break;
+    }
+
+    const int ch = outputChannels_;
+    const bool resample = state.resampler != nullptr;
     std::vector<float> &served = resample ? state.outLeftover : state.nativeLeftover;
     size_t &cursor = resample ? state.outCursor : state.nativeCursor;
 
@@ -444,6 +566,14 @@ size_t AndroidDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
     }
   }
 
+  // Prefer metadata that matches frames actually written this call when a
+  // mid-read format change forced an early return.
+  if (filled > 0 && state.channels != initialChannels) {
+    outputChannels_ = initialChannels;
+  } else {
+    outputChannels_ = state.channels;
+    outputSampleRate_ = state.outputRate;
+  }
   framePosition_ += static_cast<int64_t>(filled);
   return filled;
 }
@@ -457,14 +587,16 @@ decoding::DecoderResult AndroidDecoder::seekToTime(double seconds) {
   }
 
   auto &state = *impl_;
+  if (auto started = ensureCodecStarted(state); started.is_err()) {
+    return started;
+  }
+
   const auto seekUs = static_cast<int64_t>(std::llround(seconds * 1e6));
   if (AMediaExtractor_seekTo(state.extractor.get(), seekUs, AMEDIAEXTRACTOR_SEEK_CLOSEST_SYNC) !=
       AMEDIA_OK) {
     return Err("AndroidDecoder::seekToTime: AMediaExtractor_seekTo failed");
   }
-  if (state.codec != nullptr) {
-    AMediaCodec_flush(state.codec.get());
-  }
+  AMediaCodec_flush(state.codec.get());
 
   state.nativeLeftover.clear();
   state.nativeCursor = 0;
@@ -476,8 +608,7 @@ decoding::DecoderResult AndroidDecoder::seekToTime(double seconds) {
 
   // Reset resampler state so pre-seek samples don't smear into the new position.
   if (state.resampler != nullptr) {
-    state.resampler = std::make_unique<r8b::MultiChannelResampler>(
-        state.nativeSampleRate, state.outputRate, state.channels, kResampleMaxInFrames);
+    setupResamplerIfNeeded(state);
   }
 
   framePosition_ =
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.h
similarity index 54%
rename from packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h
rename to packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.h
index 7b5c65de4..840c851c4 100644
--- a/packages/react-native-audio-api/android/src/main/cpp/audioapi/AndroidDecoding.h
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.h
@@ -1,11 +1,11 @@
 #pragma once
 
-#include <audioapi/decoding/OsDecoderBase.h>
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/backends/OsDecoderBase.h>
 #include <audioapi/utils/Macros.h>
 
 #include <cstddef>
 #include <memory>
-#include <string>
 
 namespace audioapi::android_decoder {
 
@@ -15,18 +15,19 @@ struct AndroidDecoderState;
  * Android MediaExtractor + MediaCodec incremental decoder.
  *
  * Opens local files or in-memory buffers and pulls interleaved float PCM on
- * demand. Remote URL / HLS decoding stays on FFmpeg.
+ * demand. Container metadata (including duration) is read at open time; the
+ * MediaCodec pipeline starts lazily on the first read or seek. In-memory
+ * sources use AMediaDataSource on API 28+ (runtime check); API 21–27 falls
+ * back to a temp file + fd. Remote URL / HLS decoding stays on FFmpeg.
  */
-class AndroidDecoder : public OsDecoderBase {
+class AndroidDecoder : public decoding::OsDecoderBase {
  public:
   AndroidDecoder();
   ~AndroidDecoder() override;
   DELETE_COPY_AND_MOVE(AndroidDecoder);
 
-  [[nodiscard]] decoding::DecoderResult openFile(int outputSampleRate, const std::string &path)
-      override;
-  [[nodiscard]] decoding::DecoderResult
-  openMemory(int outputSampleRate, const void *data, size_t size) override;
+  [[nodiscard]] decoding::DecoderResult open(const decoding::LocalFileSource &source);
+  [[nodiscard]] decoding::DecoderResult open(const decoding::EncodedMemorySource &source);
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
   [[nodiscard]] decoding::DecoderResult seekToTime(double seconds) override;
 
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecodingDataSource.cpp b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecodingDataSource.cpp
new file mode 100644
index 000000000..b88f416de
--- /dev/null
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecodingDataSource.cpp
@@ -0,0 +1,173 @@
+#include <audioapi/android/AndroidDecodingDataSource.h>
+
+#include <media/NdkMediaError.h>
+#include <media/NdkMediaExtractor.h>
+
+#include <dlfcn.h>
+#include <algorithm>
+#include <cstring>
+#include <utility>
+#include <vector>
+
+// AMediaDataSource / setDataSourceCustom require API 28. To support lower API
+// levels at build/link time while using these on newer devices, we load them
+// dynamically from libmediandk.so.
+#if __has_include(<media/NdkMediaDataSource.h>)
+#include <media/NdkMediaDataSource.h>
+#else
+// Fallback definitions if header is missing (unlikely given it compiled).
+struct AMediaDataSource;
+typedef ssize_t (
+    *AMediaDataSourceReadAt)(void *userdata, off64_t offset, void *buffer, size_t size);
+typedef ssize_t (*AMediaDataSourceGetSize)(void *userdata);
+typedef void (*AMediaDataSourceClose)(void *userdata);
+#endif
+
+namespace audioapi::android_decoder {
+
+namespace {
+
+// Function pointer types for dynamic loading.
+typedef AMediaDataSource *(*pfn_AMediaDataSource_new)();
+typedef void (*pfn_AMediaDataSource_delete)(AMediaDataSource *);
+typedef void (*pfn_AMediaDataSource_setUserdata)(AMediaDataSource *, void *);
+typedef void (*pfn_AMediaDataSource_setReadAt)(AMediaDataSource *, AMediaDataSourceReadAt);
+typedef void (*pfn_AMediaDataSource_setGetSize)(AMediaDataSource *, AMediaDataSourceGetSize);
+typedef void (*pfn_AMediaDataSource_setClose)(AMediaDataSource *, AMediaDataSourceClose);
+typedef media_status_t (
+    *pfn_AMediaExtractor_setDataSourceCustom)(AMediaExtractor *, AMediaDataSource *);
+
+struct DynamicNDK {
+  pfn_AMediaDataSource_new AMediaDataSource_new = nullptr;
+  pfn_AMediaDataSource_delete AMediaDataSource_delete = nullptr;
+  pfn_AMediaDataSource_setUserdata AMediaDataSource_setUserdata = nullptr;
+  pfn_AMediaDataSource_setReadAt AMediaDataSource_setReadAt = nullptr;
+  pfn_AMediaDataSource_setGetSize AMediaDataSource_setGetSize = nullptr;
+  pfn_AMediaDataSource_setClose AMediaDataSource_setClose = nullptr;
+  pfn_AMediaExtractor_setDataSourceCustom AMediaExtractor_setDataSourceCustom = nullptr;
+
+  bool initialized = false;
+
+  static DynamicNDK &get() {
+    static DynamicNDK instance;
+    if (!instance.initialized) {
+      void *lib = dlopen("libmediandk.so", RTLD_NOW);
+      if (lib) {
+        instance.AMediaDataSource_new =
+            (pfn_AMediaDataSource_new)dlsym(lib, "AMediaDataSource_new");
+        instance.AMediaDataSource_delete =
+            (pfn_AMediaDataSource_delete)dlsym(lib, "AMediaDataSource_delete");
+        instance.AMediaDataSource_setUserdata =
+            (pfn_AMediaDataSource_setUserdata)dlsym(lib, "AMediaDataSource_setUserdata");
+        instance.AMediaDataSource_setReadAt =
+            (pfn_AMediaDataSource_setReadAt)dlsym(lib, "AMediaDataSource_setReadAt");
+        instance.AMediaDataSource_setGetSize =
+            (pfn_AMediaDataSource_setGetSize)dlsym(lib, "AMediaDataSource_setGetSize");
+        instance.AMediaDataSource_setClose =
+            (pfn_AMediaDataSource_setClose)dlsym(lib, "AMediaDataSource_setClose");
+        instance.AMediaExtractor_setDataSourceCustom =
+            (pfn_AMediaExtractor_setDataSourceCustom)dlsym(
+                lib, "AMediaExtractor_setDataSourceCustom");
+      }
+      instance.initialized = true;
+    }
+    return instance;
+  }
+
+  bool isAvailable() const {
+    return AMediaDataSource_new != nullptr && AMediaDataSource_delete != nullptr &&
+        AMediaExtractor_setDataSourceCustom != nullptr;
+  }
+};
+
+ssize_t memoryDataSourceReadAt(void *userdata, off64_t offset, void *buffer, size_t size) {
+  auto *context = static_cast<MemoryDataSourceContext *>(userdata);
+  if (context == nullptr || context->data == nullptr || offset < 0 ||
+      static_cast<size_t>(offset) >= context->size) {
+    return -1;
+  }
+  const size_t available = context->size - static_cast<size_t>(offset);
+  const size_t toCopy = std::min(size, available);
+  if (toCopy > 0) {
+    std::memcpy(buffer, context->data + offset, toCopy);
+  }
+  return static_cast<ssize_t>(toCopy);
+}
+
+ssize_t memoryDataSourceGetSize(void *userdata) {
+  auto *context = static_cast<MemoryDataSourceContext *>(userdata);
+  if (context == nullptr) {
+    return -1;
+  }
+  return static_cast<ssize_t>(context->size);
+}
+
+void memoryDataSourceClose(void * /*userdata*/) {}
+
+} // namespace
+
+AndroidMemoryDataSource::~AndroidMemoryDataSource() {
+  reset();
+}
+
+AndroidMemoryDataSource::AndroidMemoryDataSource(AndroidMemoryDataSource &&other) noexcept
+    : handle_(other.handle_) {
+  other.handle_ = nullptr;
+}
+
+AndroidMemoryDataSource &AndroidMemoryDataSource::operator=(
+    AndroidMemoryDataSource &&other) noexcept {
+  if (this != &other) {
+    reset();
+    handle_ = other.handle_;
+    other.handle_ = nullptr;
+  }
+  return *this;
+}
+
+void AndroidMemoryDataSource::reset() {
+  if (handle_ != nullptr) {
+    auto &ndk = DynamicNDK::get();
+    if (ndk.AMediaDataSource_delete) {
+      ndk.AMediaDataSource_delete(static_cast<AMediaDataSource *>(handle_));
+    }
+    handle_ = nullptr;
+  }
+}
+
+decoding::DecoderResult attachMemoryExtractorViaDataSource(
+    AMediaExtractor *extractor,
+    AndroidMemoryDataSource &dataSource,
+    std::vector<uint8_t> &encodedMemory,
+    MemoryDataSourceContext &memorySourceContext,
+    std::vector<uint8_t> data) {
+
+  auto &ndk = DynamicNDK::get();
+  if (!ndk.isAvailable()) {
+    return Err(
+        "AndroidDecoder: AMediaDataSource is not supported on this device (requires API 28)");
+  }
+
+  encodedMemory = std::move(data);
+  memorySourceContext = {encodedMemory.data(), encodedMemory.size()};
+
+  AMediaDataSource *rawDataSource = ndk.AMediaDataSource_new();
+  if (rawDataSource == nullptr) {
+    return Err("AndroidDecoder::open: AMediaDataSource_new failed");
+  }
+  ndk.AMediaDataSource_setUserdata(rawDataSource, &memorySourceContext);
+  ndk.AMediaDataSource_setReadAt(rawDataSource, memoryDataSourceReadAt);
+  ndk.AMediaDataSource_setGetSize(rawDataSource, memoryDataSourceGetSize);
+  ndk.AMediaDataSource_setClose(rawDataSource, memoryDataSourceClose);
+
+  if (ndk.AMediaExtractor_setDataSourceCustom(extractor, rawDataSource) != AMEDIA_OK) {
+    ndk.AMediaDataSource_delete(rawDataSource);
+    return Err("AndroidDecoder::open setDataSourceCustom failed");
+  }
+
+  dataSource.reset();
+  dataSource.handle_ = rawDataSource;
+  return Ok(None);
+}
+
+} // namespace audioapi::android_decoder
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecodingDataSource.h b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecodingDataSource.h
new file mode 100644
index 000000000..8d2aacefe
--- /dev/null
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecodingDataSource.h
@@ -0,0 +1,52 @@
+#pragma once
+
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+struct AMediaExtractor;
+
+namespace audioapi::android_decoder {
+
+// AMediaDataSource / setDataSourceCustom require API 28. minSdk may be lower, so
+// implementations live in AndroidDecodingDataSource.cpp (compiled at API 28).
+constexpr int kMediaDataSourceMinApiLevel = 28;
+
+struct MemoryDataSourceContext {
+  const uint8_t *data = nullptr;
+  size_t size = 0;
+};
+
+/// Opaque owning handle for AMediaDataSource (defined in the API 28 translation unit).
+class AndroidMemoryDataSource {
+ public:
+  AndroidMemoryDataSource() = default;
+  ~AndroidMemoryDataSource();
+  AndroidMemoryDataSource(AndroidMemoryDataSource &&other) noexcept;
+  AndroidMemoryDataSource &operator=(AndroidMemoryDataSource &&other) noexcept;
+  AndroidMemoryDataSource(const AndroidMemoryDataSource &) = delete;
+  AndroidMemoryDataSource &operator=(const AndroidMemoryDataSource &) = delete;
+
+  void reset();
+
+ private:
+  friend decoding::DecoderResult attachMemoryExtractorViaDataSource(
+      AMediaExtractor *extractor,
+      AndroidMemoryDataSource &dataSource,
+      std::vector<uint8_t> &encodedMemory,
+      MemoryDataSourceContext &memorySourceContext,
+      std::vector<uint8_t> data);
+
+  void *handle_ = nullptr;
+};
+
+[[nodiscard]] decoding::DecoderResult attachMemoryExtractorViaDataSource(
+    AMediaExtractor *extractor,
+    AndroidMemoryDataSource &dataSource,
+    std::vector<uint8_t> &encodedMemory,
+    MemoryDataSourceContext &memorySourceContext,
+    std::vector<uint8_t> data);
+
+} // namespace audioapi::android_decoder
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/BaseAudioContextHostObject.cpp b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/BaseAudioContextHostObject.cpp
index 8f5651534..e66676b6c 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/BaseAudioContextHostObject.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/BaseAudioContextHostObject.cpp
@@ -20,7 +20,7 @@
 #include <audioapi/HostObjects/utils/JsEnumParser.h>
 #include <audioapi/HostObjects/utils/NodeOptionsParser.h>
 #include <audioapi/core/BaseAudioContext.h>
-#include <audioapi/core/utils/AudioDecoding.h>
+#include <audioapi/decoding/AudioDecoding.h>
 
 #include <memory>
 #include <vector>
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/AudioDecoderHostObject.cpp b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/AudioDecoderHostObject.cpp
index 2ab437b2b..91820609a 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/AudioDecoderHostObject.cpp
+++ b/packages/react-native-audio-api/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.h>
+#include <audioapi/decoding/AudioDecoding.h>
 #include <audioapi/jsi/JsiPromise.h>
 
 #include <jsi/jsi.h>
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/AudioFileUtilsHostObject.cpp b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/AudioFileUtilsHostObject.cpp
index c23fa7674..e0ba54c1e 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/AudioFileUtilsHostObject.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/AudioFileUtilsHostObject.cpp
@@ -1,7 +1,7 @@
 #include <audioapi/HostObjects/utils/AudioFileUtilsHostObject.h>
 #include <audioapi/HostObjects/utils/NodeOptionsParser.h>
-#include <audioapi/core/utils/AudioDecoding.h>
-#include <audioapi/core/utils/AudioFileConcatenator.h>
+#include <audioapi/decoding/AudioDecoding.h>
+#include <audioapi/decoding/AudioFileConcatenator.h>
 #include <audioapi/jsi/JsiPromise.h>
 
 #include <jsi/jsi.h>
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
index 966d16ebe..015dd5251 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
@@ -12,7 +12,7 @@
 
 #include <audioapi/HostObjects/effects/PeriodicWaveHostObject.h>
 #include <audioapi/HostObjects/sources/AudioBufferHostObject.h>
-#include <audioapi/core/utils/AudioDecoding.h>
+#include <audioapi/decoding/AudioDecoding.h>
 #include <audioapi/types/NodeOptions.h>
 #include <audioapi/utils/AudioArray.hpp>
 #include <audioapi/utils/AudioArrayBuffer.hpp>
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/BaseAudioContext.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/BaseAudioContext.cpp
index 117856b41..1400a438d 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/BaseAudioContext.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/BaseAudioContext.cpp
@@ -1,6 +1,6 @@
 #include <audioapi/core/BaseAudioContext.h>
 #include <audioapi/core/destinations/AudioDestinationNode.h>
-#include <audioapi/core/utils/AudioDecoding.h>
+#include <audioapi/decoding/AudioDecoding.h>
 #include <audioapi/events/AudioEventHandlerRegistry.h>
 #include <audioapi/utils/AudioArray.hpp>
 #include <audioapi/utils/CircularArray.hpp>
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
index 5e22978da..be1d7e4b1 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.cpp
@@ -9,7 +9,8 @@
 
 #include <audioapi/core/AudioContext.h>
 
-#include <audioapi/core/utils/decoding/SeekDecoderDaemon.h>
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/SeekDecoderDaemon.h>
 #include <audioapi/utils/SpscChannel.hpp>
 #include <algorithm>
 #include <atomic>
@@ -97,12 +98,23 @@ bool AudioFileSourceNode::initDecoder(
           COMMAND_CHANNEL_CAPACITY);
   commandSender_ = std::move(commandSender);
 
+  const int contextSampleRate = static_cast<int>(context->getSampleRate());
+  decoding::DecoderSource source = decoding::EncodedMemorySource{};
+  if (!options.sourceUrl.empty()) {
+    source = decoding::RemoteUrlSource{
+        .url = std::move(options.sourceUrl),
+        .httpHeaders = std::move(options.httpHeaders),
+        .sampleRate = contextSampleRate};
+  } else if (!options.filePath.empty()) {
+    source = decoding::LocalFileSource{
+        .path = std::move(options.filePath), .sampleRate = contextSampleRate};
+  } else {
+    source = decoding::EncodedMemorySource{
+        .data = std::move(options.data), .sampleRate = contextSampleRate};
+  }
+
   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),
+      .source = std::move(source),
       .contextSampleRate = context->getSampleRate(),
       .loop = options.loop};
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
index d01d534dd..495217328 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/core/sources/AudioFileSourceNode.h
@@ -2,8 +2,8 @@
 
 #include <audioapi/core/AudioNode.h>
 #include <audioapi/core/sources/AudioScheduledSourceNode.h>
-#include <audioapi/core/utils/decoding/SeekDecoderDaemon.h>
-#include <audioapi/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/decoding/SeekDecoderDaemon.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/dsp/WsolaTimeStretcher.h>
 #include <audioapi/types/NodeOptions.h>
 #include <audioapi/utils/events/PositionChangedDispatcher.h>
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
deleted file mode 100644
index 73df4532c..000000000
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.cpp
+++ /dev/null
@@ -1,226 +0,0 @@
-#include <audioapi/core/utils/AudioDecoding.h>
-#include <audioapi/decoding/IncrementalAudioDecoder.h>
-#include <audioapi/decoding/OSDecoding.h>
-#include <audioapi/libs/base64/base64.h>
-#include <audioapi/libs/miniaudio/MiniAudioDecoding.h>
-
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-#include <audioapi/libs/ffmpeg/FFmpegDecoding.h>
-#endif // RN_AUDIO_API_FFMPEG_DISABLED
-
-#include <algorithm>
-#include <cctype>
-#include <cmath>
-#include <cstdint>
-#include <cstring>
-#include <map>
-#include <memory>
-#include <string>
-#include <utility>
-#include <vector>
-
-namespace audioapi::audiodecoding {
-
-// Drains an incremental decoder into an AudioBuffer. Total frame count is not
-// known up front for some formats (e.g. Vorbis), so we read in fixed-size
-// chunks and grow the interleaved accumulator until the decoder reports EOF.
-AudioBufferResult decodeAll(decoding::IncrementalAudioDecoder &decoder) {
-  const int channels = std::max(1, decoder.outputChannels());
-  const auto outputSampleRate = static_cast<float>(decoder.outputSampleRate());
-
-  std::vector<float> interleaved;
-  std::vector<float> chunk(
-      decoding::IncrementalAudioDecoder::CHUNK_SIZE * static_cast<size_t>(channels));
-
-  while (true) {
-    const size_t framesRead =
-        decoder.readPcmFrames(chunk.data(), decoding::IncrementalAudioDecoder::CHUNK_SIZE);
-    if (framesRead == 0) {
-      break;
-    }
-    interleaved.insert(
-        interleaved.end(),
-        chunk.begin(),
-        chunk.begin() + static_cast<std::ptrdiff_t>(framesRead * static_cast<size_t>(channels)));
-  }
-
-  if (interleaved.empty()) {
-    return Err("Failed to decode any frames");
-  }
-
-  const size_t outputFrames = interleaved.size() / static_cast<size_t>(channels);
-  auto audioBuffer = std::make_shared<AudioBuffer>(outputFrames, channels, outputSampleRate);
-  audioBuffer->deinterleaveFrom(interleaved.data(), outputFrames);
-  return Ok(std::move(audioBuffer));
-}
-
-bool pathHasExtension(const std::string &path, const std::vector<std::string> &extensions) {
-  std::string pathLower = path;
-  std::ranges::transform(pathLower, pathLower.begin(), [](unsigned char c) {
-    return static_cast<char>(std::tolower(c));
-  });
-  return std::ranges::any_of(
-      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);
-}
-
-namespace {
-
-/// Tries OS decoder then miniaudio. `open` opens the given decoder for the source.
-template <typename OpenFn>
-  requires std::
-      is_invocable_r_v<decoding::DecoderResult, OpenFn, decoding::IncrementalAudioDecoder &>
-    AudioDurationResult probeDurationLocal(OpenFn &&open, const char *errorMessage) {
-#if RN_AUDIO_API_HAS_OS_DECODER
-  {
-    os_decoder::Decoder platformDecoder;
-    if (open(platformDecoder).is_ok()) {
-      auto result = resolveDurationFromDecoder(platformDecoder);
-      platformDecoder.close();
-      if (result.is_ok()) {
-        return result;
-      }
-    } else {
-      platformDecoder.close();
-    }
-  }
-#endif // RN_AUDIO_API_HAS_OS_DECODER
-
-  miniaudio_decoder::MiniAudioDecoder decoder;
-  if (open(decoder).is_err()) {
-    return Err(errorMessage);
-  }
-  auto result = resolveDurationFromDecoder(decoder);
-  decoder.close();
-  if (result.is_err()) {
-    return Err(errorMessage);
-  }
-  return result;
-}
-
-template <typename OpenFn>
-  requires std::
-      is_invocable_r_v<decoding::DecoderResult, OpenFn, decoding::IncrementalAudioDecoder &>
-    AudioBufferResult decodeLocal(OpenFn &&open, const char *errorMessage) {
-#if RN_AUDIO_API_HAS_OS_DECODER
-  {
-    os_decoder::Decoder platformDecoder;
-    if (open(platformDecoder).is_ok()) {
-      auto result = decodeAll(platformDecoder);
-      platformDecoder.close();
-      if (result.is_ok()) {
-        return result;
-      }
-    } else {
-      platformDecoder.close();
-    }
-  }
-#endif // RN_AUDIO_API_HAS_OS_DECODER
-
-  miniaudio_decoder::MiniAudioDecoder decoder;
-  if (open(decoder).is_err()) {
-    return Err(errorMessage);
-  }
-  auto result = decodeAll(decoder);
-  decoder.close();
-  if (result.is_err()) {
-    return Err(errorMessage);
-  }
-  return result;
-}
-
-} // namespace
-
-AudioDurationResult probeDurationWithFilePath(const std::string &path) {
-  return probeDurationLocal(
-      [&](decoding::IncrementalAudioDecoder &decoder) { return decoder.openFile(0, path); },
-      "Cannot read duration: file could not be decoded");
-}
-
-AudioDurationResult probeDurationWithMemory(const void *data, size_t size, int sampleRate) {
-  const int sr = sampleRate != 0 ? sampleRate : 0;
-  return probeDurationLocal(
-      [=](decoding::IncrementalAudioDecoder &decoder) {
-        return decoder.openMemory(sr, data, size);
-      },
-      "Cannot read duration: audio data could not be decoded");
-}
-
-AudioDurationResult probeDurationWithUrl(
-    const std::string &url,
-    int sampleRate,
-    const std::map<std::string, std::string> &headers) {
-  // Remote URL duration probing uses FFmpeg's HTTP/HLS demuxer (byte ranges).
-#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);
-  return decodeLocal(
-      [&](decoding::IncrementalAudioDecoder &decoder) { return decoder.openFile(sr, path); },
-      "Cannot decode file: unsupported or invalid audio format");
-}
-
-AudioBufferResult decodeWithMemoryBlock(const void *data, size_t size, float sampleRate) {
-  const int sr = static_cast<int>(sampleRate);
-  return decodeLocal(
-      [&](decoding::IncrementalAudioDecoder &decoder) {
-        return decoder.openMemory(sr, data, size);
-      },
-      "Cannot decode audio data: unsupported or invalid audio format");
-}
-
-AudioBufferResult decodeWithPCMInBase64(
-    const std::string &data,
-    float inputSampleRate,
-    int inputChannelCount,
-    bool interleaved) {
-  auto decodedData = base64_decode(data, false);
-  const auto *uint8Data = reinterpret_cast<uint8_t *>(decodedData.data());
-  size_t numFramesDecoded = decodedData.size() / (inputChannelCount * sizeof(int16_t));
-
-  auto audioBuffer =
-      std::make_shared<AudioBuffer>(numFramesDecoded, inputChannelCount, inputSampleRate);
-
-  for (int ch = 0; ch < inputChannelCount; ++ch) {
-    auto channelData = audioBuffer->getChannel(ch)->span();
-
-    for (size_t i = 0; i < numFramesDecoded; ++i) {
-      size_t offset;
-      if (interleaved) {
-        // Ch1, Ch2, Ch1, Ch2, ...
-        offset = (i * inputChannelCount + ch) * sizeof(int16_t);
-      } else {
-        // Ch1, Ch1, Ch1, ..., Ch2, Ch2, Ch2, ...
-        offset = (ch * numFramesDecoded + i) * sizeof(int16_t);
-      }
-
-      channelData[i] = uint8ToFloat(uint8Data[offset], uint8Data[offset + 1]);
-    }
-  }
-
-  return Ok(std::move(audioBuffer));
-}
-
-} // namespace audioapi::audiodecoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioDecoding.cpp
new file mode 100644
index 000000000..c12e18111
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioDecoding.cpp
@@ -0,0 +1,174 @@
+#include <audioapi/decoding/AudioDecoding.h>
+#include <audioapi/decoding/DecoderFactory.h>
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
+
+#include <algorithm>
+#include <cmath>
+#include <concepts>
+#include <cstdint>
+#include <map>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace audioapi::audiodecoding {
+
+namespace {
+
+template <typename Fn, typename Result>
+concept DecoderOperation = std::invocable<Fn, decoding::AudioDecoderBackend &> &&
+    std::same_as<std::invoke_result_t<Fn, decoding::AudioDecoderBackend &>, Result>;
+
+template <typename Result, DecoderOperation<Result> Fn>
+Result withDecoderFromSource(
+    const decoding::DecoderSource &source,
+    const char *errorMessage,
+    Fn &&operation) {
+  auto decoderResult = decoding::createDecoder(source);
+  if (decoderResult.is_err()) {
+    return Err(errorMessage);
+  }
+
+  auto decoder = std::move(decoderResult).unwrap();
+  auto result = std::forward<Fn>(operation)(*decoder);
+  decoder->close();
+  if (result.is_err()) {
+    return Err(errorMessage);
+  }
+  return result;
+}
+
+decoding::EncodedMemorySource
+makeEncodedMemorySource(const void *data, size_t size, int sampleRate) {
+  return decoding::EncodedMemorySource{
+      .data = std::vector<uint8_t>(
+          static_cast<const uint8_t *>(data), static_cast<const uint8_t *>(data) + size),
+      .sampleRate = sampleRate};
+}
+
+AudioBufferResult decodeAll(decoding::AudioDecoderBackend &decoder) {
+  const int channels = std::max(1, decoder.outputChannels());
+  const auto outputSampleRate = static_cast<float>(decoder.outputSampleRate());
+
+  std::vector<float> interleaved;
+  std::vector<float> chunk(
+      decoding::AudioDecoderBackend::CHUNK_SIZE * static_cast<size_t>(channels));
+
+  while (true) {
+    const size_t framesRead =
+        decoder.readPcmFrames(chunk.data(), decoding::AudioDecoderBackend::CHUNK_SIZE);
+    if (framesRead == 0) {
+      break;
+    }
+    interleaved.insert(
+        interleaved.end(),
+        chunk.begin(),
+        chunk.begin() + static_cast<std::ptrdiff_t>(framesRead * static_cast<size_t>(channels)));
+  }
+
+  if (interleaved.empty()) {
+    return Err("Failed to decode any frames");
+  }
+
+  const size_t outputFrames = interleaved.size() / static_cast<size_t>(channels);
+  auto audioBuffer = std::make_shared<AudioBuffer>(outputFrames, channels, outputSampleRate);
+  audioBuffer->deinterleaveFrom(interleaved.data(), outputFrames);
+  return Ok(std::move(audioBuffer));
+}
+
+AudioDurationResult probeDurationFromSource(
+    const decoding::DecoderSource &source,
+    const char *errorMessage) {
+  return withDecoderFromSource<AudioDurationResult>(
+      source, errorMessage, resolveDurationFromDecoder);
+}
+
+AudioBufferResult decodeFromSource(
+    const decoding::DecoderSource &source,
+    const char *errorMessage) {
+  return withDecoderFromSource<AudioBufferResult>(source, errorMessage, decodeAll);
+}
+
+} // namespace
+
+bool pathHasExtension(const std::string &path, const std::vector<std::string> &extensions) {
+  return decoding::pathHasExtension(path, extensions);
+}
+
+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) {
+  return probeDurationFromSource(
+      decoding::LocalFileSource{.path = path, .sampleRate = 0},
+      "Cannot read duration: file could not be decoded");
+}
+
+AudioDurationResult probeDurationWithMemory(const void *data, size_t size, int sampleRate) {
+  const int sr = sampleRate != 0 ? sampleRate : 0;
+  if (data == nullptr || size == 0) {
+    return Err("Cannot read duration: audio data could not be decoded");
+  }
+  return probeDurationFromSource(
+      makeEncodedMemorySource(data, size, sr),
+      "Cannot read duration: audio data could not be decoded");
+}
+
+AudioDurationResult probeDurationWithUrl(
+    const std::string &url,
+    int sampleRate,
+    const std::map<std::string, std::string> &headers) {
+#if !RN_AUDIO_API_FFMPEG_DISABLED
+  if (url.empty()) {
+    return Err("Failed to open URL with FFmpeg decoder: url is empty");
+  }
+  return probeDurationFromSource(
+      decoding::RemoteUrlSource{.url = url, .httpHeaders = headers, .sampleRate = sampleRate},
+      "Failed to open URL with FFmpeg decoder");
+#else
+  (void)url;
+  (void)sampleRate;
+  (void)headers;
+  return Err("FFmpeg is disabled, cannot probe duration from URL");
+#endif
+}
+
+AudioBufferResult decodeWithFilePath(const std::string &path, float sampleRate) {
+  const int sr = static_cast<int>(sampleRate);
+  return decodeFromSource(
+      decoding::LocalFileSource{.path = path, .sampleRate = sr},
+      "Cannot decode file: unsupported or invalid audio format");
+}
+
+AudioBufferResult decodeWithMemoryBlock(const void *data, size_t size, float sampleRate) {
+  const int sr = static_cast<int>(sampleRate);
+  if (data == nullptr || size == 0) {
+    return Err("Cannot decode audio data: unsupported or invalid audio format");
+  }
+  return decodeFromSource(
+      makeEncodedMemorySource(data, size, sr),
+      "Cannot decode audio data: unsupported or invalid audio format");
+}
+
+AudioBufferResult decodeWithPCMInBase64(
+    const std::string &data,
+    float inputSampleRate,
+    int inputChannelCount,
+    bool interleaved) {
+  return decodeFromSource(
+      decoding::RawPcmBase64Source{
+          .base64 = data,
+          .channelCount = inputChannelCount,
+          .interleaved = interleaved,
+          .sampleRate = static_cast<int>(inputSampleRate)},
+      "Cannot decode PCM base64 data");
+}
+
+} // namespace audioapi::audiodecoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioDecoding.h
similarity index 85%
rename from packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.h
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioDecoding.h
index 026fd5c00..a86e44c5c 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioDecoding.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioDecoding.h
@@ -1,6 +1,6 @@
 #pragma once
 
-#include <audioapi/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/utils/AudioBuffer.hpp>
 #include <audioapi/utils/Result.hpp>
 #include <cstddef>
@@ -31,7 +31,7 @@ decodeWithMemoryBlock(const void *data, size_t size, float sampleRate);
 [[nodiscard]] bool isValidDuration(float duration);
 
 [[nodiscard]] inline AudioDurationResult resolveDurationFromDecoder(
-    decoding::IncrementalAudioDecoder &decoder) {
+    decoding::AudioDecoderBackend &decoder) {
   const float duration = decoder.getDurationInSeconds();
   if (!isValidDuration(duration)) {
     return Err("Audio duration metadata is unavailable");
@@ -39,10 +39,6 @@ decodeWithMemoryBlock(const void *data, size_t size, float sampleRate);
   return Ok(duration);
 }
 
-[[nodiscard]] inline float uint8ToFloat(uint8_t byte1, uint8_t byte2) {
-  return static_cast<float>(static_cast<int16_t>((byte2 << CHAR_BIT) | byte1)) / INT16_MAX;
-}
-
 [[nodiscard]] AudioDurationResult probeDurationWithFilePath(const std::string &path);
 [[nodiscard]] AudioDurationResult
 probeDurationWithMemory(const void *data, size_t size, int sampleRate = 0);
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioFileConcatenator.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioFileConcatenator.cpp
similarity index 88%
rename from packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioFileConcatenator.cpp
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioFileConcatenator.cpp
index 7ca4f296d..ad1ba969e 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioFileConcatenator.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioFileConcatenator.cpp
@@ -1,10 +1,13 @@
-#include <audioapi/core/utils/AudioFileConcatenator.h>
+#include <audioapi/decoding/AudioFileConcatenator.h>
+#include <audioapi/decoding/DecoderFactory.h>
+#include <audioapi/decoding/DecoderSource.h>
 #include <audioapi/libs/miniaudio/miniaudio.h>
 
 #include <algorithm>
 #include <array>
 #include <cctype>
 #include <charconv>
+#include <cstddef>
 #include <cstdint>
 #include <cstring>
 #include <limits>
@@ -130,8 +133,8 @@ std::string percentDecode(const std::string &path) {
     }
 
     unsigned int value = 0;
-    auto first = path.data() + i + 1;
-    auto last = first + 2;
+    const auto *first = path.data() + i + 1;
+    const auto *last = first + 2;
     auto result = std::from_chars(first, last, value, 16);
     if (result.ec != std::errc() || result.ptr != last) {
       decoded.push_back(path[i]);
@@ -212,74 +215,72 @@ std::string parseMiniAudioError(ma_result errorCode) {
 
 } // namespace
 
-MiniAudioDecoderGuard::MiniAudioDecoderGuard(MiniAudioDecoderGuard &&other) noexcept
-    : filePath_(std::move(other.filePath_)),
-      decoder_(std::move(other.decoder_)),
-      initialized_(std::exchange(other.initialized_, false)) {}
+AudioDecoderBackendGuard::AudioDecoderBackendGuard(AudioDecoderBackendGuard &&other) noexcept
+    : filePath_(std::move(other.filePath_)), decoder_(std::move(other.decoder_)) {}
 
-MiniAudioDecoderGuard &MiniAudioDecoderGuard::operator=(MiniAudioDecoderGuard &&other) noexcept {
+AudioDecoderBackendGuard &AudioDecoderBackendGuard::operator=(
+    AudioDecoderBackendGuard &&other) noexcept {
   if (this != &other) {
     close();
     filePath_ = std::move(other.filePath_);
     decoder_ = std::move(other.decoder_);
-    initialized_ = std::exchange(other.initialized_, false);
   }
   return *this;
 }
 
-MiniAudioDecoderGuard::~MiniAudioDecoderGuard() {
+AudioDecoderBackendGuard::~AudioDecoderBackendGuard() {
   close();
 }
 
-Result<MiniAudioDecoderGuard, std::string> MiniAudioDecoderGuard::open(
-    const std::string &filePath,
-    ma_format outputFormat) {
-  MiniAudioDecoderGuard input;
+Result<AudioDecoderBackendGuard, std::string> AudioDecoderBackendGuard::open(
+    const std::string &filePath) {
+  AudioDecoderBackendGuard input;
   input.filePath_ = filePath;
-  input.decoder_ = std::make_unique<ma_decoder>();
 
-  ma_decoder_config config = ma_decoder_config_init(outputFormat, 0, 0);
-  const ma_result result = ma_decoder_init_file(filePath.c_str(), &config, input.decoder_.get());
-  if (result != MA_SUCCESS) {
-    return Err(
-        "Failed to open input file '" + filePath +
-        "' with miniaudio: " + parseMiniAudioError(result));
+  auto decoderResult =
+      decoding::createDecoder(decoding::LocalFileSource{.path = filePath, .sampleRate = 0});
+  if (decoderResult.is_err()) {
+    return Err("Failed to open input file '" + filePath + "': " + decoderResult.unwrap_err());
   }
 
-  input.initialized_ = true;
-  if (input.decoder_->outputSampleRate == 0 || input.decoder_->outputChannels == 0) {
+  input.decoder_ = std::move(decoderResult).unwrap();
+  if (!input.decoder_->isOpen() || input.decoder_->outputSampleRate() == 0 ||
+      input.decoder_->outputChannels() == 0) {
+    input.close();
     return Err("Input file '" + filePath + "' is missing required audio parameters.");
   }
 
   return Ok(std::move(input));
 }
 
-ma_decoder *MiniAudioDecoderGuard::get() {
-  return decoder_.get();
+size_t AudioDecoderBackendGuard::readPcmFrames(float *frames, size_t frameCount) {
+  if (decoder_ == nullptr || frames == nullptr || frameCount == 0) {
+    return 0;
+  }
+  return decoder_->readPcmFrames(frames, frameCount);
 }
 
-const std::string &MiniAudioDecoderGuard::filePath() const {
+const std::string &AudioDecoderBackendGuard::filePath() const {
   return filePath_;
 }
 
-ma_uint32 MiniAudioDecoderGuard::sampleRate() const {
-  return decoder_->outputSampleRate;
+ma_uint32 AudioDecoderBackendGuard::sampleRate() const {
+  return static_cast<ma_uint32>(decoder_->outputSampleRate());
 }
 
-ma_uint32 MiniAudioDecoderGuard::channels() const {
-  return decoder_->outputChannels;
+ma_uint32 AudioDecoderBackendGuard::channels() const {
+  return static_cast<ma_uint32>(decoder_->outputChannels());
 }
 
-ma_format MiniAudioDecoderGuard::format() const {
-  return decoder_->outputFormat;
+ma_uint64 AudioDecoderBackendGuard::totalPcmFrames() const {
+  return static_cast<ma_uint64>(decoder_->getTotalPcmFrameCount());
 }
 
-void MiniAudioDecoderGuard::close() {
-  if (initialized_ && decoder_ != nullptr) {
-    ma_decoder_uninit(decoder_.get());
-    initialized_ = false;
+void AudioDecoderBackendGuard::close() {
+  if (decoder_ != nullptr) {
+    decoder_->close();
+    decoder_.reset();
   }
-  decoder_.reset();
 }
 
 MiniAudioEncoderGuard::~MiniAudioEncoderGuard() {
@@ -335,8 +336,8 @@ void MiniAudioEncoderGuard::close() {
 namespace {
 
 AudioFileConcatResult validateCompatibleMiniAudioInput(
-    const MiniAudioDecoderGuard &input,
-    const MiniAudioDecoderGuard &reference) {
+    const AudioDecoderBackendGuard &input,
+    const AudioDecoderBackendGuard &reference) {
   if (input.sampleRate() != reference.sampleRate()) {
     return Err("Input file '" + input.filePath() + "' uses a different sample rate.");
   }
@@ -354,12 +355,11 @@ AudioFileConcatResult validateCompatibleMiniAudioInput(
 
 AudioFileConcatResult openAndValidateMiniAudioInputs(
     const std::vector<std::string> &inputPaths,
-    std::vector<MiniAudioDecoderGuard> &inputs,
-    ma_format outputFormat = ma_format_unknown) {
+    std::vector<AudioDecoderBackendGuard> &inputs) {
   inputs.reserve(inputPaths.size());
 
   for (const auto &inputPath : inputPaths) {
-    auto inputResult = MiniAudioDecoderGuard::open(inputPath, outputFormat);
+    auto inputResult = AudioDecoderBackendGuard::open(inputPath);
     if (inputResult.is_err()) {
       return Err(inputResult.unwrap_err());
     }
@@ -378,7 +378,7 @@ AudioFileConcatResult openAndValidateMiniAudioInputs(
 }
 
 AudioFileConcatResult validateRiffWaveOutputSize(
-    std::vector<MiniAudioDecoderGuard> &inputs,
+    std::vector<AudioDecoderBackendGuard> &inputs,
     ma_uint64 bytesPerFrame) {
   if (bytesPerFrame == 0) {
     return Err("Input files use an unsupported WAV sample format.");
@@ -386,12 +386,9 @@ AudioFileConcatResult validateRiffWaveOutputSize(
 
   ma_uint64 totalDataBytes = 0;
   for (auto &input : inputs) {
-    ma_uint64 frameCount = 0;
-    const ma_result result = ma_decoder_get_length_in_pcm_frames(input.get(), &frameCount);
-    if (result != MA_SUCCESS) {
-      return Err(
-          "Failed to determine decoded frame count for '" + input.filePath() +
-          "' with miniaudio: " + parseMiniAudioError(result));
+    const ma_uint64 frameCount = input.totalPcmFrames();
+    if (frameCount == 0) {
+      return Err("Failed to determine decoded frame count for '" + input.filePath() + "'.");
     }
 
     if (frameCount > (std::numeric_limits<ma_uint64>::max() - totalDataBytes) / bytesPerFrame) {
@@ -422,14 +419,14 @@ AudioFileConcatResult concatAudioFilesWithMiniAudio(
     }
   }
 
-  std::vector<MiniAudioDecoderGuard> inputs;
+  std::vector<AudioDecoderBackendGuard> inputs;
   auto inputValidationResult = openAndValidateMiniAudioInputs(inputPaths, inputs);
   if (inputValidationResult.is_err()) {
     return inputValidationResult;
   }
 
-  const ma_uint64 bytesPerFrame =
-      inputs.front().channels() * ma_get_bytes_per_sample(inputs.front().format());
+  const ma_uint64 bytesPerFrame = static_cast<const ma_uint64>(inputs.front().channels()) *
+      ma_get_bytes_per_sample(inputs.front().format());
   auto outputSizeResult = validateRiffWaveOutputSize(inputs, bytesPerFrame);
   if (outputSizeResult.is_err()) {
     return outputSizeResult;
@@ -442,18 +439,10 @@ AudioFileConcatResult concatAudioFilesWithMiniAudio(
     return outputResult;
   }
 
-  std::vector<uint8_t> buffer(miniaudioChunkFrames * bytesPerFrame);
+  std::vector<float> buffer(miniaudioChunkFrames * inputs.front().channels());
   for (auto &input : inputs) {
     while (true) {
-      ma_uint64 framesRead = 0;
-      const ma_result result =
-          ma_decoder_read_pcm_frames(input.get(), buffer.data(), miniaudioChunkFrames, &framesRead);
-      if (result != MA_SUCCESS && result != MA_AT_END) {
-        return Err(
-            "Failed to decode frames from '" + input.filePath() +
-            "' with miniaudio: " + parseMiniAudioError(result));
-      }
-
+      const size_t framesRead = input.readPcmFrames(buffer.data(), miniaudioChunkFrames);
       if (framesRead == 0) {
         break;
       }
@@ -462,10 +451,6 @@ AudioFileConcatResult concatAudioFilesWithMiniAudio(
       if (writeResult.is_err()) {
         return writeResult;
       }
-
-      if (result == MA_AT_END) {
-        break;
-      }
     }
   }
 
@@ -663,7 +648,7 @@ AudioFileConcatResult createOutput(
   (*outputStream)->codecpar->codec_tag = 0;
   (*outputStream)->time_base = AVRational{.num = 1, .den = inputStream->codecpar->sample_rate};
 
-  if (!(rawOutputContext->oformat->flags & AVFMT_NOFILE)) {
+  if ((rawOutputContext->oformat->flags & AVFMT_NOFILE) == 0) {
     result = avio_open(&rawOutputContext->pb, outputPath.c_str(), AVIO_FLAG_WRITE);
     if (result < 0) {
       return Err("Failed to open output file '" + outputPath + "': " + parseFFmpegError(result));
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioFileConcatenator.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioFileConcatenator.h
similarity index 79%
rename from packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioFileConcatenator.h
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioFileConcatenator.h
index 3d16cde57..ebbb61c1e 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/AudioFileConcatenator.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/AudioFileConcatenator.h
@@ -1,5 +1,6 @@
 #pragma once
 
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/libs/miniaudio/miniaudio.h>
 #include <audioapi/utils/Result.hpp>
 
@@ -17,44 +18,39 @@ namespace audioapi {
 
 using AudioFileConcatResult = Result<std::string, std::string>;
 
-class MiniAudioDecoderGuard {
+class AudioDecoderBackendGuard {
  public:
-  MiniAudioDecoderGuard() = default;
-  MiniAudioDecoderGuard(const MiniAudioDecoderGuard &) = delete;
-  MiniAudioDecoderGuard &operator=(const MiniAudioDecoderGuard &) = delete;
+  AudioDecoderBackendGuard() = default;
+  AudioDecoderBackendGuard(const AudioDecoderBackendGuard &) = delete;
+  AudioDecoderBackendGuard &operator=(const AudioDecoderBackendGuard &) = delete;
 
-  MiniAudioDecoderGuard(MiniAudioDecoderGuard &&other) noexcept;
-  MiniAudioDecoderGuard &operator=(MiniAudioDecoderGuard &&other) noexcept;
+  AudioDecoderBackendGuard(AudioDecoderBackendGuard &&other) noexcept;
+  AudioDecoderBackendGuard &operator=(AudioDecoderBackendGuard &&other) noexcept;
 
-  // Closes the owned miniaudio decoder.
-  ~MiniAudioDecoderGuard();
+  ~AudioDecoderBackendGuard();
 
-  // Opens an input file for decoded PCM reads.
-  [[nodiscard]] static Result<MiniAudioDecoderGuard, std::string> open(
-      const std::string &filePath,
-      ma_format outputFormat = ma_format_unknown);
+  [[nodiscard]] static Result<AudioDecoderBackendGuard, std::string> open(
+      const std::string &filePath);
 
-  // Returns the owned miniaudio decoder.
-  [[nodiscard]] ma_decoder *get();
+  [[nodiscard]] size_t readPcmFrames(float *frames, size_t frameCount);
 
-  // Returns the normalized file path represented by this input.
   [[nodiscard]] const std::string &filePath() const;
 
-  // Returns the decoded output sample rate.
   [[nodiscard]] ma_uint32 sampleRate() const;
 
-  // Returns the decoded output channel count.
   [[nodiscard]] ma_uint32 channels() const;
 
-  // Returns the decoded output sample format.
-  [[nodiscard]] ma_format format() const;
+  [[nodiscard]] ma_format format() const {
+    return ma_format_f32;
+  }
+
+  [[nodiscard]] ma_uint64 totalPcmFrames() const;
 
  private:
   void close();
 
   std::string filePath_;
-  std::unique_ptr<ma_decoder> decoder_{nullptr};
-  bool initialized_{false};
+  std::unique_ptr<decoding::AudioDecoderBackend> decoder_;
 };
 
 class MiniAudioEncoderGuard {
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.cpp
new file mode 100644
index 000000000..babff678c
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.cpp
@@ -0,0 +1,114 @@
+#include <audioapi/decoding/DecoderFactory.h>
+#include <audioapi/decoding/OSDecoding.h>
+#include <audioapi/decoding/backends/MiniAudioDecoder.h>
+#include <audioapi/decoding/backends/RawPcmDecoder.h>
+
+#if !RN_AUDIO_API_FFMPEG_DISABLED
+#include <audioapi/decoding/backends/FfmpegDecoder.h>
+#endif
+
+#include <concepts>
+#include <memory>
+#include <utility>
+
+namespace audioapi::decoding {
+namespace {
+
+// Combines multiple lambdas into one visitor so std::visit can dispatch on DecoderSource
+// (each lambda handles a different std::variant alternative).
+template <class... Ts>
+struct overloaded : Ts... {
+  using Ts::operator()...;
+};
+template <class... Ts>
+overloaded(Ts...) -> overloaded<Ts...>;
+
+#if RN_AUDIO_API_HAS_OS_DECODER
+template <typename Source>
+concept OsFallbackOpenableSource = requires(
+    const Source &source,
+    miniaudio::MiniAudioDecoder &miniAudioDecoder,
+    os_decoder::Decoder &platformDecoder) {
+  { miniAudioDecoder.open(source) } -> std::same_as<DecoderResult>;
+  { platformDecoder.open(source) } -> std::same_as<DecoderResult>;
+};
+#else
+template <typename Source>
+concept OsFallbackOpenableSource =
+    requires(const Source &source, miniaudio::MiniAudioDecoder &miniAudioDecoder) {
+      { miniAudioDecoder.open(source) } -> std::same_as<DecoderResult>;
+    };
+#endif
+
+template <typename Decoder, typename Source>
+CreateDecoderResult createAndOpen(const Source &source) {
+  auto decoder = std::make_unique<Decoder>();
+  if (auto opened = decoder->open(source); opened.is_err()) {
+    decoder->close();
+    return Err(opened.unwrap_err());
+  }
+  return Ok(DecoderPtr(std::move(decoder)));
+}
+
+template <OsFallbackOpenableSource Source>
+CreateDecoderResult tryOpenWithOsFallback(const Source &source, const char *errorMessage) {
+#if RN_AUDIO_API_HAS_OS_DECODER
+  if (auto result = createAndOpen<os_decoder::Decoder>(source); result.is_ok()) {
+    return result;
+  }
+#endif
+
+  if (auto result = createAndOpen<miniaudio::MiniAudioDecoder>(source); result.is_ok()) {
+    return result;
+  }
+  return Err(errorMessage);
+}
+
+} // namespace
+
+CreateDecoderResult createDecoder(const DecoderSource &source) {
+  return std::visit(
+      overloaded{
+          [](const LocalFileSource &localSource) -> CreateDecoderResult {
+            if (localSource.path.empty()) {
+              return Err("DecoderFactory: local file path is empty");
+            }
+            if (localPathRequiresFfmpeg(localSource.path)) {
+#if !RN_AUDIO_API_FFMPEG_DISABLED
+              return createAndOpen<ffmpeg::FfmpegDecoder>(localSource);
+#else
+              return Err("FFmpeg is disabled, cannot decode local HLS (.m3u8) playlists");
+#endif
+            }
+            return tryOpenWithOsFallback(
+                localSource, "Cannot open local file: unsupported or invalid audio format");
+          },
+          [](const EncodedMemorySource &memorySource) -> CreateDecoderResult {
+            if (memorySource.data.empty()) {
+              return Err("DecoderFactory: encoded memory source is empty");
+            }
+            return tryOpenWithOsFallback(
+                memorySource, "Cannot decode encoded memory: unsupported or invalid audio format");
+          },
+          [](const RemoteUrlSource &remoteSource) -> CreateDecoderResult {
+            if (remoteSource.url.empty()) {
+              return Err("DecoderFactory: remote URL is empty");
+            }
+#if !RN_AUDIO_API_FFMPEG_DISABLED
+            return createAndOpen<ffmpeg::FfmpegDecoder>(remoteSource);
+#else
+            (void)remoteSource;
+            return Err("FFmpeg is disabled, cannot decode remote URL");
+#endif
+          },
+          [](const RawPcmSource &pcmSource) -> CreateDecoderResult {
+            return createAndOpen<raw_pcm::RawPcmDecoder>(pcmSource);
+          },
+          [](const RawPcmBase64Source &pcmSource) -> CreateDecoderResult {
+            return createAndOpen<raw_pcm::RawPcmDecoder>(pcmSource);
+          },
+      },
+      source);
+}
+
+} // namespace audioapi::decoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.h
new file mode 100644
index 000000000..c502936f2
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.h
@@ -0,0 +1,17 @@
+#pragma once
+
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
+#include <audioapi/utils/Result.hpp>
+
+#include <memory>
+
+namespace audioapi::decoding {
+
+using DecoderPtr = std::unique_ptr<AudioDecoderBackend>;
+using CreateDecoderResult = Result<DecoderPtr, DecoderError>;
+
+/// Selects a backend, opens @p source, and returns a ready incremental decoder.
+[[nodiscard]] CreateDecoderResult createDecoder(const DecoderSource &source);
+
+} // namespace audioapi::decoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
new file mode 100644
index 000000000..fdb5cdd14
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
@@ -0,0 +1,65 @@
+#pragma once
+
+#include <algorithm>
+#include <cctype>
+#include <cstddef>
+#include <map>
+#include <string>
+#include <variant>
+#include <vector>
+
+namespace audioapi::decoding {
+
+struct LocalFileSource {
+  std::string path;
+  int sampleRate = 0;
+};
+
+struct EncodedMemorySource {
+  std::vector<uint8_t> data;
+  int sampleRate = 0;
+};
+
+struct RemoteUrlSource {
+  std::string url;
+  std::map<std::string, std::string> httpHeaders;
+  int sampleRate = 0;
+};
+
+struct RawPcmSource {
+  std::vector<uint8_t> data;
+  int channelCount = 0;
+  bool interleaved = true;
+  int sampleRate = 0;
+};
+
+struct RawPcmBase64Source {
+  std::string base64;
+  int channelCount = 0;
+  bool interleaved = true;
+  int sampleRate = 0;
+};
+
+using DecoderSource = std::variant<
+    LocalFileSource,
+    EncodedMemorySource,
+    RemoteUrlSource,
+    RawPcmSource,
+    RawPcmBase64Source>;
+
+[[nodiscard]] inline bool pathHasExtension(
+    const std::string &path,
+    const std::vector<std::string> &extensions) {
+  std::string pathLower = path;
+  std::ranges::transform(pathLower, pathLower.begin(), [](unsigned char c) {
+    return static_cast<char>(std::tolower(c));
+  });
+  return std::ranges::any_of(
+      extensions, [&pathLower](const std::string &ext) { return pathLower.ends_with(ext); });
+}
+
+[[nodiscard]] inline bool localPathRequiresFfmpeg(const std::string &path) {
+  return pathHasExtension(path, {".m3u8"});
+}
+
+} // namespace audioapi::decoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h
deleted file mode 100644
index 00e59f4ee..000000000
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/IncrementalAudioDecoder.h
+++ /dev/null
@@ -1,77 +0,0 @@
-#pragma once
-
-#include <audioapi/utils/Macros.h>
-#include <audioapi/utils/Result.hpp>
-#include <cstddef>
-#include <string>
-
-namespace audioapi::decoding {
-using DecoderResult = Result<NoneType, std::string>;
-/**
- * Incremental PCM decoder: openFile or openMemory → readPcmFrames in a loop → close.
- * Shared contract for OS-based and MiniAudio-based implementations.
- */
-class IncrementalAudioDecoder {
- public:
-  static constexpr size_t CHUNK_SIZE = 4096;
-  IncrementalAudioDecoder() = default;
-  virtual ~IncrementalAudioDecoder() = default;
-  DELETE_COPY_AND_MOVE(IncrementalAudioDecoder);
-
-  /// @brief Opens a file for decoding.
-  /// @param outputSampleRate The output sample rate.
-  /// @param path The path to the file.
-  /// @return Ok(None) on success or Err(message) on failure.
-  [[nodiscard]] virtual DecoderResult openFile(int outputSampleRate, const std::string &path) = 0;
-
-  /// @brief Opens a memory block for decoding.
-  /// @param outputSampleRate The output sample rate.
-  /// @param data The data to decode.
-  /// @param size The size of the data.
-  /// @return Ok(None) on success or Err(message) on failure.
-  /// Default rejects; OS and MiniAudio override with real implementations.
-  [[nodiscard]] virtual DecoderResult
-  openMemory(int /*outputSampleRate*/, const void * /*data*/, size_t /*size*/) {
-    return Err("openMemory is not supported by this decoder");
-  }
-
-  /// @brief Reads PCM frames from the decoder.
-  /// @param outInterleaved The output buffer for the decoded frames.
-  /// @param frameCount The number of frames to read.
-  /// @return The number of frames read.
-  [[nodiscard]] virtual size_t readPcmFrames(float *outInterleaved, size_t frameCount) = 0;
-
-  /// @brief Closes the decoder.
-  virtual void close() = 0;
-
-  /// @brief Checks if the decoder is open.
-  /// @return True if the decoder is open, false otherwise.
-  [[nodiscard]] virtual bool isOpen() const = 0;
-
-  /// @brief Gets the number of output channels.
-  /// @return The number of output channels.
-  [[nodiscard]] virtual int outputChannels() const = 0;
-
-  /// @brief Gets the output sample rate.
-  /// @return The output sample rate.
-  [[nodiscard]] virtual int outputSampleRate() const = 0;
-
-  /// @brief True when the source uses FFmpeg's live HLS demuxer (indefinite stream).
-  [[nodiscard]] virtual bool isHlsStreaming() const {
-    return false;
-  }
-
-  /// @brief Gets the duration of the audio in seconds.
-  /// @return The duration of the audio in seconds.
-  [[nodiscard]] virtual float getDurationInSeconds() const = 0;
-
-  /// @brief Gets the current position of the audio in seconds.
-  /// @return The current position of the audio in seconds.
-  [[nodiscard]] virtual float getCurrentPositionInSeconds() const = 0;
-
-  /// @brief Seeks to a specific time in the audio.
-  /// @param seconds The time to seek to in seconds.
-  /// @return Ok(None) on success or Err(message) on failure.
-  [[nodiscard]] virtual DecoderResult seekToTime(double seconds) = 0;
-};
-} // namespace audioapi::decoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/OSDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/OSDecoding.h
index 138015d27..f3ca26ae5 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/OSDecoding.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/OSDecoding.h
@@ -10,7 +10,7 @@
  */
 
 #if defined(__ANDROID__)
-#include <audioapi/AndroidDecoding.h>
+#include <audioapi/android/AndroidDecoding.h>
 #define RN_AUDIO_API_HAS_OS_DECODER 1
 namespace audioapi::os_decoder {
 using Decoder = android_decoder::AndroidDecoder;
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/SeekDecoderDaemon.cpp
similarity index 75%
rename from packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/SeekDecoderDaemon.cpp
index 04d083f34..17c4eb3d1 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/SeekDecoderDaemon.cpp
@@ -1,28 +1,14 @@
-#include <audioapi/core/utils/decoding/SeekDecoderDaemon.h>
-#include <audioapi/decoding/OSDecoding.h>
+#include <audioapi/decoding/DecoderFactory.h>
+#include <audioapi/decoding/SeekDecoderDaemon.h>
 
 #include <memory>
 #include <thread>
 #include <utility>
 
 namespace audioapi {
-namespace {
-
-decoding::DecoderResult openLocalWithDecoder(
-    decoding::IncrementalAudioDecoder &decoder,
-    const SeekDecoderDaemonOptions &options,
-    int contextSampleRate) {
-  if (!options.filePath.empty()) {
-    return decoder.openFile(contextSampleRate, options.filePath);
-  }
-  return decoder.openMemory(
-      contextSampleRate, options.memoryData.data(), options.memoryData.size());
-}
-
-} // namespace
 
 SeekDecoderDaemon::SeekDecoderDaemon(
-    SeekDecoderDaemonOptions options,
+    const SeekDecoderDaemonOptions &options,
     std::shared_ptr<AudioFileDecoderState> sharedState,
     CommandReceiver commandReceiver,
     FrameSender frameSender,
@@ -31,39 +17,14 @@ SeekDecoderDaemon::SeekDecoderDaemon(
       commandReceiver_(std::move(commandReceiver)),
       frameSender_(std::move(frameSender)),
       frameReceiverForDrain_(std::move(frameReceiver)) {
-  const int contextSampleRate = static_cast<int>(options.contextSampleRate);
-  decoding::DecoderResult openResult = Err("Failed to initialize decoder");
-
-  // Remote HTTP(S) / HLS: FFmpeg owns network demux (byte ranges + playlists).
-  if (!options.sourceUrl.empty()) {
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-    auto ffmpegDecoder = std::make_unique<ffmpeg_decoder::FFmpegDecoder>();
-    openResult = ffmpegDecoder->openUrl(contextSampleRate, options.sourceUrl, options.httpHeaders);
-    decoder_ = std::move(ffmpegDecoder);
-#endif
-  } else {
-#if RN_AUDIO_API_HAS_OS_DECODER
-    decoder_ = std::make_unique<os_decoder::Decoder>();
-    openResult = openLocalWithDecoder(*decoder_, options, contextSampleRate);
-
-    if (openResult.is_err()) {
-      decoder_->close();
-#endif // RN_AUDIO_API_HAS_OS_DECODER
-      decoder_ = std::make_unique<miniaudio_decoder::MiniAudioDecoder>();
-      openResult = openLocalWithDecoder(*decoder_, options, contextSampleRate);
-#if RN_AUDIO_API_HAS_OS_DECODER
-    }
-#endif // RN_AUDIO_API_HAS_OS_DECODER
-  }
-
-  if (openResult.is_err()) {
-    if (decoder_) {
-      decoder_->close();
-    }
+  auto decoderResult = decoding::createDecoder(options.source);
+  if (decoderResult.is_err()) {
     sharedState_->isDaemonRunning.store(false, std::memory_order_release);
     return;
   }
 
+  decoder_ = std::move(decoderResult).unwrap();
+
   sharedState_->channelCount.store(decoder_->outputChannels(), std::memory_order_release);
   sharedState_->sampleRate.store(
       static_cast<float>(decoder_->outputSampleRate()), std::memory_order_release);
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/SeekDecoderDaemon.h
similarity index 84%
rename from packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.h
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/SeekDecoderDaemon.h
index 617958746..f0e2baff5 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/core/utils/decoding/SeekDecoderDaemon.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/SeekDecoderDaemon.h
@@ -1,31 +1,19 @@
 #pragma once
 
 #include <audioapi/core/utils/Constants.h>
-#include <audioapi/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/dsp/WsolaTimeStretcher.h>
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-#include <audioapi/libs/ffmpeg/FFmpegDecoding.h>
-#endif // RN_AUDIO_API_FFMPEG_DISABLED
-#include <audioapi/libs/miniaudio/MiniAudioDecoding.h>
 #include <audioapi/utils/SpscChannel.hpp>
 #include <array>
 #include <atomic>
-#include <map>
 #include <memory>
 #include <optional>
-#include <string>
-#include <vector>
 
 using namespace audioapi::channels::spsc;
 
 struct SeekDecoderDaemonOptions {
-  bool requiresFFmpeg;
-  // source
-  std::string filePath;
-  std::string sourceUrl;
-  std::map<std::string, std::string> httpHeaders;
-  std::vector<uint8_t> memoryData;
-  // playback
+  audioapi::decoding::DecoderSource source;
   float contextSampleRate;
   bool loop;
 };
@@ -91,14 +79,14 @@ inline constexpr auto SLEEP_DURATION_ON_FULL = std::chrono::milliseconds(10);
 
 namespace audioapi {
 
-/// @brief SeekDecoderDaemon is a dedicated thread worker that manages an audio
-/// decoder instance (FFmpeg for remote URLs/HLS; OS or MiniAudio for local).
-/// It listens for seek commands from the JS thread, performs seeks on the decoder,
-/// decodes audio frames, and sends decoded planar audio data back to the audio thread via a lock-free SPSC channel.
+/// @brief SeekDecoderDaemon is a dedicated thread worker that manages an incremental
+/// audio decoder. It listens for seek commands from the JS thread, performs seeks on the
+/// decoder, decodes audio frames, and sends decoded planar audio data back to the audio
+/// thread via a lock-free SPSC channel.
 class SeekDecoderDaemon {
  public:
   SeekDecoderDaemon(
-      SeekDecoderDaemonOptions options,
+      const SeekDecoderDaemonOptions &options,
       std::shared_ptr<AudioFileDecoderState> sharedState,
       CommandReceiver commandReceiver,
       FrameSender frameSender,
@@ -110,7 +98,7 @@ class SeekDecoderDaemon {
   void operator()();
 
  private:
-  std::unique_ptr<decoding::IncrementalAudioDecoder> decoder_;
+  std::unique_ptr<decoding::AudioDecoderBackend> decoder_;
 
   /// @brief Shared state with the AudioFileSourceNode, used for communicating decoder status, metadata, and playback position.
   std::shared_ptr<AudioFileDecoderState> sharedState_;
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/AudioDecoderBackend.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/AudioDecoderBackend.h
new file mode 100644
index 000000000..d2abff57c
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/AudioDecoderBackend.h
@@ -0,0 +1,36 @@
+#pragma once
+
+#include <audioapi/utils/Macros.h>
+#include <audioapi/utils/Result.hpp>
+#include <cstddef>
+#include <string>
+
+namespace audioapi::decoding {
+using DecoderError = std::string;
+using DecoderResult = Result<NoneType, DecoderError>;
+
+class AudioDecoderBackend {
+ public:
+  static constexpr size_t CHUNK_SIZE = 4096;
+  AudioDecoderBackend() = default;
+  virtual ~AudioDecoderBackend() = default;
+  DELETE_COPY_AND_MOVE(AudioDecoderBackend);
+
+  [[nodiscard]] virtual size_t readPcmFrames(float *outInterleaved, size_t frameCount) = 0;
+  [[nodiscard]] virtual DecoderResult seekToTime(double seconds) = 0;
+  virtual void close() = 0;
+  [[nodiscard]] virtual bool isOpen() const = 0;
+  [[nodiscard]] virtual int outputChannels() const = 0;
+  [[nodiscard]] virtual int outputSampleRate() const = 0;
+  [[nodiscard]] virtual float getDurationInSeconds() const = 0;
+  [[nodiscard]] virtual float getCurrentPositionInSeconds() const = 0;
+  [[nodiscard]] virtual bool isHlsStreaming() const {
+    return false;
+  }
+  /// Total PCM frame count when known (e.g. WAV); 0 when unavailable.
+  [[nodiscard]] virtual size_t getTotalPcmFrameCount() const {
+    return 0;
+  }
+};
+
+} // namespace audioapi::decoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp
similarity index 76%
rename from packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp
index 9ebc2d3bd..61a0f962c 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp
@@ -8,18 +8,18 @@
  * FFmpeg, you must comply with the terms of the LGPL for FFmpeg itself.
  */
 
-#include <audioapi/libs/ffmpeg/FFmpegDecoding.h>
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-
+#include <audioapi/decoding/backends/FfmpegDecoder.h>
 #include <algorithm>
 #include <array>
+#include <cerrno>
 #include <chrono>
 #include <cmath>
-#include <cerrno>
 #include <cstring>
 #include <map>
+#include <string>
 #include <thread>
 
+#if !RN_AUDIO_API_FFMPEG_DISABLED
 extern "C" {
 #include <libavutil/avutil.h>
 #include <libavutil/channel_layout.h>
@@ -28,7 +28,7 @@ extern "C" {
 #include <libavutil/rational.h>
 }
 
-namespace audioapi::ffmpeg_decoder {
+namespace audioapi::decoding::ffmpeg {
 
 namespace {
 
@@ -78,39 +78,39 @@ decoding::DecoderResult
 openCodec(AVFormatContext *fmt_ctx, int &audio_stream_index, AVCodecContext **out_codec) {
   audio_stream_index = findAudioStreamIndex(fmt_ctx);
   if (audio_stream_index < 0) {
-    return Err("FFmpegDecoder::openCodec failed: no audio stream found");
+    return Err("FfmpegDecoder::openCodec failed: no audio stream found");
   }
   AVCodecParameters *codecpar = fmt_ctx->streams[audio_stream_index]->codecpar;
   const AVCodec *codec = avcodec_find_decoder(codecpar->codec_id);
   if (codec == nullptr) {
-    return Err("FFmpegDecoder::openCodec failed: decoder not found");
+    return Err("FfmpegDecoder::openCodec failed: decoder not found");
   }
   AVCodecContext *ctx = avcodec_alloc_context3(codec);
   if (ctx == nullptr) {
-    return Err("FFmpegDecoder::openCodec failed: avcodec_alloc_context3 returned null");
+    return Err("FfmpegDecoder::openCodec failed: avcodec_alloc_context3 returned null");
   }
   const int parametersResult = avcodec_parameters_to_context(ctx, codecpar);
   if (parametersResult < 0) {
     avcodec_free_context(&ctx);
     return Err(
-        "FFmpegDecoder::openCodec failed: avcodec_parameters_to_context failed: " +
+        "FfmpegDecoder::openCodec failed: avcodec_parameters_to_context failed: " +
         parseFFmpegError(parametersResult));
   }
   const int openResult = avcodec_open2(ctx, codec, nullptr);
   if (openResult < 0) {
     avcodec_free_context(&ctx);
     return Err(
-        "FFmpegDecoder::openCodec failed: avcodec_open2 failed: " + parseFFmpegError(openResult));
+        "FfmpegDecoder::openCodec failed: avcodec_open2 failed: " + parseFFmpegError(openResult));
   }
   *out_codec = ctx;
   return Ok(None);
 }
 
-FFmpegDecoder::~FFmpegDecoder() {
+FfmpegDecoder::~FfmpegDecoder() {
   close();
 }
 
-void FFmpegDecoder::close() {
+void FfmpegDecoder::close() {
   if (resampled_data_ != nullptr) {
     av_freep(&resampled_data_[0]);
     av_freep(&resampled_data_);
@@ -140,15 +140,15 @@ void FFmpegDecoder::close() {
   is_hls_streaming_ = false;
 }
 
-void FFmpegDecoder::detectHlsStreamingMode() {
+void FfmpegDecoder::detectHlsStreamingMode() {
   is_hls_streaming_ = fmt_ctx_ != nullptr && fmt_ctx_->iformat != nullptr &&
       fmt_ctx_->iformat->name != nullptr && std::strcmp(fmt_ctx_->iformat->name, "hls") == 0;
 }
 
-decoding::DecoderResult FFmpegDecoder::setupSwr() {
+decoding::DecoderResult FfmpegDecoder::setupSwr() {
   swr_ = swr_alloc();
   if (swr_ == nullptr) {
-    return Err("FFmpegDecoder::setupSwr failed: swr_alloc returned null");
+    return Err("FfmpegDecoder::setupSwr failed: swr_alloc returned null");
   }
   av_opt_set_chlayout(swr_, "in_chlayout", &codec_ctx_->ch_layout, 0);
   av_opt_set_int(swr_, "in_sample_rate", codec_ctx_->sample_rate, 0);
@@ -163,7 +163,7 @@ decoding::DecoderResult FFmpegDecoder::setupSwr() {
   if (swrInitResult < 0) {
     av_channel_layout_uninit(&out_layout);
     return Err(
-        "FFmpegDecoder::setupSwr failed: swr_init failed: " + parseFFmpegError(swrInitResult));
+        "FfmpegDecoder::setupSwr failed: swr_init failed: " + parseFFmpegError(swrInitResult));
   }
   av_channel_layout_uninit(&out_layout);
 
@@ -171,19 +171,19 @@ decoding::DecoderResult FFmpegDecoder::setupSwr() {
       &resampled_data_,
       nullptr,
       output_channels_,
-      decoding::IncrementalAudioDecoder::CHUNK_SIZE,
+      decoding::AudioDecoderBackend::CHUNK_SIZE,
       AV_SAMPLE_FMT_FLT,
       0);
   if (allocResult < 0) {
     return Err(
-        "FFmpegDecoder::setupSwr failed: av_samples_alloc_array_and_samples failed: " +
+        "FfmpegDecoder::setupSwr failed: av_samples_alloc_array_and_samples failed: " +
         parseFFmpegError(allocResult));
   }
-  max_resampled_samples_ = static_cast<int>(decoding::IncrementalAudioDecoder::CHUNK_SIZE);
+  max_resampled_samples_ = static_cast<int>(decoding::AudioDecoderBackend::CHUNK_SIZE);
   return Ok(None);
 }
 
-decoding::DecoderResult FFmpegDecoder::initializeDecodedStreams(
+decoding::DecoderResult FfmpegDecoder::initializeDecodedStreams(
     int outputSampleRate,
     const char *errorContext) {
   const int streamInfoResult = avformat_find_stream_info(fmt_ctx_, nullptr);
@@ -191,8 +191,8 @@ decoding::DecoderResult FFmpegDecoder::initializeDecodedStreams(
     avformat_close_input(&fmt_ctx_);
     fmt_ctx_ = nullptr;
     return Err(
-        std::string(errorContext) + " failed: avformat_find_stream_info failed: " +
-        parseFFmpegError(streamInfoResult));
+        std::string(errorContext) +
+        " failed: avformat_find_stream_info failed: " + parseFFmpegError(streamInfoResult));
   }
   detectHlsStreamingMode();
   auto codecResult = openCodec(fmt_ctx_, audio_stream_index_, &codec_ctx_);
@@ -223,50 +223,47 @@ decoding::DecoderResult FFmpegDecoder::initializeDecodedStreams(
   return Ok(None);
 }
 
-decoding::DecoderResult FFmpegDecoder::openFile(int outputSampleRate, const std::string &path) {
+decoding::DecoderResult FfmpegDecoder::open(const decoding::LocalFileSource &source) {
   close();
-  if (path.empty()) {
-    return Err("FFmpegDecoder::openFile failed: path is empty");
+  if (source.path.empty()) {
+    return Err("FfmpegDecoder::open failed: path is empty");
   }
-  const int openInputResult = avformat_open_input(&fmt_ctx_, path.c_str(), nullptr, nullptr);
+  const int openInputResult = avformat_open_input(&fmt_ctx_, source.path.c_str(), nullptr, nullptr);
   if (openInputResult < 0) {
     fmt_ctx_ = nullptr;
     return Err(
-        "FFmpegDecoder::openFile failed: avformat_open_input failed: " +
+        "FfmpegDecoder::open failed: avformat_open_input failed: " +
         parseFFmpegError(openInputResult));
   }
-  return initializeDecodedStreams(outputSampleRate, "FFmpegDecoder::openFile");
+  return initializeDecodedStreams(source.sampleRate, "FfmpegDecoder::open");
 }
 
-decoding::DecoderResult FFmpegDecoder::openUrl(
-    int outputSampleRate,
-    const std::string &url,
-    const std::map<std::string, std::string> &headers) {
+decoding::DecoderResult FfmpegDecoder::open(const decoding::RemoteUrlSource &source) {
   close();
-  if (url.empty()) {
-    return Err("FFmpegDecoder::openUrl failed: url is empty");
+  if (source.url.empty()) {
+    return Err("FfmpegDecoder::open failed: url is empty");
   }
 
   AVDictionary *options = nullptr;
   av_dict_set(&options, "protocol_whitelist", "file,http,https,tcp,tls,crypto,hls", 0);
 
-  const std::string headerBlock = buildFfmpegHttpHeaders(headers);
+  const std::string headerBlock = buildFfmpegHttpHeaders(source.httpHeaders);
   if (!headerBlock.empty()) {
     av_dict_set(&options, "headers", headerBlock.c_str(), 0);
   }
 
-  const int openInputResult = avformat_open_input(&fmt_ctx_, url.c_str(), nullptr, &options);
+  const int openInputResult = avformat_open_input(&fmt_ctx_, source.url.c_str(), nullptr, &options);
   av_dict_free(&options);
   if (openInputResult < 0) {
     fmt_ctx_ = nullptr;
     return Err(
-        "FFmpegDecoder::openUrl failed: avformat_open_input failed: " +
+        "FfmpegDecoder::open failed: avformat_open_input failed: " +
         parseFFmpegError(openInputResult));
   }
-  return initializeDecodedStreams(outputSampleRate, "FFmpegDecoder::openUrl");
+  return initializeDecodedStreams(source.sampleRate, "FfmpegDecoder::open");
 }
 
-void FFmpegDecoder::appendFrameResampled(AVFrame *frame) {
+void FfmpegDecoder::appendFrameResampled(AVFrame *frame) {
   int out_samples = swr_get_out_samples(swr_, frame->nb_samples);
   if (out_samples > max_resampled_samples_) {
     av_freep(&resampled_data_[0]);
@@ -295,7 +292,7 @@ void FFmpegDecoder::appendFrameResampled(AVFrame *frame) {
   }
 }
 
-decoding::DecoderResult FFmpegDecoder::feedPipeline() {
+decoding::DecoderResult FfmpegDecoder::feedPipeline() {
   int readRetries = 0;
 
   for (;;) {
@@ -310,12 +307,12 @@ decoding::DecoderResult FFmpegDecoder::feedPipeline() {
         return Ok(None);
       }
       if (!is_hls_streaming_) {
-        return Err("FFmpegDecoder::feedPipeline reached end of stream");
+        return Err("FfmpegDecoder::feedPipeline reached end of stream");
       }
       // HLS live: need more segment data — fall through to av_read_frame.
     } else if (r != AVERROR(EAGAIN)) {
       return Err(
-          "FFmpegDecoder::feedPipeline failed: avcodec_receive_frame failed: " +
+          "FfmpegDecoder::feedPipeline failed: avcodec_receive_frame failed: " +
           parseFFmpegError(r));
     }
 
@@ -328,7 +325,7 @@ decoding::DecoderResult FFmpegDecoder::feedPipeline() {
       const int flushResult = avcodec_send_packet(codec_ctx_, nullptr);
       if (flushResult < 0) {
         return Err(
-            "FFmpegDecoder::feedPipeline failed: avcodec_send_packet flush failed: " +
+            "FfmpegDecoder::feedPipeline failed: avcodec_send_packet flush failed: " +
             parseFFmpegError(flushResult));
       }
       continue;
@@ -340,7 +337,7 @@ decoding::DecoderResult FFmpegDecoder::feedPipeline() {
         continue;
       }
       return Err(
-          "FFmpegDecoder::feedPipeline failed: av_read_frame failed: " + parseFFmpegError(r));
+          "FfmpegDecoder::feedPipeline failed: av_read_frame failed: " + parseFFmpegError(r));
     }
     readRetries = 0;
     if (packet_->stream_index != audio_stream_index_) {
@@ -351,12 +348,12 @@ decoding::DecoderResult FFmpegDecoder::feedPipeline() {
     av_packet_unref(packet_);
     if (r < 0) {
       return Err(
-          "FFmpegDecoder::feedPipeline failed: avcodec_send_packet failed: " + parseFFmpegError(r));
+          "FfmpegDecoder::feedPipeline failed: avcodec_send_packet failed: " + parseFFmpegError(r));
     }
   }
 }
 
-float FFmpegDecoder::getDurationInSeconds() const {
+float FfmpegDecoder::getDurationInSeconds() const {
   if (!isOpen() || fmt_ctx_ == nullptr || audio_stream_index_ < 0) {
     return 0;
   }
@@ -388,7 +385,7 @@ float FFmpegDecoder::getDurationInSeconds() const {
   return 0;
 }
 
-float FFmpegDecoder::getCurrentPositionInSeconds() const {
+float FfmpegDecoder::getCurrentPositionInSeconds() const {
   if (!isOpen() || output_sample_rate_ <= 0) {
     return 0;
   }
@@ -397,9 +394,9 @@ float FFmpegDecoder::getCurrentPositionInSeconds() const {
 
 // todo: offload this call to a separate thread because seeking decoder can take a while
 // current implementation suspends audio thread, which disable multiple playbacks
-decoding::DecoderResult FFmpegDecoder::seekToTime(double seconds) {
+decoding::DecoderResult FfmpegDecoder::seekToTime(double seconds) {
   if (!isOpen() || audio_stream_index_ < 0 || output_sample_rate_ <= 0) {
-    return Err("FFmpegDecoder::seekToTime failed: decoder is not open");
+    return Err("FfmpegDecoder::seekToTime failed: decoder is not open");
   }
   float dur = getDurationInSeconds();
   if (dur > 0 && std::isfinite(dur)) {
@@ -407,7 +404,7 @@ decoding::DecoderResult FFmpegDecoder::seekToTime(double seconds) {
   } else {
     seconds = std::max(0.0, seconds);
     if (!std::isfinite(seconds)) {
-      return Err("FFmpegDecoder::seekToTime failed: seconds is not finite");
+      return Err("FfmpegDecoder::seekToTime failed: seconds is not finite");
     }
   }
 
@@ -415,7 +412,7 @@ decoding::DecoderResult FFmpegDecoder::seekToTime(double seconds) {
   const int seekResult = avformat_seek_file(fmt_ctx_, -1, INT64_MIN, ts, INT64_MAX, 0);
   if (seekResult < 0) {
     return Err(
-        "FFmpegDecoder::seekToTime failed: avformat_seek_file failed: " +
+        "FfmpegDecoder::seekToTime failed: avformat_seek_file failed: " +
         parseFFmpegError(seekResult));
   }
   avcodec_flush_buffers(codec_ctx_);
@@ -426,7 +423,7 @@ decoding::DecoderResult FFmpegDecoder::seekToTime(double seconds) {
   return Ok(None);
 }
 
-size_t FFmpegDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
+size_t FfmpegDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
   if (!isOpen() || outInterleaved == nullptr || frameCount == 0 || output_channels_ <= 0) {
     return 0;
   }
@@ -459,35 +456,43 @@ size_t FFmpegDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
   return delivered;
 }
 
-} // namespace audioapi::ffmpeg_decoder
+size_t FfmpegDecoder::getTotalPcmFrameCount() const {
+  const float duration = getDurationInSeconds();
+  if (duration <= 0.0f || output_sample_rate_ <= 0) {
+    return 0;
+  }
+  return static_cast<size_t>(duration * static_cast<float>(output_sample_rate_));
+}
+
+} // namespace audioapi::decoding::ffmpeg
 
 #else
 
-namespace audioapi::ffmpeg_decoder {
-FFmpegDecoder::~FFmpegDecoder() = default;
-void FFmpegDecoder::close() {}
-decoding::DecoderResult FFmpegDecoder::openFile(int, const std::string &) {
+namespace audioapi::decoding::ffmpeg {
+FfmpegDecoder::~FfmpegDecoder() = default;
+void FfmpegDecoder::close() {}
+decoding::DecoderResult FfmpegDecoder::open(const decoding::LocalFileSource &) {
   return Err("FFmpeg is disabled");
 }
-decoding::DecoderResult FFmpegDecoder::openUrl(
-    int,
-    const std::string &,
-    const std::map<std::string, std::string> &) {
+decoding::DecoderResult FfmpegDecoder::open(const decoding::RemoteUrlSource &) {
   return Err("FFmpeg is disabled");
 }
-float FFmpegDecoder::getDurationInSeconds() const {
+float FfmpegDecoder::getDurationInSeconds() const {
   return 0;
 }
-float FFmpegDecoder::getCurrentPositionInSeconds() const {
+float FfmpegDecoder::getCurrentPositionInSeconds() const {
   return 0;
 }
-decoding::DecoderResult FFmpegDecoder::seekToTime(double) {
+decoding::DecoderResult FfmpegDecoder::seekToTime(double) {
   return Err("FFmpeg is disabled");
 }
-size_t FFmpegDecoder::readPcmFrames(float *, size_t) {
+size_t FfmpegDecoder::readPcmFrames(float *, size_t) {
+  return 0;
+}
+size_t FfmpegDecoder::getTotalPcmFrameCount() const {
   return 0;
 }
 
-} // namespace audioapi::ffmpeg_decoder
+} // namespace audioapi::decoding::ffmpeg
 
 #endif // !RN_AUDIO_API_FFMPEG_DISABLED
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.h
new file mode 100644
index 000000000..94a814a23
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.h
@@ -0,0 +1,86 @@
+#pragma once
+
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
+#include <audioapi/utils/Macros.h>
+#include <cstddef>
+#include <vector>
+
+extern "C" {
+#include <libavcodec/avcodec.h>
+#include <libavformat/avformat.h>
+#include <libavutil/opt.h>
+#include <libswresample/swresample.h>
+}
+
+namespace audioapi::decoding::ffmpeg {
+
+/**
+ * FFmpeg decoder for remote HTTP(S) / HLS and local HLS playlists.
+ *
+ * Usage: open via DecoderFactory → readPcmFrames repeatedly → close.
+ */
+class FfmpegDecoder : public AudioDecoderBackend {
+ public:
+  FfmpegDecoder() = default;
+  ~FfmpegDecoder() override;
+  DELETE_COPY_AND_MOVE(FfmpegDecoder);
+
+  [[nodiscard]] DecoderResult open(const LocalFileSource &source);
+  [[nodiscard]] DecoderResult open(const RemoteUrlSource &source);
+
+  [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
+
+  void close() override;
+
+  [[nodiscard]] bool isOpen() const override {
+    return fmt_ctx_ != nullptr && codec_ctx_ != nullptr;
+  }
+  [[nodiscard]] int outputChannels() const override {
+    return output_channels_;
+  }
+  [[nodiscard]] int outputSampleRate() const override {
+    return output_sample_rate_;
+  }
+
+  [[nodiscard]] bool isHlsStreaming() const override {
+    return is_hls_streaming_;
+  }
+
+  [[nodiscard]] float getDurationInSeconds() const override;
+
+  [[nodiscard]] float getCurrentPositionInSeconds() const override;
+
+  [[nodiscard]] DecoderResult seekToTime(double seconds) override;
+  [[nodiscard]] size_t getTotalPcmFrameCount() const override;
+
+ private:
+  [[nodiscard]] DecoderResult initializeDecodedStreams(
+      int outputSampleRate,
+      const char *errorContext);
+
+  [[nodiscard]] DecoderResult setupSwr();
+  [[nodiscard]] DecoderResult feedPipeline();
+  void appendFrameResampled(AVFrame *frame);
+  void detectHlsStreamingMode();
+
+  bool is_hls_streaming_ = false;
+
+  AVFormatContext *fmt_ctx_ = nullptr;
+  AVCodecContext *codec_ctx_ = nullptr;
+  SwrContext *swr_ = nullptr;
+  AVPacket *packet_ = nullptr;
+  AVFrame *frame_ = nullptr;
+
+  uint8_t **resampled_data_ = nullptr;
+  int max_resampled_samples_ = 0;
+
+  std::vector<float> leftover_;
+  size_t leftover_offset_ = 0;
+  int audio_stream_index_ = -1;
+  int output_channels_ = 0;
+  int output_sample_rate_ = 0;
+  size_t total_output_frames_ = 0;
+};
+
+} // namespace audioapi::decoding::ffmpeg
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.cpp
similarity index 52%
rename from packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.cpp
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.cpp
index 1babec16e..c703d547b 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.cpp
@@ -1,4 +1,4 @@
-#include <audioapi/libs/miniaudio/MiniAudioDecoding.h>
+#include <audioapi/decoding/backends/MiniAudioDecoder.h>
 
 #include <audioapi/libs/miniaudio/decoders/libopus/miniaudio_libopus.h>
 #include <audioapi/libs/miniaudio/decoders/libvorbis/miniaudio_libvorbis.h>
@@ -7,10 +7,11 @@
 #include <algorithm>
 #include <cmath>
 #include <cstddef>
+#include <memory>
 #include <string>
 #include <vector>
 
-namespace audioapi::miniaudio_decoder {
+namespace audioapi::decoding::miniaudio {
 
 namespace {
 
@@ -23,8 +24,7 @@ std::string parseMiniAudioError(ma_result result) {
 }
 
 ma_decoder_config makeDecoderConfig(const int outputSampleRate) {
-  const ma_uint32 outRate =
-      outputSampleRate > 0 ? static_cast<ma_uint32>(outputSampleRate) : 0;
+  const ma_uint32 outRate = outputSampleRate > 0 ? static_cast<ma_uint32>(outputSampleRate) : 0;
   ma_decoder_config config = ma_decoder_config_init(ma_format_f32, 0, outRate);
 #if RN_AUDIO_API_STATIC_EXTERNAL_LIBS_DISABLED
   config.ppCustomBackendVTables = nullptr;
@@ -37,8 +37,7 @@ ma_decoder_config makeDecoderConfig(const int outputSampleRate) {
   };
   // NOLINTNEXTLINE(cppcoreguidelines-pro-bounds-array-to-pointer-decay)
   config.ppCustomBackendVTables = customBackends;
-  config.customBackendCount =
-      sizeof(customBackends) / sizeof(customBackends[0]);
+  config.customBackendCount = sizeof(customBackends) / sizeof(customBackends[0]);
 #endif
   return config;
 }
@@ -81,33 +80,30 @@ float MiniAudioDecoder::getDurationInSeconds() const {
   if (!isOpen() || outputSampleRate_ <= 0 || totalLengthFrames_ == 0) {
     return 0;
   }
-  return static_cast<float>(static_cast<double>(totalLengthFrames_) /
-      static_cast<double>(outputSampleRate_));
+  return static_cast<float>(
+      static_cast<double>(totalLengthFrames_) / static_cast<double>(outputSampleRate_));
 }
 
 float MiniAudioDecoder::getCurrentPositionInSeconds() const {
   if (!isOpen() || outputSampleRate_ <= 0) {
     return 0;
   }
-  return static_cast<float>(static_cast<double>(totalOutputFrames_) /
-      static_cast<double>(outputSampleRate_));
+  return static_cast<float>(
+      static_cast<double>(totalOutputFrames_) / static_cast<double>(outputSampleRate_));
 }
 
-decoding::DecoderResult MiniAudioDecoder::openFile(
-    int outputSampleRate,
-    const std::string &path) {
+DecoderResult MiniAudioDecoder::open(const LocalFileSource &source) {
   close();
-  if (path.empty()) {
-    return Err("MiniAudioDecoder::openFile failed: path is empty");
+  if (source.path.empty()) {
+    return Err("MiniAudioDecoder::open failed: path is empty");
   }
 
-  ma_decoder_config config = makeDecoderConfig(outputSampleRate);
+  ma_decoder_config config = makeDecoderConfig(source.sampleRate);
   decoder_ = std::make_unique<ma_decoder>();
-  const ma_result result =
-      ma_decoder_init_file(path.c_str(), &config, decoder_.get());
+  const ma_result result = ma_decoder_init_file(source.path.c_str(), &config, decoder_.get());
   if (result != MA_SUCCESS) {
     teardownDecoder();
-    return Err("MiniAudioDecoder::openFile failed: " + parseMiniAudioError(result));
+    return Err("MiniAudioDecoder::open failed: " + parseMiniAudioError(result));
   }
 
   outputChannels_ = static_cast<int>(decoder_->outputChannels);
@@ -123,28 +119,20 @@ decoding::DecoderResult MiniAudioDecoder::openFile(
   return Ok(None);
 }
 
-decoding::DecoderResult MiniAudioDecoder::openMemory(
-    int outputSampleRate,
-    const void *data,
-    size_t size) {
+DecoderResult MiniAudioDecoder::open(const EncodedMemorySource &source) {
   close();
-  if (data == nullptr || size == 0) {
-    return Err("MiniAudioDecoder::openMemory failed: input data is empty");
+  if (source.data.empty()) {
+    return Err("MiniAudioDecoder::open failed: input data is empty");
   }
-  memoryCopy_.assign(
-      static_cast<const uint8_t *>(data),
-      static_cast<const uint8_t *>(data) + size);
+  memoryCopy_ = source.data;
 
-  ma_decoder_config config = makeDecoderConfig(outputSampleRate);
+  ma_decoder_config config = makeDecoderConfig(source.sampleRate);
   decoder_ = std::make_unique<ma_decoder>();
-  const ma_result result = ma_decoder_init_memory(
-      memoryCopy_.data(),
-      memoryCopy_.size(),
-      &config,
-      decoder_.get());
+  const ma_result result =
+      ma_decoder_init_memory(memoryCopy_.data(), memoryCopy_.size(), &config, decoder_.get());
   if (result != MA_SUCCESS) {
     teardownDecoder();
-    return Err("MiniAudioDecoder::openMemory failed: " + parseMiniAudioError(result));
+    return Err("MiniAudioDecoder::open failed: " + parseMiniAudioError(result));
   }
 
   outputChannels_ = static_cast<int>(decoder_->outputChannels);
@@ -160,21 +148,22 @@ decoding::DecoderResult MiniAudioDecoder::openMemory(
   return Ok(None);
 }
 
+size_t MiniAudioDecoder::getTotalPcmFrameCount() const {
+  return static_cast<size_t>(totalLengthFrames_);
+}
+
 size_t MiniAudioDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
   if (!isOpen() || outInterleaved == nullptr || frameCount == 0 || outputChannels_ <= 0) {
     return 0;
   }
   ma_uint64 framesRead = 0;
   ma_decoder_read_pcm_frames(
-      decoder_.get(),
-      outInterleaved,
-      static_cast<ma_uint64>(frameCount),
-      &framesRead);
+      decoder_.get(), outInterleaved, static_cast<ma_uint64>(frameCount), &framesRead);
   totalOutputFrames_ += static_cast<size_t>(framesRead);
   return static_cast<size_t>(framesRead);
 }
 
-decoding::DecoderResult MiniAudioDecoder::seekToTime(double seconds) {
+DecoderResult MiniAudioDecoder::seekToTime(double seconds) {
   if (!isOpen() || outputSampleRate_ <= 0) {
     return Err("MiniAudioDecoder::seekToTime failed: decoder is not open");
   }
@@ -188,7 +177,7 @@ decoding::DecoderResult MiniAudioDecoder::seekToTime(double seconds) {
     }
   }
 
-  const ma_uint64 frame =
+  const auto frame =
       static_cast<ma_uint64>(std::llround(seconds * static_cast<double>(outputSampleRate_)));
   const ma_result result = ma_decoder_seek_to_pcm_frame(decoder_.get(), frame);
   if (result != MA_SUCCESS) {
@@ -198,66 +187,4 @@ decoding::DecoderResult MiniAudioDecoder::seekToTime(double seconds) {
   return Ok(None);
 }
 
-namespace {
-
-std::shared_ptr<AudioBuffer> buildAudioBufferFromInterleaved(
-    std::vector<float> &interleaved,
-    int channels,
-    int sample_rate) {
-  if (interleaved.empty() || channels <= 0 || sample_rate <= 0) {
-    return nullptr;
-  }
-  const size_t frames = interleaved.size() / static_cast<size_t>(channels);
-  auto buf = std::make_shared<AudioBuffer>(
-      frames, channels, static_cast<float>(sample_rate));
-  buf->deinterleaveFrom(interleaved.data(), frames);
-  return buf;
-}
-
-} // namespace
-
-std::shared_ptr<AudioBuffer> decodeWithFilePath(const std::string &path, int sample_rate) {
-  MiniAudioDecoder dec;
-  const auto openResult = dec.openFile(sample_rate, path);
-  if (openResult.is_err()) {
-    return nullptr;
-  }
-  const int ch = std::max(1, dec.outputChannels());
-  std::vector<float> acc;
-  std::vector<float> tmp(decoding::IncrementalAudioDecoder::CHUNK_SIZE * static_cast<size_t>(ch));
-  while (true) {
-    const size_t n = dec.readPcmFrames(tmp.data(), decoding::IncrementalAudioDecoder::CHUNK_SIZE);
-    if (n == 0) {
-      break;
-    }
-    acc.insert(
-        acc.end(),
-        tmp.begin(),
-        tmp.begin() + static_cast<std::ptrdiff_t>(n * static_cast<size_t>(ch)));
-  }
-  return buildAudioBufferFromInterleaved(acc, dec.outputChannels(), dec.outputSampleRate());
-}
-
-std::shared_ptr<AudioBuffer> decodeWithMemoryBlock(const void *data, size_t size, int sample_rate) {
-  MiniAudioDecoder dec;
-  const auto openResult = dec.openMemory(sample_rate, data, size);
-  if (openResult.is_err()) {
-    return nullptr;
-  }
-  const int ch = std::max(1, dec.outputChannels());
-  std::vector<float> acc;
-  std::vector<float> tmp(decoding::IncrementalAudioDecoder::CHUNK_SIZE * static_cast<size_t>(ch));
-  while (true) {
-    const size_t n = dec.readPcmFrames(tmp.data(), decoding::IncrementalAudioDecoder::CHUNK_SIZE);
-    if (n == 0) {
-      break;
-    }
-    acc.insert(
-        acc.end(),
-        tmp.begin(),
-        tmp.begin() + static_cast<std::ptrdiff_t>(n * static_cast<size_t>(ch)));
-  }
-  return buildAudioBufferFromInterleaved(acc, dec.outputChannels(), dec.outputSampleRate());
-}
-
-} // namespace audioapi::miniaudio_decoder
+} // namespace audioapi::decoding::miniaudio
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.h
similarity index 54%
rename from packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.h
index 1bbfcf73e..4810722ee 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/miniaudio/MiniAudioDecoding.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.h
@@ -1,35 +1,30 @@
 #pragma once
 
-#include <audioapi/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/libs/miniaudio/miniaudio.h>
-#include <audioapi/utils/AudioBuffer.hpp>
 #include <audioapi/utils/Macros.h>
 
 #include <cstddef>
 #include <cstdint>
 #include <memory>
-#include <string>
 #include <vector>
 
-namespace audioapi::miniaudio_decoder {
+namespace audioapi::decoding::miniaudio {
 
 /**
  * MiniAudio-backed incremental decoder (Vorbis/Opus/WAV, etc. via ma_decoder + custom backends).
- * Local file / memory only — remote URLs use FFmpegDecoder::openUrl.
+ * Local file / memory only — remote URLs use FfmpegDecoder.
  */
-class MiniAudioDecoder : public decoding::IncrementalAudioDecoder {
+class MiniAudioDecoder : public AudioDecoderBackend {
  public:
   MiniAudioDecoder() = default;
   ~MiniAudioDecoder() override;
   DELETE_COPY_AND_MOVE(MiniAudioDecoder);
 
-  [[nodiscard]] decoding::DecoderResult openFile(
-      int outputSampleRate,
-      const std::string &path) override;
-  [[nodiscard]] decoding::DecoderResult openMemory(
-      int outputSampleRate,
-      const void *data,
-      size_t size) override;
+  [[nodiscard]] DecoderResult open(const LocalFileSource &source);
+  [[nodiscard]] DecoderResult open(const EncodedMemorySource &source);
+
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
   void close() override;
   [[nodiscard]] bool isOpen() const override;
@@ -37,7 +32,8 @@ class MiniAudioDecoder : public decoding::IncrementalAudioDecoder {
   [[nodiscard]] int outputSampleRate() const override;
   [[nodiscard]] float getDurationInSeconds() const override;
   [[nodiscard]] float getCurrentPositionInSeconds() const override;
-  [[nodiscard]] decoding::DecoderResult seekToTime(double seconds) override;
+  [[nodiscard]] DecoderResult seekToTime(double seconds) override;
+  [[nodiscard]] size_t getTotalPcmFrameCount() const override;
 
  private:
   void teardownDecoder();
@@ -50,7 +46,4 @@ class MiniAudioDecoder : public decoding::IncrementalAudioDecoder {
   std::uint64_t totalLengthFrames_ = 0;
 };
 
-std::shared_ptr<AudioBuffer> decodeWithMemoryBlock(const void *data, size_t size, int sample_rate);
-std::shared_ptr<AudioBuffer> decodeWithFilePath(const std::string &path, int sample_rate);
-
-} // namespace audioapi::miniaudio_decoder
+} // namespace audioapi::decoding::miniaudio
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/OsDecoderBase.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/OsDecoderBase.h
similarity index 77%
rename from packages/react-native-audio-api/common/cpp/audioapi/decoding/OsDecoderBase.h
rename to packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/OsDecoderBase.h
index 728adbb85..c282b2f80 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/OsDecoderBase.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/OsDecoderBase.h
@@ -1,11 +1,11 @@
 #pragma once
 
-#include <audioapi/decoding/IncrementalAudioDecoder.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/utils/Macros.h>
 
 #include <cstdint>
 
-namespace audioapi {
+namespace audioapi::decoding {
 
 /**
  * Shared open-state for OS-native incremental decoders (iOS / Android).
@@ -13,7 +13,7 @@ namespace audioapi {
  * Owns the common metadata reset by `close()`; subclasses release platform
  * resources in `releaseImpl()` (e.g. `impl_.reset()`).
  */
-class OsDecoderBase : public decoding::IncrementalAudioDecoder {
+class OsDecoderBase : public AudioDecoderBackend {
  public:
   OsDecoderBase() = default;
   ~OsDecoderBase() override = default;
@@ -52,6 +52,13 @@ class OsDecoderBase : public decoding::IncrementalAudioDecoder {
         static_cast<double>(framePosition_) / static_cast<double>(outputSampleRate_));
   }
 
+  [[nodiscard]] size_t getTotalPcmFrameCount() const override {
+    if (outputSampleRate_ <= 0 || durationSeconds_ <= 0.0) {
+      return 0;
+    }
+    return static_cast<size_t>(durationSeconds_ * static_cast<double>(outputSampleRate_));
+  }
+
  protected:
   /// Drop platform-native decoder resources (ExtAudioFile / MediaCodec, etc.).
   virtual void releaseImpl() = 0;
@@ -63,4 +70,4 @@ class OsDecoderBase : public decoding::IncrementalAudioDecoder {
   bool open_ = false;
 };
 
-} // namespace audioapi
+} // namespace audioapi::decoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
new file mode 100644
index 000000000..cf84719c1
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
@@ -0,0 +1,167 @@
+#include <audioapi/decoding/backends/RawPcmDecoder.h>
+#include <audioapi/libs/base64/base64.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+
+namespace audioapi::decoding::raw_pcm {
+namespace {
+
+float uint8ToFloat(uint8_t byte1, uint8_t byte2) {
+  return static_cast<float>(static_cast<int16_t>((byte2 << 8) | byte1)) /
+      static_cast<float>(INT16_MAX);
+}
+
+} // namespace
+
+DecoderResult RawPcmDecoder::openFromBytes(
+    const uint8_t *data,
+    size_t size,
+    int sampleRate,
+    int channelCount,
+    bool interleaved) {
+  close();
+  if (data == nullptr || size == 0) {
+    return Err("RawPcmDecoder::open failed: input data is empty");
+  }
+  if (sampleRate <= 0 || !std::isfinite(sampleRate)) {
+    return Err("RawPcmDecoder::open failed: invalid sample rate");
+  }
+  if (channelCount <= 0) {
+    return Err("RawPcmDecoder::open failed: invalid channel count");
+  }
+
+  const size_t bytesPerFrame = static_cast<size_t>(channelCount) * sizeof(int16_t);
+  if (size % bytesPerFrame != 0) {
+    return Err("RawPcmDecoder::open failed: PCM byte length is not frame-aligned");
+  }
+
+  const size_t numFrames = size / bytesPerFrame;
+  interleavedPcm_.resize(numFrames * static_cast<size_t>(channelCount));
+
+  for (int ch = 0; ch < channelCount; ++ch) {
+    for (size_t i = 0; i < numFrames; ++i) {
+      size_t offset;
+      if (interleaved) {
+        offset =
+            (i * static_cast<size_t>(channelCount) + static_cast<size_t>(ch)) * sizeof(int16_t);
+      } else {
+        offset = (static_cast<size_t>(ch) * numFrames + i) * sizeof(int16_t);
+      }
+      interleavedPcm_[i * static_cast<size_t>(channelCount) + static_cast<size_t>(ch)] =
+          uint8ToFloat(data[offset], data[offset + 1]);
+    }
+  }
+
+  outputChannels_ = channelCount;
+  outputSampleRate_ = sampleRate;
+  framePosition_ = 0;
+  return Ok(None);
+}
+
+DecoderResult RawPcmDecoder::open(const RawPcmSource &source) {
+  return openFromBytes(
+      source.data.data(),
+      source.data.size(),
+      source.sampleRate,
+      source.channelCount,
+      source.interleaved);
+}
+
+DecoderResult RawPcmDecoder::open(const RawPcmBase64Source &source) {
+  auto decodedData = base64_decode(source.base64, false);
+  return openFromBytes(
+      reinterpret_cast<const uint8_t *>(decodedData.data()),
+      decodedData.size(),
+      source.sampleRate,
+      source.channelCount,
+      source.interleaved);
+}
+
+size_t RawPcmDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
+  if (!isOpen() || outInterleaved == nullptr || frameCount == 0 || outputChannels_ <= 0) {
+    return 0;
+  }
+
+  const size_t totalFrames = interleavedPcm_.size() / static_cast<size_t>(outputChannels_);
+  if (framePosition_ >= totalFrames) {
+    return 0;
+  }
+
+  const size_t framesToRead = std::min(frameCount, totalFrames - framePosition_);
+  const auto channelCount = static_cast<size_t>(outputChannels_);
+  const size_t srcOffset = framePosition_ * channelCount;
+  std::copy_n(
+      interleavedPcm_.begin() + static_cast<std::ptrdiff_t>(srcOffset),
+      framesToRead * channelCount,
+      outInterleaved);
+  framePosition_ += framesToRead;
+  return framesToRead;
+}
+
+DecoderResult RawPcmDecoder::seekToTime(double seconds) {
+  if (!isOpen() || outputSampleRate_ <= 0) {
+    return Err("RawPcmDecoder::seekToTime failed: decoder is not open");
+  }
+  if (!std::isfinite(seconds)) {
+    return Err("RawPcmDecoder::seekToTime failed: seconds is not finite");
+  }
+
+  const float duration = getDurationInSeconds();
+  if (duration > 0.0f) {
+    seconds = std::clamp(seconds, 0.0, static_cast<double>(duration));
+  } else {
+    seconds = std::max(0.0, seconds);
+  }
+
+  framePosition_ =
+      static_cast<size_t>(std::llround(seconds * static_cast<double>(outputSampleRate_)));
+  const size_t totalFrames = getTotalPcmFrameCount();
+  framePosition_ = std::min(framePosition_, totalFrames);
+  return Ok(None);
+}
+
+void RawPcmDecoder::close() {
+  interleavedPcm_.clear();
+  framePosition_ = 0;
+  outputChannels_ = 0;
+  outputSampleRate_ = 0;
+}
+
+bool RawPcmDecoder::isOpen() const {
+  return !interleavedPcm_.empty() && outputChannels_ > 0 && outputSampleRate_ > 0;
+}
+
+int RawPcmDecoder::outputChannels() const {
+  return outputChannels_;
+}
+
+int RawPcmDecoder::outputSampleRate() const {
+  return outputSampleRate_;
+}
+
+float RawPcmDecoder::getDurationInSeconds() const {
+  if (!isOpen()) {
+    return 0.0f;
+  }
+  return static_cast<float>(
+      static_cast<double>(getTotalPcmFrameCount()) / static_cast<double>(outputSampleRate_));
+}
+
+float RawPcmDecoder::getCurrentPositionInSeconds() const {
+  if (!isOpen() || outputSampleRate_ <= 0) {
+    return 0.0f;
+  }
+  return static_cast<float>(
+      static_cast<double>(framePosition_) / static_cast<double>(outputSampleRate_));
+}
+
+size_t RawPcmDecoder::getTotalPcmFrameCount() const {
+  if (!isOpen() || outputChannels_ <= 0) {
+    return 0;
+  }
+  return interleavedPcm_.size() / static_cast<size_t>(outputChannels_);
+}
+
+} // namespace audioapi::decoding::raw_pcm
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.h
new file mode 100644
index 000000000..464fed78a
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.h
@@ -0,0 +1,45 @@
+#pragma once
+
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/backends/AudioDecoderBackend.h>
+#include <audioapi/utils/Macros.h>
+
+#include <cstddef>
+#include <vector>
+
+namespace audioapi::decoding::raw_pcm {
+
+class RawPcmDecoder : public AudioDecoderBackend {
+ public:
+  RawPcmDecoder() = default;
+  ~RawPcmDecoder() override = default;
+  DELETE_COPY_AND_MOVE(RawPcmDecoder);
+
+  [[nodiscard]] DecoderResult open(const RawPcmSource &source);
+  [[nodiscard]] DecoderResult open(const RawPcmBase64Source &source);
+
+  [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
+  [[nodiscard]] DecoderResult seekToTime(double seconds) override;
+  void close() override;
+  [[nodiscard]] bool isOpen() const override;
+  [[nodiscard]] int outputChannels() const override;
+  [[nodiscard]] int outputSampleRate() const override;
+  [[nodiscard]] float getDurationInSeconds() const override;
+  [[nodiscard]] float getCurrentPositionInSeconds() const override;
+  [[nodiscard]] size_t getTotalPcmFrameCount() const override;
+
+ private:
+  [[nodiscard]] DecoderResult openFromBytes(
+      const uint8_t *data,
+      size_t size,
+      int sampleRate,
+      int channelCount,
+      bool interleaved);
+
+  std::vector<float> interleavedPcm_;
+  size_t framePosition_ = 0;
+  int outputChannels_ = 0;
+  int outputSampleRate_ = 0;
+};
+
+} // namespace audioapi::decoding::raw_pcm
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h b/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
deleted file mode 100644
index 3c40447c3..000000000
--- a/packages/react-native-audio-api/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.h
+++ /dev/null
@@ -1,103 +0,0 @@
-/*
- * This file dynamically links to the FFmpeg library, which is licensed under
- * the GNU Lesser General Public License (LGPL) version 2.1 or later.
- *
- * Our own code in this file is licensed under the MIT License and dynamic
- * linking allows you to use this code without your entire project being subject
- * to the terms of the LGPL. However, note that if you link statically to
- * FFmpeg, you must comply with the terms of the LGPL for FFmpeg itself.
- */
-
-#pragma once
-
-#include <audioapi/decoding/IncrementalAudioDecoder.h>
-#include <audioapi/utils/Macros.h>
-#include <cstddef>
-#include <map>
-#include <string>
-#include <vector>
-
-extern "C" {
-#include <libavcodec/avcodec.h>
-#include <libavformat/avformat.h>
-#include <libavutil/opt.h>
-#include <libswresample/swresample.h>
-}
-
-namespace audioapi::ffmpeg_decoder {
-
-/**
- * FFmpeg decoder for remote HTTP(S) / HLS (`openUrl`). Local file and memory
- * decode use OS / miniaudio instead.
- *
- * Usage: openUrl → readPcmFrames repeatedly → close.
- */
-class FFmpegDecoder : public decoding::IncrementalAudioDecoder {
- public:
-  FFmpegDecoder() = default;
-  ~FFmpegDecoder() override;
-  DELETE_COPY_AND_MOVE(FFmpegDecoder);
-
-  [[nodiscard]] decoding::DecoderResult openFile(int outputSampleRate, const std::string &path)
-      override;
-
-  /// Opens a remote HTTP(S) / HLS URL. Not part of IncrementalAudioDecoder —
-  /// only FFmpeg owns network demux.
-  [[nodiscard]] decoding::DecoderResult openUrl(
-      int outputSampleRate,
-      const std::string &url,
-      const std::map<std::string, std::string> &headers = {});
-
-  [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
-
-  void close() override;
-
-  [[nodiscard]] bool isOpen() const override {
-    return fmt_ctx_ != nullptr && codec_ctx_ != nullptr;
-  }
-  [[nodiscard]] int outputChannels() const override {
-    return output_channels_;
-  }
-  [[nodiscard]] int outputSampleRate() const override {
-    return output_sample_rate_;
-  }
-
-  [[nodiscard]] bool isHlsStreaming() const override {
-    return is_hls_streaming_;
-  }
-
-  [[nodiscard]] float getDurationInSeconds() const override;
-
-  [[nodiscard]] float getCurrentPositionInSeconds() const override;
-
-  [[nodiscard]] decoding::DecoderResult seekToTime(double seconds) override;
-
- private:
-  [[nodiscard]] decoding::DecoderResult initializeDecodedStreams(
-      int outputSampleRate,
-      const char *errorContext);
-  [[nodiscard]] decoding::DecoderResult setupSwr();
-  [[nodiscard]] decoding::DecoderResult feedPipeline();
-  void appendFrameResampled(AVFrame *frame);
-  void detectHlsStreamingMode();
-
-  bool is_hls_streaming_ = false;
-
-  AVFormatContext *fmt_ctx_ = nullptr;
-  AVCodecContext *codec_ctx_ = nullptr;
-  SwrContext *swr_ = nullptr;
-  AVPacket *packet_ = nullptr;
-  AVFrame *frame_ = nullptr;
-
-  uint8_t **resampled_data_ = nullptr;
-  int max_resampled_samples_ = 0;
-
-  std::vector<float> leftover_;
-  size_t leftover_offset_ = 0;
-  int audio_stream_index_ = -1;
-  int output_channels_ = 0;
-  int output_sample_rate_ = 0;
-  size_t total_output_frames_ = 0;
-};
-
-} // namespace audioapi::ffmpeg_decoder
diff --git a/packages/react-native-audio-api/common/cpp/test/CMakeLists.txt b/packages/react-native-audio-api/common/cpp/test/CMakeLists.txt
index f11d0aaea..5f80efd2d 100644
--- a/packages/react-native-audio-api/common/cpp/test/CMakeLists.txt
+++ b/packages/react-native-audio-api/common/cpp/test/CMakeLists.txt
@@ -40,7 +40,7 @@ list(FILTER RNAUDIOAPI_SRC EXCLUDE REGEX ".*/audioapi/HostObjects/.*\\.cpp$")
 
 list(REMOVE_ITEM RNAUDIOAPI_SRC
   "${REACT_NATIVE_AUDIO_API_DIR}/common/cpp/audioapi/core/AudioContext.cpp"
-  "${REACT_NATIVE_AUDIO_API_DIR}/common/cpp/audioapi/libs/ffmpeg/FFmpegDecoding.cpp"
+  "${REACT_NATIVE_AUDIO_API_DIR}/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp"
 )
 
 file(GLOB_RECURSE RNAUDIOAPI_LIBS
diff --git a/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
new file mode 100644
index 000000000..f87be04ac
--- /dev/null
+++ b/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
@@ -0,0 +1,136 @@
+#include <audioapi/decoding/DecoderFactory.h>
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/libs/miniaudio/miniaudio.h>
+#include <gtest/gtest.h>
+
+#include <cstdio>
+#include <fstream>
+#include <string>
+#include <vector>
+
+using namespace audioapi;
+
+// NOLINTBEGIN
+
+namespace {
+
+constexpr ma_uint32 sampleRate = 48000;
+constexpr ma_uint32 channelCount = 1;
+
+std::string testFilePath(const std::string &name) {
+  return ::testing::TempDir() + name;
+}
+
+void removeFile(const std::string &path) {
+  std::remove(path.c_str());
+}
+
+void writeWavFile(const std::string &path, const std::vector<float> &frames) {
+  ma_encoder encoder;
+  ma_encoder_config config =
+      ma_encoder_config_init(ma_encoding_format_wav, ma_format_f32, channelCount, sampleRate);
+  ASSERT_EQ(ma_encoder_init_file(path.c_str(), &config, &encoder), MA_SUCCESS);
+
+  ma_uint64 framesWritten = 0;
+  EXPECT_EQ(
+      ma_encoder_write_pcm_frames(
+          &encoder, frames.data(), static_cast<ma_uint64>(frames.size()), &framesWritten),
+      MA_SUCCESS);
+  EXPECT_EQ(framesWritten, frames.size());
+
+  ma_encoder_uninit(&encoder);
+}
+
+std::vector<uint8_t> readFileBytes(const std::string &path) {
+  std::ifstream input(path, std::ios::binary);
+  EXPECT_TRUE(input.is_open());
+  return std::vector<uint8_t>(
+      std::istreambuf_iterator<char>(input), std::istreambuf_iterator<char>());
+}
+
+} // namespace
+
+TEST(DecoderFactoryTest, OpensLocalWavFile) {
+  const std::string path = testFilePath("decoder-factory.wav");
+  removeFile(path);
+  writeWavFile(path, std::vector<float>(sampleRate / 2, 0.25F));
+
+  auto result = decoding::createDecoder(decoding::LocalFileSource{.path = path, .sampleRate = 0});
+  ASSERT_TRUE(result.is_ok()) << result.unwrap_err();
+
+  auto decoder = std::move(result).unwrap();
+  EXPECT_TRUE(decoder->isOpen());
+  EXPECT_EQ(decoder->outputChannels(), static_cast<int>(channelCount));
+  EXPECT_EQ(decoder->outputSampleRate(), static_cast<int>(sampleRate));
+  EXPECT_GT(decoder->getTotalPcmFrameCount(), 0U);
+  decoder->close();
+
+  removeFile(path);
+}
+
+TEST(DecoderFactoryTest, OpensEncodedMemoryWav) {
+  const std::string path = testFilePath("decoder-factory-memory.wav");
+  removeFile(path);
+  writeWavFile(path, std::vector<float>(sampleRate / 4, 0.5F));
+  const auto bytes = readFileBytes(path);
+
+  auto result =
+      decoding::createDecoder(decoding::EncodedMemorySource{.data = bytes, .sampleRate = 0});
+  ASSERT_TRUE(result.is_ok()) << result.unwrap_err();
+
+  auto decoder = std::move(result).unwrap();
+  EXPECT_TRUE(decoder->isOpen());
+  EXPECT_GT(decoder->getDurationInSeconds(), 0.0f);
+  decoder->close();
+
+  removeFile(path);
+}
+
+TEST(DecoderFactoryTest, RejectsEmptyLocalFilePath) {
+  auto result = decoding::createDecoder(decoding::LocalFileSource{});
+  EXPECT_TRUE(result.is_err());
+}
+
+TEST(DecoderFactoryTest, RejectsEmptyEncodedMemory) {
+  auto result = decoding::createDecoder(decoding::EncodedMemorySource{});
+  EXPECT_TRUE(result.is_err());
+}
+
+TEST(DecoderFactoryTest, RejectsRemoteUrlWhenFfmpegDisabled) {
+  auto result = decoding::createDecoder(
+      decoding::RemoteUrlSource{.url = "https://example.com/audio.mp3", .sampleRate = 0});
+  EXPECT_TRUE(result.is_err());
+  EXPECT_EQ(result.unwrap_err(), "FFmpeg is disabled, cannot decode remote URL");
+}
+
+TEST(DecoderFactoryTest, RejectsLocalM3u8WhenFfmpegDisabled) {
+  auto result = decoding::createDecoder(
+      decoding::LocalFileSource{.path = "/tmp/playlist.m3u8", .sampleRate = 0});
+  EXPECT_TRUE(result.is_err());
+  EXPECT_EQ(result.unwrap_err(), "FFmpeg is disabled, cannot decode local HLS (.m3u8) playlists");
+}
+
+TEST(DecoderFactoryTest, OpensRawPcmSource) {
+  std::vector<uint8_t> pcmBytes(2);
+  pcmBytes[0] = 0x00;
+  pcmBytes[1] = 0x00;
+
+  auto result = decoding::createDecoder(
+      decoding::RawPcmSource{
+          .data = std::move(pcmBytes),
+          .sampleRate = 44100,
+          .channelCount = 1,
+          .interleaved = true});
+  ASSERT_TRUE(result.is_ok()) << result.unwrap_err();
+
+  auto decoder = std::move(result).unwrap();
+  EXPECT_EQ(decoder->outputChannels(), 1);
+  EXPECT_EQ(decoder->outputSampleRate(), 44100);
+  EXPECT_EQ(decoder->getTotalPcmFrameCount(), 1U);
+
+  float sample = 0.0f;
+  EXPECT_EQ(decoder->readPcmFrames(&sample, 1), 1U);
+  decoder->close();
+}
+
+// NOLINTEND
diff --git a/packages/react-native-audio-api/common/cpp/test/src/utils/AudioDecodingTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/utils/AudioDecodingTest.cpp
index afefbf2ef..fbf655641 100644
--- a/packages/react-native-audio-api/common/cpp/test/src/utils/AudioDecodingTest.cpp
+++ b/packages/react-native-audio-api/common/cpp/test/src/utils/AudioDecodingTest.cpp
@@ -1,4 +1,4 @@
-#include <audioapi/core/utils/AudioDecoding.h>
+#include <audioapi/decoding/AudioDecoding.h>
 #include <audioapi/libs/miniaudio/miniaudio.h>
 #include <gtest/gtest.h>
 
@@ -111,6 +111,28 @@ TEST(AudioDecodingTest, RejectsInvalidDurationMetadataFromMemory) {
   EXPECT_TRUE(result.is_err());
 }
 
+TEST(AudioDecodingTest, DecodesLocalWavFile) {
+  const std::string input = writeDurationWavFile("audio-decode.wav");
+
+  auto result = audiodecoding::decodeWithFilePath(input, static_cast<float>(sampleRate));
+  ASSERT_TRUE(result.is_ok()) << result.unwrap_err();
+  EXPECT_EQ(result.unwrap()->getSize(), sampleRate / 2);
+
+  removeFile(input);
+}
+
+TEST(AudioDecodingTest, DecodesMemoryWav) {
+  const std::string input = writeDurationWavFile("audio-decode-memory.wav");
+  const auto bytes = readFileBytes(input);
+
+  auto result = audiodecoding::decodeWithMemoryBlock(
+      bytes.data(), bytes.size(), static_cast<float>(sampleRate));
+  ASSERT_TRUE(result.is_ok()) << result.unwrap_err();
+  EXPECT_EQ(result.unwrap()->getSize(), sampleRate / 2);
+
+  removeFile(input);
+}
+
 TEST(AudioDecodingTest, ReturnsDisabledErrorForUrlProbeWhenFFmpegIsUnavailable) {
   auto result = audiodecoding::probeDurationWithUrl("https://example.com/audio.mp3", 0, {});
 
diff --git a/packages/react-native-audio-api/common/cpp/test/src/utils/AudioFileConcatenatorTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/utils/AudioFileConcatenatorTest.cpp
index 02919a238..d5b25455d 100644
--- a/packages/react-native-audio-api/common/cpp/test/src/utils/AudioFileConcatenatorTest.cpp
+++ b/packages/react-native-audio-api/common/cpp/test/src/utils/AudioFileConcatenatorTest.cpp
@@ -1,4 +1,4 @@
-#include <audioapi/core/utils/AudioFileConcatenator.h>
+#include <audioapi/decoding/AudioFileConcatenator.h>
 #include <audioapi/libs/miniaudio/miniaudio.h>
 #include <gtest/gtest.h>
 
diff --git a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
index a6c72d014..6caa20f78 100644
--- a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
+++ b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.h
@@ -1,6 +1,7 @@
 #pragma once
 
-#include <audioapi/decoding/OsDecoderBase.h>
+#include <audioapi/decoding/DecoderSource.h>
+#include <audioapi/decoding/backends/OsDecoderBase.h>
 #include <audioapi/utils/Macros.h>
 
 #include <cstddef>
@@ -18,16 +19,14 @@ struct IosDecoderState;
  * Opens local files or in-memory buffers and pulls interleaved float PCM on
  * demand. Remote URL / HLS decoding stays on FFmpeg.
  */
-class IOSDecoder : public OsDecoderBase {
+class IOSDecoder : public decoding::OsDecoderBase {
  public:
   IOSDecoder();
   ~IOSDecoder() override;
   DELETE_COPY_AND_MOVE(IOSDecoder);
 
-  [[nodiscard]] decoding::DecoderResult openFile(int outputSampleRate, const std::string &path)
-      override;
-  [[nodiscard]] decoding::DecoderResult
-  openMemory(int outputSampleRate, const void *data, size_t size) override;
+  [[nodiscard]] decoding::DecoderResult open(const decoding::LocalFileSource &source);
+  [[nodiscard]] decoding::DecoderResult open(const decoding::EncodedMemorySource &source);
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
   [[nodiscard]] decoding::DecoderResult seekToTime(double seconds) override;
 
diff --git a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
index 8ff269f29..d23e2ab49 100644
--- a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
+++ b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
@@ -192,31 +192,31 @@ SInt64 memoryGetSizeProc(void *inClientData)
   return Ok(None);
 }
 
-decoding::DecoderResult IOSDecoder::openFile(int outputSampleRate, const std::string &path)
+decoding::DecoderResult IOSDecoder::open(const decoding::LocalFileSource &source)
 {
   close();
-  if (path.empty()) {
-    return Err("IOSDecoder::openFile failed: path is empty");
+  if (source.path.empty()) {
+    return Err("IOSDecoder::open failed: path is empty");
   }
 
   @autoreleasepool {
-    NSString *nsPath = [NSString stringWithUTF8String:path.c_str()];
+    NSString *nsPath = [NSString stringWithUTF8String:source.path.c_str()];
     if (nsPath == nil) {
-      return Err("IOSDecoder::openFile failed: invalid path encoding");
+      return Err("IOSDecoder::open failed: invalid path encoding");
     }
     NSURL *url = [NSURL fileURLWithPath:nsPath];
     ExtAudioFileRef extFile = nullptr;
     // NOLINTNEXTLINE(cppcoreguidelines-pro-type-cstyle-cast)
     OSStatus status = ExtAudioFileOpenURL((__bridge CFURLRef)url, &extFile);
     if (status != noErr || extFile == nullptr) {
-      return Err("IOSDecoder::openFile ExtAudioFileOpenURL failed: " + std::to_string(status));
+      return Err("IOSDecoder::open ExtAudioFileOpenURL failed: " + std::to_string(status));
     }
 
     auto state = std::make_unique<IosDecoderState>();
     state->extFile.reset(extFile);
     auto configured = configureExtAudioFile(
         state->extFile.get(),
-        outputSampleRate,
+        source.sampleRate,
         outputChannels_,
         outputSampleRate_,
         durationSeconds_,
@@ -232,22 +232,21 @@ SInt64 memoryGetSizeProc(void *inClientData)
   }
 }
 
-decoding::DecoderResult IOSDecoder::openMemory(int outputSampleRate, const void *data, size_t size)
+decoding::DecoderResult IOSDecoder::open(const decoding::EncodedMemorySource &source)
 {
   close();
-  if (data == nullptr || size == 0) {
-    return Err("IOSDecoder::openMemory failed: empty input");
+  if (source.data.empty()) {
+    return Err("IOSDecoder::open failed: empty input");
   }
 
   auto state = std::make_unique<IosDecoderState>();
-  state->memory.assign(
-      static_cast<const uint8_t *>(data), static_cast<const uint8_t *>(data) + size);
+  state->memory = source.data;
 
   // Wrap the owned bytes with AudioFile callbacks, then wrap that with
-  // ExtAudioFile so we get the same read/seek/convert path as openFile without
+  // ExtAudioFile so we get the same read/seek/convert path as open without
   // touching the filesystem.
   AudioFileTypeID hint = 0;
-  const char *ext = guessFileTypeExtension(data, size);
+  const char *ext = guessFileTypeExtension(source.data.data(), source.data.size());
   if (std::strcmp(ext, "wav") == 0) {
     hint = kAudioFileWAVEType;
   } else if (std::strcmp(ext, "mp3") == 0) {
@@ -268,8 +267,7 @@ SInt64 memoryGetSizeProc(void *inClientData)
   OSStatus status = AudioFileOpenWithCallbacks(
       state.get(), memoryReadProc, nullptr, memoryGetSizeProc, nullptr, hint, &audioFile);
   if (status != noErr || audioFile == nullptr) {
-    return Err(
-        "IOSDecoder::openMemory AudioFileOpenWithCallbacks failed: " + std::to_string(status));
+    return Err("IOSDecoder::open AudioFileOpenWithCallbacks failed: " + std::to_string(status));
   }
   state->audioFile.reset(audioFile);
 
@@ -277,14 +275,13 @@ SInt64 memoryGetSizeProc(void *inClientData)
   status =
       ExtAudioFileWrapAudioFileID(state->audioFile.get(), static_cast<Boolean>(false), &extFile);
   if (status != noErr || extFile == nullptr) {
-    return Err(
-        "IOSDecoder::openMemory ExtAudioFileWrapAudioFileID failed: " + std::to_string(status));
+    return Err("IOSDecoder::open ExtAudioFileWrapAudioFileID failed: " + std::to_string(status));
   }
   state->extFile.reset(extFile);
 
   auto configured = configureExtAudioFile(
       state->extFile.get(),
-      outputSampleRate,
+      source.sampleRate,
       outputChannels_,
       outputSampleRate_,
       durationSeconds_,

From e4709e5cc4f31790ff47481759f8b290db19c28e Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Tue, 21 Jul 2026 17:06:47 +0200
Subject: [PATCH 04/12] fix: tests

---
 .../common/cpp/audioapi/decoding/DecoderSource.h                | 1 +
 .../common/cpp/test/src/decoding/DecoderFactoryTest.cpp         | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
index fdb5cdd14..4f97004d0 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
@@ -3,6 +3,7 @@
 #include <algorithm>
 #include <cctype>
 #include <cstddef>
+#include <cstdint>
 #include <map>
 #include <string>
 #include <variant>
diff --git a/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
index f87be04ac..9837d8fe4 100644
--- a/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
+++ b/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
@@ -118,8 +118,8 @@ TEST(DecoderFactoryTest, OpensRawPcmSource) {
   auto result = decoding::createDecoder(
       decoding::RawPcmSource{
           .data = std::move(pcmBytes),
-          .sampleRate = 44100,
           .channelCount = 1,
+          .sampleRate = 44100,
           .interleaved = true});
   ASSERT_TRUE(result.is_ok()) << result.unwrap_err();
 

From 076c896168ad90854bf3cb5b284027d9da11e547 Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Tue, 21 Jul 2026 17:13:12 +0200
Subject: [PATCH 05/12] fix: tests v2

---
 .../common/cpp/test/src/decoding/DecoderFactoryTest.cpp       | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
index 9837d8fe4..9c183af9c 100644
--- a/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
+++ b/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
@@ -119,8 +119,8 @@ TEST(DecoderFactoryTest, OpensRawPcmSource) {
       decoding::RawPcmSource{
           .data = std::move(pcmBytes),
           .channelCount = 1,
-          .sampleRate = 44100,
-          .interleaved = true});
+          .interleaved = true,
+          .sampleRate = 44100});
   ASSERT_TRUE(result.is_ok()) << result.unwrap_err();
 
   auto decoder = std::move(result).unwrap();

From e1bacd34a44ed815abfd0816479128976a304551 Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Thu, 23 Jul 2026 13:39:09 +0200
Subject: [PATCH 06/12] refactor: onboard most of the osdecoderbase to audio
 deckoder backend

---
 .../HostObjects/utils/NodeOptionsParser.h     |   4 +-
 .../cpp/audioapi/decoding/DecoderFactory.cpp  |   7 -
 .../cpp/audioapi/decoding/DecoderSource.h     |   4 -
 .../decoding/backends/AudioDecoderBackend.h   |  53 ++++++-
 .../decoding/backends/FfmpegDecoder.cpp       | 135 +++++++-----------
 .../decoding/backends/FfmpegDecoder.h         |  18 +--
 .../decoding/backends/MiniAudioDecoder.cpp    |  49 ++-----
 .../decoding/backends/MiniAudioDecoder.h      |  11 +-
 .../decoding/backends/OsDecoderBase.h         |  42 +-----
 .../decoding/backends/RawPcmDecoder.cpp       |  51 ++-----
 .../decoding/backends/RawPcmDecoder.h         |   9 +-
 .../utils/MiniaudioImplementation.cpp         |  11 ++
 .../test/src/decoding/DecoderFactoryTest.cpp  |   4 +-
 .../audioapi/ios/core/utils/IOSDecoding.mm    |   8 +-
 14 files changed, 141 insertions(+), 265 deletions(-)

diff --git a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
index 015dd5251..12e466c03 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/HostObjects/utils/NodeOptionsParser.h
@@ -352,8 +352,8 @@ inline AudioFileSourceOptions parseAudioFileSourceOptions(
       options.requiresFFmpeg = true;
     } else {
       options.filePath = path;
-      // Local HLS playlists still need FFmpeg; other local formats use OS/miniaudio.
-      options.requiresFFmpeg = audiodecoding::pathHasExtension(path, {".m3u8"});
+      // Local files use OS/miniaudio — FFmpeg is only for remote/network sources.
+      options.requiresFFmpeg = false;
     }
   } else if (sourceValue.isObject()) {
     auto sourceObj = sourceValue.asObject(runtime);
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.cpp
index babff678c..b35536348 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderFactory.cpp
@@ -73,13 +73,6 @@ CreateDecoderResult createDecoder(const DecoderSource &source) {
             if (localSource.path.empty()) {
               return Err("DecoderFactory: local file path is empty");
             }
-            if (localPathRequiresFfmpeg(localSource.path)) {
-#if !RN_AUDIO_API_FFMPEG_DISABLED
-              return createAndOpen<ffmpeg::FfmpegDecoder>(localSource);
-#else
-              return Err("FFmpeg is disabled, cannot decode local HLS (.m3u8) playlists");
-#endif
-            }
             return tryOpenWithOsFallback(
                 localSource, "Cannot open local file: unsupported or invalid audio format");
           },
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
index 4f97004d0..2b402aefd 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/DecoderSource.h
@@ -59,8 +59,4 @@ using DecoderSource = std::variant<
       extensions, [&pathLower](const std::string &ext) { return pathLower.ends_with(ext); });
 }
 
-[[nodiscard]] inline bool localPathRequiresFfmpeg(const std::string &path) {
-  return pathHasExtension(path, {".m3u8"});
-}
-
 } // namespace audioapi::decoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/AudioDecoderBackend.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/AudioDecoderBackend.h
index d2abff57c..fa3f9fa34 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/AudioDecoderBackend.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/AudioDecoderBackend.h
@@ -3,6 +3,7 @@
 #include <audioapi/utils/Macros.h>
 #include <audioapi/utils/Result.hpp>
 #include <cstddef>
+#include <cstdint>
 #include <string>
 
 namespace audioapi::decoding {
@@ -20,17 +21,57 @@ class AudioDecoderBackend {
   [[nodiscard]] virtual DecoderResult seekToTime(double seconds) = 0;
   virtual void close() = 0;
   [[nodiscard]] virtual bool isOpen() const = 0;
-  [[nodiscard]] virtual int outputChannels() const = 0;
-  [[nodiscard]] virtual int outputSampleRate() const = 0;
-  [[nodiscard]] virtual float getDurationInSeconds() const = 0;
-  [[nodiscard]] virtual float getCurrentPositionInSeconds() const = 0;
+
+  [[nodiscard]] virtual int outputChannels() const {
+    return outputChannels_;
+  }
+  [[nodiscard]] virtual int outputSampleRate() const {
+    return outputSampleRate_;
+  }
+  [[nodiscard]] virtual float getDurationInSeconds() const {
+    if (outputSampleRate_ <= 0 || totalPcmFrames_ == 0) {
+      return 0.0f;
+    }
+    return static_cast<float>(
+        static_cast<double>(totalPcmFrames_) / static_cast<double>(outputSampleRate_));
+  }
+  [[nodiscard]] virtual float getCurrentPositionInSeconds() const {
+    if (outputSampleRate_ <= 0) {
+      return 0.0f;
+    }
+    return static_cast<float>(
+        static_cast<double>(framePosition_) / static_cast<double>(outputSampleRate_));
+  }
   [[nodiscard]] virtual bool isHlsStreaming() const {
     return false;
   }
-  /// Total PCM frame count when known (e.g. WAV); 0 when unavailable.
+  /// Total PCM frame count when known; 0 when unavailable.
   [[nodiscard]] virtual size_t getTotalPcmFrameCount() const {
-    return 0;
+    return totalPcmFrames_;
   }
+
+ protected:
+  void resetOpenMetadata() {
+    outputChannels_ = 0;
+    outputSampleRate_ = 0;
+    framePosition_ = 0;
+    totalPcmFrames_ = 0;
+  }
+
+  /// Cache length from a duration in seconds (no-op when rate/duration invalid).
+  void setTotalPcmFramesFromDuration(double durationSeconds) {
+    if (durationSeconds > 0.0 && outputSampleRate_ > 0) {
+      totalPcmFrames_ =
+          static_cast<size_t>(durationSeconds * static_cast<double>(outputSampleRate_));
+    } else {
+      totalPcmFrames_ = 0;
+    }
+  }
+
+  int outputChannels_ = 0;
+  int outputSampleRate_ = 0;
+  int64_t framePosition_ = 0;
+  size_t totalPcmFrames_ = 0;
 };
 
 } // namespace audioapi::decoding
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp
index 61a0f962c..2ecbfbbb7 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.cpp
@@ -134,9 +134,7 @@ void FfmpegDecoder::close() {
   leftover_.clear();
   leftover_offset_ = 0;
   audio_stream_index_ = -1;
-  output_channels_ = 0;
-  output_sample_rate_ = 0;
-  total_output_frames_ = 0;
+  resetOpenMetadata();
   is_hls_streaming_ = false;
 }
 
@@ -155,9 +153,9 @@ decoding::DecoderResult FfmpegDecoder::setupSwr() {
   av_opt_set_sample_fmt(swr_, "in_sample_fmt", codec_ctx_->sample_fmt, 0);
 
   AVChannelLayout out_layout;
-  av_channel_layout_default(&out_layout, output_channels_);
+  av_channel_layout_default(&out_layout, outputChannels_);
   av_opt_set_chlayout(swr_, "out_chlayout", &out_layout, 0);
-  av_opt_set_int(swr_, "out_sample_rate", output_sample_rate_, 0);
+  av_opt_set_int(swr_, "out_sample_rate", outputSampleRate_, 0);
   av_opt_set_sample_fmt(swr_, "out_sample_fmt", AV_SAMPLE_FMT_FLT, 0);
   const int swrInitResult = swr_init(swr_);
   if (swrInitResult < 0) {
@@ -170,7 +168,7 @@ decoding::DecoderResult FfmpegDecoder::setupSwr() {
   const int allocResult = av_samples_alloc_array_and_samples(
       &resampled_data_,
       nullptr,
-      output_channels_,
+      outputChannels_,
       decoding::AudioDecoderBackend::CHUNK_SIZE,
       AV_SAMPLE_FMT_FLT,
       0);
@@ -201,8 +199,8 @@ decoding::DecoderResult FfmpegDecoder::initializeDecodedStreams(
     fmt_ctx_ = nullptr;
     return codecResult;
   }
-  output_channels_ = codec_ctx_->ch_layout.nb_channels;
-  output_sample_rate_ = (outputSampleRate > 0) ? outputSampleRate : codec_ctx_->sample_rate;
+  outputChannels_ = codec_ctx_->ch_layout.nb_channels;
+  outputSampleRate_ = (outputSampleRate > 0) ? outputSampleRate : codec_ctx_->sample_rate;
 
   packet_ = av_packet_alloc();
   frame_ = av_frame_alloc();
@@ -219,23 +217,45 @@ decoding::DecoderResult FfmpegDecoder::initializeDecodedStreams(
     close();
     return swrResult;
   }
-  total_output_frames_ = 0;
+  framePosition_ = 0;
+  cacheDurationFromContainer();
   return Ok(None);
 }
 
-decoding::DecoderResult FfmpegDecoder::open(const decoding::LocalFileSource &source) {
-  close();
-  if (source.path.empty()) {
-    return Err("FfmpegDecoder::open failed: path is empty");
+void FfmpegDecoder::cacheDurationFromContainer() {
+  if (fmt_ctx_ == nullptr || audio_stream_index_ < 0) {
+    totalPcmFrames_ = 0;
+    return;
   }
-  const int openInputResult = avformat_open_input(&fmt_ctx_, source.path.c_str(), nullptr, nullptr);
-  if (openInputResult < 0) {
-    fmt_ctx_ = nullptr;
-    return Err(
-        "FfmpegDecoder::open failed: avformat_open_input failed: " +
-        parseFFmpegError(openInputResult));
+  AVStream *st = fmt_ctx_->streams[audio_stream_index_];
+  if (st == nullptr) {
+    totalPcmFrames_ = 0;
+    return;
   }
-  return initializeDecodedStreams(source.sampleRate, "FfmpegDecoder::open");
+
+  auto validSeconds = [](double s) -> bool {
+    return s > 0 && std::isfinite(s);
+  };
+
+  // Prefer per-stream duration (e.g. MP4 mdhd) — often exact vs container-level
+  // guesses that trigger AAC “bitrate duration” warnings.
+  if (st->duration != AV_NOPTS_VALUE && st->duration > 0) {
+    double t = static_cast<double>(st->duration) * av_q2d(st->time_base);
+    if (validSeconds(t)) {
+      setTotalPcmFramesFromDuration(t);
+      return;
+    }
+  }
+
+  if (fmt_ctx_->duration != AV_NOPTS_VALUE && fmt_ctx_->duration >= 0) {
+    double t = static_cast<double>(fmt_ctx_->duration) / static_cast<double>(AV_TIME_BASE);
+    if (validSeconds(t)) {
+      setTotalPcmFramesFromDuration(t);
+      return;
+    }
+  }
+
+  totalPcmFrames_ = 0;
 }
 
 decoding::DecoderResult FfmpegDecoder::open(const decoding::RemoteUrlSource &source) {
@@ -272,7 +292,7 @@ void FfmpegDecoder::appendFrameResampled(AVFrame *frame) {
     if (av_samples_alloc_array_and_samples(
             &resampled_data_,
             nullptr,
-            output_channels_,
+            outputChannels_,
             max_resampled_samples_,
             AV_SAMPLE_FMT_FLT,
             0) < 0) {
@@ -286,7 +306,7 @@ void FfmpegDecoder::appendFrameResampled(AVFrame *frame) {
       const_cast<const uint8_t **>(frame->data),
       frame->nb_samples);
   if (converted > 0) {
-    size_t n = static_cast<size_t>(converted) * static_cast<size_t>(output_channels_);
+    size_t n = static_cast<size_t>(converted) * static_cast<size_t>(outputChannels_);
     const float *src = reinterpret_cast<float *>(resampled_data_[0]);
     leftover_.insert(leftover_.end(), src, src + n);
   }
@@ -353,49 +373,10 @@ decoding::DecoderResult FfmpegDecoder::feedPipeline() {
   }
 }
 
-float FfmpegDecoder::getDurationInSeconds() const {
-  if (!isOpen() || fmt_ctx_ == nullptr || audio_stream_index_ < 0) {
-    return 0;
-  }
-  AVStream *st = fmt_ctx_->streams[audio_stream_index_];
-  if (st == nullptr) {
-    return 0;
-  }
-
-  auto validSeconds = [](double s) -> bool {
-    return s > 0 && std::isfinite(s);
-  };
-
-  // Prefer per-stream duration (e.g. MP4 mdhd) — often exact vs container-level
-  // guesses that trigger AAC “bitrate duration” warnings.
-  if (st->duration != AV_NOPTS_VALUE && st->duration > 0) {
-    double t = static_cast<double>(st->duration) * av_q2d(st->time_base);
-    if (validSeconds(t)) {
-      return static_cast<float>(t);
-    }
-  }
-
-  if (fmt_ctx_->duration != AV_NOPTS_VALUE && fmt_ctx_->duration >= 0) {
-    double t = static_cast<double>(fmt_ctx_->duration) / static_cast<double>(AV_TIME_BASE);
-    if (validSeconds(t)) {
-      return static_cast<float>(t);
-    }
-  }
-
-  return 0;
-}
-
-float FfmpegDecoder::getCurrentPositionInSeconds() const {
-  if (!isOpen() || output_sample_rate_ <= 0) {
-    return 0;
-  }
-  return static_cast<float>(total_output_frames_) / static_cast<float>(output_sample_rate_);
-}
-
 // todo: offload this call to a separate thread because seeking decoder can take a while
 // current implementation suspends audio thread, which disable multiple playbacks
 decoding::DecoderResult FfmpegDecoder::seekToTime(double seconds) {
-  if (!isOpen() || audio_stream_index_ < 0 || output_sample_rate_ <= 0) {
+  if (!isOpen() || audio_stream_index_ < 0 || outputSampleRate_ <= 0) {
     return Err("FfmpegDecoder::seekToTime failed: decoder is not open");
   }
   float dur = getDurationInSeconds();
@@ -418,17 +399,17 @@ decoding::DecoderResult FfmpegDecoder::seekToTime(double seconds) {
   avcodec_flush_buffers(codec_ctx_);
   leftover_.clear();
   leftover_offset_ = 0;
-  total_output_frames_ =
-      static_cast<size_t>(std::llround(seconds * static_cast<double>(output_sample_rate_)));
+  framePosition_ =
+      static_cast<int64_t>(std::llround(seconds * static_cast<double>(outputSampleRate_)));
   return Ok(None);
 }
 
 size_t FfmpegDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
-  if (!isOpen() || outInterleaved == nullptr || frameCount == 0 || output_channels_ <= 0) {
+  if (!isOpen() || outInterleaved == nullptr || frameCount == 0 || outputChannels_ <= 0) {
     return 0;
   }
   size_t delivered = 0;
-  const auto ch = static_cast<size_t>(output_channels_);
+  const auto ch = static_cast<size_t>(outputChannels_);
 
   while (delivered < frameCount) {
     size_t need = frameCount - delivered;
@@ -452,18 +433,10 @@ size_t FfmpegDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
       break;
     }
   }
-  total_output_frames_ += delivered;
+  framePosition_ += static_cast<int64_t>(delivered);
   return delivered;
 }
 
-size_t FfmpegDecoder::getTotalPcmFrameCount() const {
-  const float duration = getDurationInSeconds();
-  if (duration <= 0.0f || output_sample_rate_ <= 0) {
-    return 0;
-  }
-  return static_cast<size_t>(duration * static_cast<float>(output_sample_rate_));
-}
-
 } // namespace audioapi::decoding::ffmpeg
 
 #else
@@ -471,27 +444,15 @@ size_t FfmpegDecoder::getTotalPcmFrameCount() const {
 namespace audioapi::decoding::ffmpeg {
 FfmpegDecoder::~FfmpegDecoder() = default;
 void FfmpegDecoder::close() {}
-decoding::DecoderResult FfmpegDecoder::open(const decoding::LocalFileSource &) {
-  return Err("FFmpeg is disabled");
-}
 decoding::DecoderResult FfmpegDecoder::open(const decoding::RemoteUrlSource &) {
   return Err("FFmpeg is disabled");
 }
-float FfmpegDecoder::getDurationInSeconds() const {
-  return 0;
-}
-float FfmpegDecoder::getCurrentPositionInSeconds() const {
-  return 0;
-}
 decoding::DecoderResult FfmpegDecoder::seekToTime(double) {
   return Err("FFmpeg is disabled");
 }
 size_t FfmpegDecoder::readPcmFrames(float *, size_t) {
   return 0;
 }
-size_t FfmpegDecoder::getTotalPcmFrameCount() const {
-  return 0;
-}
 
 } // namespace audioapi::decoding::ffmpeg
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.h
index 94a814a23..58116aa98 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/FfmpegDecoder.h
@@ -16,7 +16,7 @@ extern "C" {
 namespace audioapi::decoding::ffmpeg {
 
 /**
- * FFmpeg decoder for remote HTTP(S) / HLS and local HLS playlists.
+ * FFmpeg decoder for remote HTTP(S) / HLS sources that need network handling.
  *
  * Usage: open via DecoderFactory → readPcmFrames repeatedly → close.
  */
@@ -26,7 +26,6 @@ class FfmpegDecoder : public AudioDecoderBackend {
   ~FfmpegDecoder() override;
   DELETE_COPY_AND_MOVE(FfmpegDecoder);
 
-  [[nodiscard]] DecoderResult open(const LocalFileSource &source);
   [[nodiscard]] DecoderResult open(const RemoteUrlSource &source);
 
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
@@ -36,23 +35,12 @@ class FfmpegDecoder : public AudioDecoderBackend {
   [[nodiscard]] bool isOpen() const override {
     return fmt_ctx_ != nullptr && codec_ctx_ != nullptr;
   }
-  [[nodiscard]] int outputChannels() const override {
-    return output_channels_;
-  }
-  [[nodiscard]] int outputSampleRate() const override {
-    return output_sample_rate_;
-  }
 
   [[nodiscard]] bool isHlsStreaming() const override {
     return is_hls_streaming_;
   }
 
-  [[nodiscard]] float getDurationInSeconds() const override;
-
-  [[nodiscard]] float getCurrentPositionInSeconds() const override;
-
   [[nodiscard]] DecoderResult seekToTime(double seconds) override;
-  [[nodiscard]] size_t getTotalPcmFrameCount() const override;
 
  private:
   [[nodiscard]] DecoderResult initializeDecodedStreams(
@@ -63,6 +51,7 @@ class FfmpegDecoder : public AudioDecoderBackend {
   [[nodiscard]] DecoderResult feedPipeline();
   void appendFrameResampled(AVFrame *frame);
   void detectHlsStreamingMode();
+  void cacheDurationFromContainer();
 
   bool is_hls_streaming_ = false;
 
@@ -78,9 +67,6 @@ class FfmpegDecoder : public AudioDecoderBackend {
   std::vector<float> leftover_;
   size_t leftover_offset_ = 0;
   int audio_stream_index_ = -1;
-  int output_channels_ = 0;
-  int output_sample_rate_ = 0;
-  size_t total_output_frames_ = 0;
 };
 
 } // namespace audioapi::decoding::ffmpeg
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.cpp
index c703d547b..3488b4442 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.cpp
@@ -54,10 +54,7 @@ void MiniAudioDecoder::teardownDecoder() {
     decoder_.reset();
   }
   memoryCopy_.clear();
-  outputChannels_ = 0;
-  outputSampleRate_ = 0;
-  totalOutputFrames_ = 0;
-  totalLengthFrames_ = 0;
+  resetOpenMetadata();
 }
 
 void MiniAudioDecoder::close() {
@@ -68,30 +65,6 @@ bool MiniAudioDecoder::isOpen() const {
   return decoder_ != nullptr;
 }
 
-int MiniAudioDecoder::outputChannels() const {
-  return outputChannels_;
-}
-
-int MiniAudioDecoder::outputSampleRate() const {
-  return outputSampleRate_;
-}
-
-float MiniAudioDecoder::getDurationInSeconds() const {
-  if (!isOpen() || outputSampleRate_ <= 0 || totalLengthFrames_ == 0) {
-    return 0;
-  }
-  return static_cast<float>(
-      static_cast<double>(totalLengthFrames_) / static_cast<double>(outputSampleRate_));
-}
-
-float MiniAudioDecoder::getCurrentPositionInSeconds() const {
-  if (!isOpen() || outputSampleRate_ <= 0) {
-    return 0;
-  }
-  return static_cast<float>(
-      static_cast<double>(totalOutputFrames_) / static_cast<double>(outputSampleRate_));
-}
-
 DecoderResult MiniAudioDecoder::open(const LocalFileSource &source) {
   close();
   if (source.path.empty()) {
@@ -111,11 +84,11 @@ DecoderResult MiniAudioDecoder::open(const LocalFileSource &source) {
 
   ma_uint64 length = 0;
   if (ma_decoder_get_length_in_pcm_frames(decoder_.get(), &length) == MA_SUCCESS) {
-    totalLengthFrames_ = static_cast<std::uint64_t>(length);
+    totalPcmFrames_ = static_cast<size_t>(length);
   } else {
-    totalLengthFrames_ = 0;
+    totalPcmFrames_ = 0;
   }
-  totalOutputFrames_ = 0;
+  framePosition_ = 0;
   return Ok(None);
 }
 
@@ -140,18 +113,14 @@ DecoderResult MiniAudioDecoder::open(const EncodedMemorySource &source) {
 
   ma_uint64 length = 0;
   if (ma_decoder_get_length_in_pcm_frames(decoder_.get(), &length) == MA_SUCCESS) {
-    totalLengthFrames_ = static_cast<std::uint64_t>(length);
+    totalPcmFrames_ = static_cast<size_t>(length);
   } else {
-    totalLengthFrames_ = 0;
+    totalPcmFrames_ = 0;
   }
-  totalOutputFrames_ = 0;
+  framePosition_ = 0;
   return Ok(None);
 }
 
-size_t MiniAudioDecoder::getTotalPcmFrameCount() const {
-  return static_cast<size_t>(totalLengthFrames_);
-}
-
 size_t MiniAudioDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
   if (!isOpen() || outInterleaved == nullptr || frameCount == 0 || outputChannels_ <= 0) {
     return 0;
@@ -159,7 +128,7 @@ size_t MiniAudioDecoder::readPcmFrames(float *outInterleaved, size_t frameCount)
   ma_uint64 framesRead = 0;
   ma_decoder_read_pcm_frames(
       decoder_.get(), outInterleaved, static_cast<ma_uint64>(frameCount), &framesRead);
-  totalOutputFrames_ += static_cast<size_t>(framesRead);
+  framePosition_ += static_cast<int64_t>(framesRead);
   return static_cast<size_t>(framesRead);
 }
 
@@ -183,7 +152,7 @@ DecoderResult MiniAudioDecoder::seekToTime(double seconds) {
   if (result != MA_SUCCESS) {
     return Err("MiniAudioDecoder::seekToTime failed: " + parseMiniAudioError(result));
   }
-  totalOutputFrames_ = static_cast<size_t>(frame);
+  framePosition_ = static_cast<int64_t>(frame);
   return Ok(None);
 }
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.h
index 4810722ee..4db3041f1 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/MiniAudioDecoder.h
@@ -13,7 +13,7 @@
 namespace audioapi::decoding::miniaudio {
 
 /**
- * MiniAudio-backed incremental decoder (Vorbis/Opus/WAV, etc. via ma_decoder + custom backends).
+ * MiniAudio-backed incremental decoder (Vorbis/Ogg via libvorbis custom backend).
  * Local file / memory only — remote URLs use FfmpegDecoder.
  */
 class MiniAudioDecoder : public AudioDecoderBackend {
@@ -28,22 +28,13 @@ class MiniAudioDecoder : public AudioDecoderBackend {
   [[nodiscard]] size_t readPcmFrames(float *outInterleaved, size_t frameCount) override;
   void close() override;
   [[nodiscard]] bool isOpen() const override;
-  [[nodiscard]] int outputChannels() const override;
-  [[nodiscard]] int outputSampleRate() const override;
-  [[nodiscard]] float getDurationInSeconds() const override;
-  [[nodiscard]] float getCurrentPositionInSeconds() const override;
   [[nodiscard]] DecoderResult seekToTime(double seconds) override;
-  [[nodiscard]] size_t getTotalPcmFrameCount() const override;
 
  private:
   void teardownDecoder();
 
   std::unique_ptr<ma_decoder> decoder_;
   std::vector<uint8_t> memoryCopy_;
-  int outputChannels_ = 0;
-  int outputSampleRate_ = 0;
-  size_t totalOutputFrames_ = 0;
-  std::uint64_t totalLengthFrames_ = 0;
 };
 
 } // namespace audioapi::decoding::miniaudio
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/OsDecoderBase.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/OsDecoderBase.h
index c282b2f80..1aa1b71ba 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/OsDecoderBase.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/OsDecoderBase.h
@@ -3,14 +3,12 @@
 #include <audioapi/decoding/backends/AudioDecoderBackend.h>
 #include <audioapi/utils/Macros.h>
 
-#include <cstdint>
-
 namespace audioapi::decoding {
 
 /**
- * Shared open-state for OS-native incremental decoders (iOS / Android).
+ * Shared open/close for OS-native incremental decoders (iOS / Android).
  *
- * Owns the common metadata reset by `close()`; subclasses release platform
+ * Metadata lives on `AudioDecoderBackend`; subclasses release platform
  * resources in `releaseImpl()` (e.g. `impl_.reset()`).
  */
 class OsDecoderBase : public AudioDecoderBackend {
@@ -21,10 +19,7 @@ class OsDecoderBase : public AudioDecoderBackend {
 
   void close() final {
     releaseImpl();
-    outputChannels_ = 0;
-    outputSampleRate_ = 0;
-    durationSeconds_ = 0.0;
-    framePosition_ = 0;
+    resetOpenMetadata();
     open_ = false;
   }
 
@@ -32,41 +27,10 @@ class OsDecoderBase : public AudioDecoderBackend {
     return open_;
   }
 
-  [[nodiscard]] int outputChannels() const final {
-    return outputChannels_;
-  }
-
-  [[nodiscard]] int outputSampleRate() const final {
-    return outputSampleRate_;
-  }
-
-  [[nodiscard]] float getDurationInSeconds() const final {
-    return static_cast<float>(durationSeconds_);
-  }
-
-  [[nodiscard]] float getCurrentPositionInSeconds() const final {
-    if (outputSampleRate_ <= 0) {
-      return 0.0f;
-    }
-    return static_cast<float>(
-        static_cast<double>(framePosition_) / static_cast<double>(outputSampleRate_));
-  }
-
-  [[nodiscard]] size_t getTotalPcmFrameCount() const override {
-    if (outputSampleRate_ <= 0 || durationSeconds_ <= 0.0) {
-      return 0;
-    }
-    return static_cast<size_t>(durationSeconds_ * static_cast<double>(outputSampleRate_));
-  }
-
  protected:
   /// Drop platform-native decoder resources (ExtAudioFile / MediaCodec, etc.).
   virtual void releaseImpl() = 0;
 
-  int outputChannels_ = 0;
-  int outputSampleRate_ = 0;
-  double durationSeconds_ = 0.0;
-  int64_t framePosition_ = 0;
   bool open_ = false;
 };
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
index cf84719c1..495a0f16e 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
@@ -57,6 +57,7 @@ DecoderResult RawPcmDecoder::openFromBytes(
   outputChannels_ = channelCount;
   outputSampleRate_ = sampleRate;
   framePosition_ = 0;
+  totalPcmFrames_ = numFrames;
   return Ok(None);
 }
 
@@ -84,19 +85,19 @@ size_t RawPcmDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
     return 0;
   }
 
-  const size_t totalFrames = interleavedPcm_.size() / static_cast<size_t>(outputChannels_);
-  if (framePosition_ >= totalFrames) {
+  if (framePosition_ < 0 || static_cast<size_t>(framePosition_) >= totalPcmFrames_) {
     return 0;
   }
 
-  const size_t framesToRead = std::min(frameCount, totalFrames - framePosition_);
+  const size_t framesToRead =
+      std::min(frameCount, totalPcmFrames_ - static_cast<size_t>(framePosition_));
   const auto channelCount = static_cast<size_t>(outputChannels_);
-  const size_t srcOffset = framePosition_ * channelCount;
+  const size_t srcOffset = static_cast<size_t>(framePosition_) * channelCount;
   std::copy_n(
       interleavedPcm_.begin() + static_cast<std::ptrdiff_t>(srcOffset),
       framesToRead * channelCount,
       outInterleaved);
-  framePosition_ += framesToRead;
+  framePosition_ += static_cast<int64_t>(framesToRead);
   return framesToRead;
 }
 
@@ -116,52 +117,18 @@ DecoderResult RawPcmDecoder::seekToTime(double seconds) {
   }
 
   framePosition_ =
-      static_cast<size_t>(std::llround(seconds * static_cast<double>(outputSampleRate_)));
-  const size_t totalFrames = getTotalPcmFrameCount();
-  framePosition_ = std::min(framePosition_, totalFrames);
+      static_cast<int64_t>(std::llround(seconds * static_cast<double>(outputSampleRate_)));
+  framePosition_ = std::min(framePosition_, static_cast<int64_t>(totalPcmFrames_));
   return Ok(None);
 }
 
 void RawPcmDecoder::close() {
   interleavedPcm_.clear();
-  framePosition_ = 0;
-  outputChannels_ = 0;
-  outputSampleRate_ = 0;
+  resetOpenMetadata();
 }
 
 bool RawPcmDecoder::isOpen() const {
   return !interleavedPcm_.empty() && outputChannels_ > 0 && outputSampleRate_ > 0;
 }
 
-int RawPcmDecoder::outputChannels() const {
-  return outputChannels_;
-}
-
-int RawPcmDecoder::outputSampleRate() const {
-  return outputSampleRate_;
-}
-
-float RawPcmDecoder::getDurationInSeconds() const {
-  if (!isOpen()) {
-    return 0.0f;
-  }
-  return static_cast<float>(
-      static_cast<double>(getTotalPcmFrameCount()) / static_cast<double>(outputSampleRate_));
-}
-
-float RawPcmDecoder::getCurrentPositionInSeconds() const {
-  if (!isOpen() || outputSampleRate_ <= 0) {
-    return 0.0f;
-  }
-  return static_cast<float>(
-      static_cast<double>(framePosition_) / static_cast<double>(outputSampleRate_));
-}
-
-size_t RawPcmDecoder::getTotalPcmFrameCount() const {
-  if (!isOpen() || outputChannels_ <= 0) {
-    return 0;
-  }
-  return interleavedPcm_.size() / static_cast<size_t>(outputChannels_);
-}
-
 } // namespace audioapi::decoding::raw_pcm
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.h b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.h
index 464fed78a..d30065f81 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.h
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.h
@@ -5,6 +5,7 @@
 #include <audioapi/utils/Macros.h>
 
 #include <cstddef>
+#include <cstdint>
 #include <vector>
 
 namespace audioapi::decoding::raw_pcm {
@@ -22,11 +23,6 @@ class RawPcmDecoder : public AudioDecoderBackend {
   [[nodiscard]] DecoderResult seekToTime(double seconds) override;
   void close() override;
   [[nodiscard]] bool isOpen() const override;
-  [[nodiscard]] int outputChannels() const override;
-  [[nodiscard]] int outputSampleRate() const override;
-  [[nodiscard]] float getDurationInSeconds() const override;
-  [[nodiscard]] float getCurrentPositionInSeconds() const override;
-  [[nodiscard]] size_t getTotalPcmFrameCount() const override;
 
  private:
   [[nodiscard]] DecoderResult openFromBytes(
@@ -37,9 +33,6 @@ class RawPcmDecoder : public AudioDecoderBackend {
       bool interleaved);
 
   std::vector<float> interleavedPcm_;
-  size_t framePosition_ = 0;
-  int outputChannels_ = 0;
-  int outputSampleRate_ = 0;
 };
 
 } // namespace audioapi::decoding::raw_pcm
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/utils/MiniaudioImplementation.cpp b/packages/react-native-audio-api/common/cpp/audioapi/utils/MiniaudioImplementation.cpp
index 088d3f5d1..5c4592b96 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/utils/MiniaudioImplementation.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/utils/MiniaudioImplementation.cpp
@@ -4,4 +4,15 @@
 /// This make its safe to include the header file in multiple places, without causing multiple definition errors.
 #define MINIAUDIO_IMPLEMENTATION
 #define MA_DEBUG_OUTPUT
+
+// MiniAudio is used for Vorbis/Ogg decoding (custom libvorbis backend) and WAV encoding
+// (`ma_encoder` only supports WAV). OS decoder covers WAV/MP3/FLAC decode.
+#define MA_NO_MP3
+#define MA_NO_FLAC
+#define MA_NO_DEVICE_IO
+#define MA_NO_RESOURCE_MANAGER
+#define MA_NO_NODE_GRAPH
+#define MA_NO_ENGINE
+#define MA_NO_GENERATION
+
 #include <audioapi/libs/miniaudio/miniaudio.h>
diff --git a/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp b/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
index 9c183af9c..2113ecf53 100644
--- a/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
+++ b/packages/react-native-audio-api/common/cpp/test/src/decoding/DecoderFactoryTest.cpp
@@ -103,11 +103,11 @@ TEST(DecoderFactoryTest, RejectsRemoteUrlWhenFfmpegDisabled) {
   EXPECT_EQ(result.unwrap_err(), "FFmpeg is disabled, cannot decode remote URL");
 }
 
-TEST(DecoderFactoryTest, RejectsLocalM3u8WhenFfmpegDisabled) {
+TEST(DecoderFactoryTest, RejectsUnsupportedLocalFile) {
   auto result = decoding::createDecoder(
       decoding::LocalFileSource{.path = "/tmp/playlist.m3u8", .sampleRate = 0});
   EXPECT_TRUE(result.is_err());
-  EXPECT_EQ(result.unwrap_err(), "FFmpeg is disabled, cannot decode local HLS (.m3u8) playlists");
+  EXPECT_EQ(result.unwrap_err(), "Cannot open local file: unsupported or invalid audio format");
 }
 
 TEST(DecoderFactoryTest, OpensRawPcmSource) {
diff --git a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
index d23e2ab49..b1e208fb2 100644
--- a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
+++ b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
@@ -214,12 +214,13 @@ SInt64 memoryGetSizeProc(void *inClientData)
 
     auto state = std::make_unique<IosDecoderState>();
     state->extFile.reset(extFile);
+    double durationSeconds = 0.0;
     auto configured = configureExtAudioFile(
         state->extFile.get(),
         source.sampleRate,
         outputChannels_,
         outputSampleRate_,
-        durationSeconds_,
+        durationSeconds,
         state->fileSampleRate);
     if (configured.is_err()) {
       return configured;
@@ -227,6 +228,7 @@ SInt64 memoryGetSizeProc(void *inClientData)
 
     impl_ = std::move(state);
     framePosition_ = 0;
+    setTotalPcmFramesFromDuration(durationSeconds);
     open_ = true;
     return Ok(None);
   }
@@ -279,12 +281,13 @@ SInt64 memoryGetSizeProc(void *inClientData)
   }
   state->extFile.reset(extFile);
 
+  double durationSeconds = 0.0;
   auto configured = configureExtAudioFile(
       state->extFile.get(),
       source.sampleRate,
       outputChannels_,
       outputSampleRate_,
-      durationSeconds_,
+      durationSeconds,
       state->fileSampleRate);
   if (configured.is_err()) {
     return configured;
@@ -292,6 +295,7 @@ SInt64 memoryGetSizeProc(void *inClientData)
 
   impl_ = std::move(state);
   framePosition_ = 0;
+  setTotalPcmFramesFromDuration(durationSeconds);
   open_ = true;
   return Ok(None);
 }

From e1f8283fb5f9aa50aa8c8b6ed58d506e2f0b255f Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Thu, 23 Jul 2026 14:03:12 +0200
Subject: [PATCH 07/12] fix: android build

---
 .../android/src/main/cpp/audioapi/android/AndroidDecoding.cpp | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
index 8b3444125..af4108736 100644
--- a/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
@@ -476,8 +476,8 @@ decoding::DecoderResult AndroidDecoder::open(const decoding::LocalFileSource &so
 
   outputChannels_ = state->channels;
   outputSampleRate_ = state->outputRate;
-  durationSeconds_ = state->durationSeconds;
   framePosition_ = 0;
+  setTotalPcmFramesFromDuration(state->durationSeconds);
   impl_ = std::move(state);
   open_ = true;
   return Ok(None);
@@ -502,8 +502,8 @@ decoding::DecoderResult AndroidDecoder::open(const decoding::EncodedMemorySource
 
   outputChannels_ = state->channels;
   outputSampleRate_ = state->outputRate;
-  durationSeconds_ = state->durationSeconds;
   framePosition_ = 0;
+  setTotalPcmFramesFromDuration(state->durationSeconds);
   impl_ = std::move(state);
   open_ = true;
   return Ok(None);

From e4cbcf6f91c5d6f72b7515d1f935dea867f4f272 Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Thu, 23 Jul 2026 14:06:18 +0200
Subject: [PATCH 08/12] refactor: moved types conversions to shared utils

---
 .claude/skills/utilities/SKILL.md                     |  2 +-
 .../cpp/audioapi/decoding/backends/RawPcmDecoder.cpp  | 11 ++---------
 .../common/cpp/audioapi/dsp/AudioUtils.hpp            |  7 +++++++
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/.claude/skills/utilities/SKILL.md b/.claude/skills/utilities/SKILL.md
index 653c1698a..ab96877dd 100644
--- a/.claude/skills/utilities/SKILL.md
+++ b/.claude/skills/utilities/SKILL.md
@@ -213,7 +213,7 @@ RAII mutex wrapper that can hold `nullptr` (no-op). Supports `Locker::tryLock(mu
 
 ### `AudioUtils.hpp` — inline DSP math
 
-Provides `timeToSampleFrame()`, `sampleFrameToTime()`, `linearInterpolate()`, `linearToDecibels()`, `decibelsToLinear()`.
+Provides `timeToSampleFrame()`, `sampleFrameToTime()`, `linearInterpolate()`, `linearToDecibels()`, `decibelsToLinear()`, `uint8ToFloat()` (LE int16 bytes → float).
 
 For full API see [api.md](api.md#audioutilshpp--inline-dsp-math).
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
index 495a0f16e..c8b630ef3 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
@@ -1,4 +1,5 @@
 #include <audioapi/decoding/backends/RawPcmDecoder.h>
+#include <audioapi/dsp/AudioUtils.hpp>
 #include <audioapi/libs/base64/base64.h>
 
 #include <algorithm>
@@ -6,14 +7,6 @@
 #include <cstdint>
 
 namespace audioapi::decoding::raw_pcm {
-namespace {
-
-float uint8ToFloat(uint8_t byte1, uint8_t byte2) {
-  return static_cast<float>(static_cast<int16_t>((byte2 << 8) | byte1)) /
-      static_cast<float>(INT16_MAX);
-}
-
-} // namespace
 
 DecoderResult RawPcmDecoder::openFromBytes(
     const uint8_t *data,
@@ -50,7 +43,7 @@ DecoderResult RawPcmDecoder::openFromBytes(
         offset = (static_cast<size_t>(ch) * numFrames + i) * sizeof(int16_t);
       }
       interleavedPcm_[i * static_cast<size_t>(channelCount) + static_cast<size_t>(ch)] =
-          uint8ToFloat(data[offset], data[offset + 1]);
+          dsp::uint8ToFloat(data[offset], data[offset + 1]);
     }
   }
 
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/dsp/AudioUtils.hpp b/packages/react-native-audio-api/common/cpp/audioapi/dsp/AudioUtils.hpp
index af2b27e12..272cfd0d0 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/dsp/AudioUtils.hpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/dsp/AudioUtils.hpp
@@ -2,6 +2,7 @@
 
 #include <cmath>
 #include <cstddef>
+#include <cstdint>
 #include <span>
 
 namespace audioapi::dsp {
@@ -14,6 +15,12 @@ namespace audioapi::dsp {
   return static_cast<double>(sampleFrame) / sampleRate;
 }
 
+/// Convert little-endian int16 sample bytes to float in [-1, 1].
+[[nodiscard]] inline float uint8ToFloat(uint8_t byte1, uint8_t byte2) {
+  return static_cast<float>(static_cast<int16_t>((byte2 << 8) | byte1)) /
+      static_cast<float>(INT16_MAX);
+}
+
 // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables) -- function, not variable
 [[nodiscard]] inline float linearInterpolate(
     std::span<const float> source,

From a1a20f9a04c8e95fc417820beba393bf1d3f0222 Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Thu, 23 Jul 2026 14:08:31 +0200
Subject: [PATCH 09/12] chore: podfile.lock

---
 apps/fabric-example/ios/Podfile.lock | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/fabric-example/ios/Podfile.lock b/apps/fabric-example/ios/Podfile.lock
index 613b233a4..c448242eb 100644
--- a/apps/fabric-example/ios/Podfile.lock
+++ b/apps/fabric-example/ios/Podfile.lock
@@ -2597,7 +2597,7 @@ SPEC CHECKSUMS:
   ReactCodegen: d07ee3c8db75b43d1cbe479ae6affebf9925c733
   ReactCommon: fe2a3af8975e63efa60f95fca8c34dc85deee360
   ReactNativeDependencies: 4d5ce2683b6d74f7c686bf90a88c7d381295cf3c
-  RNAudioAPI: 8a7e83b96d9be33bad7591400bb21c6e8b119222
+  RNAudioAPI: 50957b72cc742b9aa1e05349be71b9db73c9cf74
   RNAudioWorklets: febe470be646585d9b8b0de320a5fb8684cb012c
   RNGestureHandler: 187c5c7936abf427bc4d22d6c3b1ac80ad1f63c0
   RNReanimated: 3a204af3747842859392545d41d443b9c5e428a3

From 8d249097f5815abb1ffde6aba7fa2bdeb954c896 Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Thu, 30 Jul 2026 11:49:15 +0200
Subject: [PATCH 10/12] refactor: remove clangd file

---
 packages/react-native-audio-api/.clangd | 24 ------------------------
 1 file changed, 24 deletions(-)

diff --git a/packages/react-native-audio-api/.clangd b/packages/react-native-audio-api/.clangd
index c28e3d1f5..e735c6397 100644
--- a/packages/react-native-audio-api/.clangd
+++ b/packages/react-native-audio-api/.clangd
@@ -9,27 +9,3 @@ CompileFlags:
 Diagnostics:
   ClangTidy:
     FastCheckFilter: Loose
-
-# Android: prefer the NDK compile database from a local Gradle/CMake configure.
-# Run common/cpp/clangd/setup-platform-headers.sh after changing NDK / SDK paths.
----
-If:
-  PathMatch: .*/android/.*\.(c|cc|cpp|cxx|h|hh|hpp|hxx)$
-CompileFlags:
-  CompilationDatabase: android/.cxx/tools/debug/arm64-v8a
-
-# iOS / ObjC++: iPhoneOS SDK (unversioned Xcode symlink) so system frameworks resolve.
----
-If:
-  PathMatch: .*/ios/.*\.(c|cc|cpp|cxx|h|hh|hpp|hxx|m|mm)$
-CompileFlags:
-  Add:
-    - -xobjective-c++
-    - -std=c++20
-    - -fobjc-arc
-    - --target=arm64-apple-ios15.0
-    - -isysroot
-    - /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk
-    - -F/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/System/Library/Frameworks
-    - -Icommon/cpp
-    - -Iios

From 186031032c611cf3ff0a6e63932b148969791a64 Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Tue, 11 Aug 2026 13:41:42 +0200
Subject: [PATCH 11/12] feat: memory reorder and includes

---
 .claude/settings.json                         |  8 +--
 .../cpp/audioapi/android/AndroidDecoding.cpp  | 67 ++++++++++++-------
 .../decoding/backends/RawPcmDecoder.cpp       |  2 +-
 .../audioapi/ios/core/utils/IOSDecoding.mm    |  8 ++-
 4 files changed, 51 insertions(+), 34 deletions(-)

diff --git a/.claude/settings.json b/.claude/settings.json
index 78963d682..509b1607e 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -32,10 +32,10 @@
 
       "Read(**)",
 
-      "WebFetch(https://webaudio.github.io/*)",
-      "WebFetch(https://developer.mozilla.org/*)",
-      "WebFetch(https://en.cppreference.com/*)",
-      "WebFetch(https://reactnative.dev/*)",
+      "WebFetch(domain:webaudio.github.io)",
+      "WebFetch(domain:developer.mozilla.org)",
+      "WebFetch(domain:en.cppreference.com)",
+      "WebFetch(domain:reactnative.dev)",
       "WebSearch(*)",
 
       "Write(.claude/**)",
diff --git a/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
index af4108736..3c10b6f63 100644
--- a/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
+++ b/packages/react-native-audio-api/android/src/main/cpp/audioapi/android/AndroidDecoding.cpp
@@ -340,8 +340,9 @@ size_t produceResampled(AndroidDecoderState &state) {
   }
 }
 
-// Selects the audio track and reads container metadata. MediaCodec is started
-// lazily on the first read/seek so probeDuration() avoids codec spin-up cost.
+// Selects the audio track and reads container metadata. Metadata channels/rate
+// are provisional — settleCodecOutputFormat() replaces them with what MediaCodec
+// actually produces before open() publishes them.
 decoding::DecoderResult configureExtractorMetadata(
     AndroidDecoderState &state,
     int outputSampleRate) {
@@ -423,6 +424,24 @@ decoding::DecoderResult ensureCodecStarted(AndroidDecoderState &state) {
   return Ok(None);
 }
 
+// Starts the codec and pumps it until it commits to an output format, so
+// channels/rate are final before callers size buffers against outputChannels().
+// Track metadata can disagree with what the codec produces — HE-AAC v2 declares
+// one channel in the container and decodes to two — and learning that only
+// during the first read would overflow buffers already sized from the metadata.
+// Frames decoded here stay in nativeLeftover and are served by the first read.
+decoding::DecoderResult settleCodecOutputFormat(AndroidDecoderState &state) {
+  if (auto started = ensureCodecStarted(state); started.is_err()) {
+    return started;
+  }
+
+  while (availableFrames(state.nativeLeftover, state.nativeCursor, state.channels) == 0 &&
+         !state.outputEnded) {
+    pumpCodec(state);
+  }
+  return Ok(None);
+}
+
 decoding::DecoderResult attachMemoryExtractor(
     AndroidDecoderState &state,
     const std::vector<uint8_t> &data) {
@@ -469,11 +488,15 @@ decoding::DecoderResult AndroidDecoder::open(const decoding::LocalFileSource &so
     return Err("AndroidDecoder::open setDataSource failed");
   }
 
-  auto configured = configureExtractorMetadata(*state, source.sampleRate);
-  if (configured.is_err()) {
+  if (auto configured = configureExtractorMetadata(*state, source.sampleRate);
+      configured.is_err()) {
     return configured;
   }
 
+  if (auto settled = settleCodecOutputFormat(*state); settled.is_err()) {
+    return settled;
+  }
+
   outputChannels_ = state->channels;
   outputSampleRate_ = state->outputRate;
   framePosition_ = 0;
@@ -495,11 +518,15 @@ decoding::DecoderResult AndroidDecoder::open(const decoding::EncodedMemorySource
     return attached;
   }
 
-  auto configured = configureExtractorMetadata(*state, source.sampleRate);
-  if (configured.is_err()) {
+  if (auto configured = configureExtractorMetadata(*state, source.sampleRate);
+      configured.is_err()) {
     return configured;
   }
 
+  if (auto settled = settleCodecOutputFormat(*state); settled.is_err()) {
+    return settled;
+  }
+
   outputChannels_ = state->channels;
   outputSampleRate_ = state->outputRate;
   framePosition_ = 0;
@@ -521,23 +548,19 @@ size_t AndroidDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
   }
 
   size_t filled = 0; // frames
-  const int initialChannels = state.channels;
+  // The caller sized outInterleaved from outputChannels(), so this call must
+  // never write wider frames than that. open() settles the codec format up
+  // front, so a change here is anomalous — stop rather than overflow, and keep
+  // the published layout stable for the frames already written.
+  const int callerChannels = outputChannels_;
 
   while (filled < frameCount) {
-    // Keep OsDecoderBase metadata aligned with codec output (may change on
-    // AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED).
-    outputChannels_ = state.channels;
-    outputSampleRate_ = state.outputRate;
-    if (outputChannels_ <= 0) {
-      break;
-    }
-    // Avoid mixing channel layouts inside a single caller buffer.
-    if (filled > 0 && state.channels != initialChannels) {
-      outputChannels_ = initialChannels;
+    if (state.channels != callerChannels) {
       break;
     }
+    outputSampleRate_ = state.outputRate;
 
-    const int ch = outputChannels_;
+    const int ch = callerChannels;
     const bool resample = state.resampler != nullptr;
     std::vector<float> &served = resample ? state.outLeftover : state.nativeLeftover;
     size_t &cursor = resample ? state.outCursor : state.nativeCursor;
@@ -566,14 +589,6 @@ size_t AndroidDecoder::readPcmFrames(float *outInterleaved, size_t frameCount) {
     }
   }
 
-  // Prefer metadata that matches frames actually written this call when a
-  // mid-read format change forced an early return.
-  if (filled > 0 && state.channels != initialChannels) {
-    outputChannels_ = initialChannels;
-  } else {
-    outputChannels_ = state.channels;
-    outputSampleRate_ = state.outputRate;
-  }
   framePosition_ += static_cast<int64_t>(filled);
   return filled;
 }
diff --git a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
index c8b630ef3..99021c82c 100644
--- a/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
+++ b/packages/react-native-audio-api/common/cpp/audioapi/decoding/backends/RawPcmDecoder.cpp
@@ -1,5 +1,5 @@
 #include <audioapi/decoding/backends/RawPcmDecoder.h>
-#include <audioapi/dsp/AudioUtils.hpp>
+#include <audioapi/dsp/AudioUtils.h>
 #include <audioapi/libs/base64/base64.h>
 
 #include <algorithm>
diff --git a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
index b1e208fb2..bad0d93e4 100644
--- a/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
+++ b/packages/react-native-audio-api/ios/audioapi/ios/core/utils/IOSDecoding.mm
@@ -45,11 +45,13 @@ void operator()(std::remove_pointer_t<AudioFileID> *file) const
 // Native reader state kept out of the shared header so Core Audio types never
 // leak into cross-platform code. Owned by IOSDecoder::impl_.
 struct IosDecoderState {
-  // Declaration order matters: ExtAudioFile wraps AudioFile for openMemory(),
-  // so extFile must be destroyed first (members destroy in reverse order).
+  // Declaration order matters (members destroy in reverse order): ExtAudioFile
+  // wraps AudioFile for openMemory(), so extFile must be destroyed first, and
+  // both may read through memoryReadProc while closing — so the buffer that
+  // callback serves has to outlive them and must be declared first.
+  std::vector<uint8_t> memory;
   AudioFilePtr audioFile;
   ExtAudioFilePtr extFile;
-  std::vector<uint8_t> memory;
   // File-native sample rate, used to translate seek time into file frames
   // (ExtAudioFileSeek positions in the file's rate, not the client rate).
   double fileSampleRate = 0.0;

From b679a18bdcba448d261e76aaf49d27d2afd14bcc Mon Sep 17 00:00:00 2001
From: michal <dydmichal@gmail.com>
Date: Tue, 11 Aug 2026 14:37:03 +0200
Subject: [PATCH 12/12] fix: correct iteration through channel map

---
 apps/fabric-example/ios/Podfile.lock            | 6 +++---
 packages/test-app-screen/src/AudioBufferTest.ts | 8 ++++----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/apps/fabric-example/ios/Podfile.lock b/apps/fabric-example/ios/Podfile.lock
index 82cf70322..0b311863e 100644
--- a/apps/fabric-example/ios/Podfile.lock
+++ b/apps/fabric-example/ios/Podfile.lock
@@ -2523,7 +2523,7 @@ EXTERNAL SOURCES:
 
 SPEC CHECKSUMS:
   FBLazyVector: c00c20551d40126351a6783c47ce75f5b374851b
-  hermes-engine: e97e6762d8c64a63b6e1d5cd704577fdd5992f9c
+  hermes-engine: 91023181d4bc5948b457de5314623fbfe4f8604e
   RCTDeprecation: 3bb167081b134461cfeb875ff7ae1945f8635257
   RCTRequired: 74839f55d5058a133a0bc4569b0afec750957f64
   RCTSwiftUI: 87a316382f3eab4dd13d2a0d0fd2adcce917361a
@@ -2532,7 +2532,7 @@ SPEC CHECKSUMS:
   React: 1b1536b9099195944034e65b1830f463caaa8390
   React-callinvoker: 6dff6d17d1d6cc8fdf85468a649bafed473c65f5
   React-Core: 00faa4d038298089a1d5a5b21dde8660c4f0820d
-  React-Core-prebuilt: c28e62d9521adb5940a1bf6d8d31c4f70debdbe3
+  React-Core-prebuilt: a6d614de037caff7898424dfc22915ec792de921
   React-CoreModules: a17807f849bfd86045b0b9a75ec8c19373b482f6
   React-cxxreact: c7b53ace5827be54048288bce5c55f337c41e95f
   React-debug: e1f00fcd2cef58a2897471a6d76a4ef5f5f90c74
@@ -2598,7 +2598,7 @@ SPEC CHECKSUMS:
   ReactCommon: fe2a3af8975e63efa60f95fca8c34dc85deee360
   ReactNativeDependencies: 4d5ce2683b6d74f7c686bf90a88c7d381295cf3c
   RNAudioAPI: 50957b72cc742b9aa1e05349be71b9db73c9cf74
-  RNAudioWorklets: febe470be646585d9b8b0de320a5fb8684cb012c
+  RNAudioWorklets: ff0c53fd3c3bbffacb7dd3beb03ffe0ea9f1fd05
   RNGestureHandler: 187c5c7936abf427bc4d22d6c3b1ac80ad1f63c0
   RNReanimated: 3a204af3747842859392545d41d443b9c5e428a3
   RNScreens: 01b065ded2dfe7987bcce770ff3a196be417ff41
diff --git a/packages/test-app-screen/src/AudioBufferTest.ts b/packages/test-app-screen/src/AudioBufferTest.ts
index cd6e36de6..2bb0d03dc 100644
--- a/packages/test-app-screen/src/AudioBufferTest.ts
+++ b/packages/test-app-screen/src/AudioBufferTest.ts
@@ -94,9 +94,9 @@ export const audioBufferFormatsTest = async (audioContextRef: React.RefObject<Au
 }
 
 export const audioBufferChannelsTest = async (audioContextRef: React.RefObject<AudioContext | null>, setTestingInfo: (value: React.SetStateAction<string>) => void) => {
-  for (const channelsStr in CHANNELS_MAP) {
-    const channels = parseInt(channelsStr, 10);
-    const url = CHANNELS_MAP.get(channels)!;
+  const lastChannelCount = Math.max(...CHANNELS_MAP.keys());
+  for (const [channels, url] of CHANNELS_MAP) {
+    console.log(`Testing audio buffer with ${channels} channels`);
     const expectedDuration = DURATIONS_MAP.get(channels)!;
     setTestingInfo(`Loading audio buffer with ${channels} channels`);
     await fetch(url, {
@@ -121,7 +121,7 @@ export const audioBufferChannelsTest = async (audioContextRef: React.RefObject<A
             bufferSource.connect(audioContextRef.current!.destination);
             bufferSource.start();
             await new Promise(resolve => setTimeout(resolve, 4000));
-            if (channels === Object.keys(CHANNELS_MAP).length) {
+            if (channels === lastChannelCount) {
               bufferSource.onEnded = () => {
                 setTestingInfo('Audio buffer channels test completed.');
               };