react-native-tuner-engine 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 denizyesilirmak
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# react-native-tuner-engine
+
+A React Native Turbo Module for real-time instrument pitch detection. The detection pipeline runs entirely in C++ on a dedicated audio thread and delivers per-frame results to JavaScript via the New Architecture event system.
+
+Requires React Native **0.75 or later** with the New Architecture enabled.
+
+## How it works
+
+Audio is captured through platform-native APIs (AVAudioEngine on iOS, Oboe on Android) and fed into a lock-free SPSC ring buffer. A C++ worker thread drains the buffer in fixed-size frames, runs the signal through a preprocessing pipeline, then through an ensemble of three pitch detectors (YIN, PYIN, cepstrum). The ensemble votes for the best estimate and fires an `onPitch` event on the JS thread.
+
+The audio callback allocates nothing at runtime — all working buffers are pre-allocated during initialization.
+
+## Installation
+
+```sh
+npm install react-native-tuner-engine
+# or
+yarn add react-native-tuner-engine
+```
+
+### iOS
+
+Add a microphone usage description to your app's `Info.plist`:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>Microphone access is required for pitch detection.</string>
+```
+
+Then run `pod install`.
+
+### Android
+
+The library's `AndroidManifest.xml` already declares `RECORD_AUDIO`. You still need to request the permission at runtime — use `requestPermission()` described below, or handle it yourself before calling `start()`.
+
+## Quick start
+
+```tsx
+import { useTuner } from 'react-native-tuner-engine';
+
+export function TunerScreen() {
+  const { start, stop, latest, isRunning, error } = useTuner({
+    noiseGateDb: -50,
+    confidenceThreshold: 0.75,
+  });
+
+  return (
+    <>
+      <Text>{latest?.noteName}{latest?.octave} {latest?.cents.toFixed(1)} ¢</Text>
+      <Button title={isRunning ? 'Stop' : 'Start'} onPress={isRunning ? stop : start} />
+    </>
+  );
+}
+```
+
+`useTuner` requests the microphone permission, configures the engine, and subscribes to events — all in one call.
+
+## API
+
+### `useTuner(options?)`
+
+React hook. Returns `{ start, stop, latest, isRunning, error }`.
+
+```typescript
+import { useTuner } from 'react-native-tuner-engine';
+
+const { start, stop, latest, isRunning, error } = useTuner({
+  // All fields optional — defaults shown
+  sampleRate?: number;          // 48000
+  frameSize?: number;           // 2048
+  noiseGateDb?: number;         // -55 dBFS
+  confidenceThreshold?: number; // 0.75  (0–1)
+  minFrequency?: number;        // 60 Hz
+  maxFrequency?: number;        // 1200 Hz
+  instrument?: Instrument;      // 'chromatic'
+  a4?: number;                  // 440 Hz
+
+  // DSP tuning
+  emaAlpha?: number;            // 0.35  — smoothing (0.05 = slow/stable, 1.0 = instant)
+  hysteresisFrames?: number;    // 3     — frames before a note change is confirmed (1–10)
+  hpfCutoffHz?: number;         // 70 Hz — high-pass filter cutoff (30 for bass, 100 for violin)
+});
+```
+
+`start()` — requests mic permission, configures the engine, then begins capture. Throws if permission is denied.
+
+`stop()` — stops capture. Safe to call when already stopped.
+
+`latest` — the most recent `PitchEvent`, or `null` before the first frame.
+
+`error` — set if `start()` throws; `null` otherwise.
+
+### `TunerEngine`
+
+Low-level imperative API, useful outside of React components.
+
+```typescript
+import { TunerEngine } from 'react-native-tuner-engine';
+
+await TunerEngine.requestPermission(); // → boolean
+await TunerEngine.configure({ noiseGateDb: -50 });
+await TunerEngine.start();
+
+const unsub = TunerEngine.onPitch((event) => {
+  if (event.hasPitch) console.log(event.noteName, event.cents);
+});
+
+// later:
+unsub();
+await TunerEngine.stop();
+```
+
+### Types
+
+```typescript
+type PitchEvent = {
+  hasPitch: boolean;
+  frequency: number;  // Hz
+  confidence: number; // 0–1
+  rmsDb: number;      // dBFS
+  noteName: string;   // e.g. "A"
+  octave: number;
+  cents: number;      // −50 to +50 relative to equal temperament
+};
+
+type TunerConfig = {
+  sampleRate?: number;          // default 48000
+  frameSize?: number;           // default 2048
+  noiseGateDb?: number;         // default -55 dBFS
+  confidenceThreshold?: number; // default 0.75
+  minFrequency?: number;        // default 60 Hz
+  maxFrequency?: number;        // default 1200 Hz
+  a4?: number;                  // default 440 Hz
+  emaAlpha?: number;            // default 0.35 — PostProcessor smoothing (0.05–1.0)
+  hysteresisFrames?: number;    // default 3    — frames to confirm a note change (1–10)
+  hpfCutoffHz?: number;         // default 70   — high-pass filter cutoff in Hz (20–300)
+  onsetDetection?: boolean;     // default false — resets smoothing on note attacks
+};
+
+type Instrument =
+  | 'guitar' | 'bass' | 'violin' | 'viola' | 'cello'
+  | 'ukulele' | 'mandolin' | 'banjo' | 'chromatic';
+
+type Temperament = 'equal' | 'just';
+```
+
+### Additional methods on `TunerEngine`
+
+```typescript
+TunerEngine.setA4(hz: number): void          // default 440
+TunerEngine.setInstrument(name: Instrument): void
+TunerEngine.setTemperament(name: Temperament): void
+TunerEngine.getStatus(): { isRunning: boolean; engineReady: boolean }
+```
+
+For the full API reference (all config options, quality presets, adaptive frame size, overlap ratio), see **[documents/API.md](documents/API.md)**.
+
+## C++ pipeline
+
+The shared C++ core (`cpp/`) compiles as a static library on both platforms.
+
+| Stage | Class | Notes |
+|---|---|---|
+| High-pass filter | `BiquadHpf` | Direct-Form II Transposed, 70 Hz cutoff (configurable), Q 0.707 |
+| Windowing | `Window` | Hann window, precomputed coefficients |
+| Pitch detection | `EnsembleSelector` | Runs YIN, PYIN, and cepstrum; votes by agreement within 1 semitone |
+| — detector 1 | `YinPitchDetector` | YIN with parabolic interpolation |
+| — detector 2 | `PyinPitchDetector` | Probabilistic YIN; prunes harmonic aliases |
+| — detector 3 | `CepstrumPitchDetector` | Real cepstrum via radix-2 FFT; SNR-based confidence |
+| Note mapping | `NoteMapper` | Hz → MIDI, note name, octave, cents deviation |
+| SNR estimation | `SnrEstimator` | Signal RMS vs. noise-floor EMA |
+| Post-processing | `PostProcessor` | Median-5 filter, EMA smoothing (configurable), note-transition hysteresis (configurable) |
+| Dispatch | `AudioFrameDispatcher` | SPSC lock-free queue, dedicated worker thread |
+
+## Performance targets
+
+| Metric | Target |
+|---|---|
+| Time to first pitch | < 300 ms |
+| Per-frame CPU (midrange Android) | < 5 ms |
+| Per-frame CPU (iPhone 12+) | < 3 ms |
+| Audio-thread allocations | 0 |
+
+## Requirements
+
+- React Native 0.75+ (New Architecture / Bridgeless)
+- iOS 13+
+- Android API 24+, NDK r26+

package/TunerEngine.podspec

@@ -0,0 +1,32 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "TunerEngine"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => '13.4' }
+  s.source       = { :git => "https://github.com/denizyesilirmak/react-native-tuner-engine.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{h,m,mm}",
+    "cpp/src/**/*.cpp",
+    "cpp/include/**/*.hpp"
+  ]
+  s.private_header_files = "ios/**/*.h"
+
+  s.frameworks = ["AVFoundation", "AVFAudio"]
+
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/cpp/include\"",
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++17",
+    "CLANG_CXX_LIBRARY" => "libc++"
+  }
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,86 @@
+buildscript {
+  ext.TunerEngine = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36,
+    ndkVersion: "26.3.11579264"
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return TunerEngine[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.tunerengine"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+  ndkVersion getExtOrDefault("ndkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-std=c++17"
+        abiFilters "arm64-v8a", "armeabi-v7a", "x86_64"
+        arguments "-DANDROID_STL=c++_shared"
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "src/main/cpp/CMakeLists.txt"
+      version "3.22.1"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "com.google.oboe:oboe:1.9.3"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.RECORD_AUDIO" />
+</manifest>

package/android/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,31 @@
+cmake_minimum_required(VERSION 3.22.1)
+
+project(tunerengine LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Pull in the shared C++ core
+add_subdirectory(
+  ${CMAKE_CURRENT_SOURCE_DIR}/../../../../cpp
+  ${CMAKE_BINARY_DIR}/tuner_engine_core
+)
+
+find_package(oboe REQUIRED CONFIG)
+
+add_library(tunerengine SHARED
+  TunerEngineJni.cpp
+  OboeAudioSource.cpp
+)
+
+target_include_directories(tunerengine PRIVATE
+  ${CMAKE_CURRENT_SOURCE_DIR}
+)
+
+target_link_libraries(tunerengine
+  PRIVATE
+    tuner_engine_core
+    oboe::oboe
+    android
+    log
+)

package/android/src/main/cpp/OboeAudioSource.cpp

@@ -0,0 +1,101 @@
+#include "OboeAudioSource.h"
+#include <android/log.h>
+
+#define LOG_TAG "OboeAudioSource"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+OboeAudioSource::OboeAudioSource(SamplesCallback callback)
+    : callback_(std::move(callback)) {}
+
+OboeAudioSource::~OboeAudioSource() {
+    stop();
+}
+
+
+bool OboeAudioSource::openStream() {
+    oboe::AudioStreamBuilder builder;
+    builder.setDirection(oboe::Direction::Input);
+    builder.setPerformanceMode(oboe::PerformanceMode::LowLatency);
+    builder.setSharingMode(oboe::SharingMode::Exclusive);
+    builder.setFormat(oboe::AudioFormat::Float);
+    builder.setChannelCount(oboe::ChannelCount::Mono);
+    builder.setSampleRate(48000);
+    builder.setCallback(this);
+
+    oboe::Result result = builder.openStream(stream_);
+
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to open Exclusive stream: %s — retrying Shared", oboe::convertToText(result));
+
+        // Fall back to Shared mode
+        builder.setSharingMode(oboe::SharingMode::Shared);
+        result = builder.openStream(stream_);
+
+        if (result != oboe::Result::OK) {
+            LOGE("Failed to open Shared stream: %s", oboe::convertToText(result));
+            return false;
+        }
+    }
+
+    sampleRate_ = static_cast<float>(stream_->getSampleRate());
+    LOGI("Oboe stream opened: sampleRate=%.0f sharingMode=%s",
+         sampleRate_,
+         oboe::convertToText(stream_->getSharingMode()));
+    return true;
+}
+
+bool OboeAudioSource::start() {
+    if (!openStream()) return false;
+
+    oboe::Result result = stream_->requestStart();
+    if (result != oboe::Result::OK) {
+        LOGE("Failed to start stream: %s", oboe::convertToText(result));
+        stream_->close();
+        stream_.reset();
+        return false;
+    }
+
+    LOGI("Oboe stream started");
+    return true;
+}
+
+void OboeAudioSource::stop() {
+    stopped_.store(true, std::memory_order_relaxed);
+    if (restartThread_.joinable()) {
+        restartThread_.join();
+    }
+    if (stream_) {
+        stream_->requestStop();
+        stream_->close();
+        stream_.reset();
+        LOGI("Oboe stream stopped");
+    }
+}
+
+float OboeAudioSource::sampleRate() const {
+    return sampleRate_;
+}
+
+oboe::DataCallbackResult OboeAudioSource::onAudioReady(
+    oboe::AudioStream* /*stream*/,
+    void* audioData,
+    int32_t numFrames
+) {
+    if (callback_) {
+        callback_(static_cast<const float*>(audioData), numFrames, sampleRate_);
+    }
+    return oboe::DataCallbackResult::Continue;
+}
+
+void OboeAudioSource::onErrorAfterClose(oboe::AudioStream* /*stream*/, oboe::Result error) {
+    LOGE("Oboe stream error after close: %s — attempting restart", oboe::convertToText(error));
+    if (stopped_.load(std::memory_order_relaxed)) return;
+    // Restart on a separate thread to avoid deadlock; join in stop()/destructor
+    if (restartThread_.joinable()) restartThread_.join();
+    restartThread_ = std::thread([this]() {
+        if (!stopped_.load(std::memory_order_relaxed)) {
+            start();
+        }
+    });
+}

package/android/src/main/cpp/OboeAudioSource.h

@@ -0,0 +1,41 @@
+#pragma once
+
+#include <oboe/Oboe.h>
+#include <functional>
+#include <memory>
+#include <atomic>
+#include <thread>
+
+// Oboe-based microphone capture.
+// The onSamples callback is invoked on the Oboe real-time audio thread —
+// must not block, lock, or allocate.
+class OboeAudioSource : public oboe::AudioStreamCallback,
+                        public std::enable_shared_from_this<OboeAudioSource> {
+public:
+    using SamplesCallback = std::function<void(const float* samples, int count, float sampleRate)>;
+
+    explicit OboeAudioSource(SamplesCallback callback);
+    ~OboeAudioSource();
+
+    bool start();
+    void stop();
+    float sampleRate() const;
+
+    // oboe::AudioStreamCallback
+    oboe::DataCallbackResult onAudioReady(
+        oboe::AudioStream* stream,
+        void* audioData,
+        int32_t numFrames
+    ) override;
+
+    void onErrorAfterClose(oboe::AudioStream* stream, oboe::Result error) override;
+
+private:
+    bool openStream();
+
+    SamplesCallback callback_;
+    std::shared_ptr<oboe::AudioStream> stream_;
+    float sampleRate_{48000.0f};
+    std::atomic<bool> stopped_{false};
+    std::thread restartThread_;
+};