react-native-tuner-engine 1.0.0

package/lib/typescript/src/index.d.ts

@@ -0,0 +1,4 @@
+export { default as TunerEngine } from './TunerEngine';
+export { useTuner } from './useTuner';
+export type { EngineStatus, Instrument, PitchEvent, QualityPreset, Temperament, TunerConfig, TuningPreset, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,SAAS,CAAC"}

package/lib/typescript/src/types.d.ts

@@ -0,0 +1,86 @@
+export type Instrument = 'guitar' | 'bass' | 'violin' | 'viola' | 'cello' | 'ukulele' | 'mandolin' | 'banjo' | 'chromatic';
+export type Temperament = 'equal' | 'just';
+/**
+ * Quality preset that maps to a frame size + overlap combination.
+ * - low-latency: frameSize=1024, overlap=0 — fastest response, less accuracy on low notes
+ * - balanced: frameSize=2048, overlap=0.5 — good for most instruments
+ * - high-accuracy: frameSize=4096, overlap=0.75 — best for bass/cello, ~21ms update rate
+ */
+export type QualityPreset = 'low-latency' | 'balanced' | 'high-accuracy';
+export type TunerConfig = {
+    /** Audio sample rate in Hz. Default: 48000 */
+    sampleRate?: number;
+    /** DSP frame size in samples. Default: 2048 */
+    frameSize?: number;
+    /** Noise gate threshold in dBFS. Frames quieter than this are ignored. Default: -55 */
+    noiseGateDb?: number;
+    /** Minimum detector confidence (0–1) to emit a pitch event. Default: 0.75 */
+    confidenceThreshold?: number;
+    /** Lowest frequency to detect in Hz. Default: 60 */
+    minFrequency?: number;
+    /** Highest frequency to detect in Hz. Default: 1200 */
+    maxFrequency?: number;
+    /** A4 reference pitch in Hz. Default: 440 */
+    a4?: number;
+    /**
+     * PostProcessor EMA smoothing factor (0.05–1.0). Lower = smoother/slower,
+     * higher = more responsive but jittery. Default: 0.35
+     */
+    emaAlpha?: number;
+    /**
+     * Consecutive frames required to confirm a note change (1–10).
+     * Higher = more stable note display, lower = faster switching. Default: 3
+     */
+    hysteresisFrames?: number;
+    /**
+     * High-pass filter cutoff in Hz (20–300). Cuts rumble below this frequency.
+     * Lower for bass guitar (e.g. 30), higher for violin (e.g. 100). Default: 70
+     */
+    hpfCutoffHz?: number;
+    /**
+     * Enable onset detection. When enabled, the PostProcessor resets on note
+     * attacks for faster response. Minimal CPU cost (one comparison per frame).
+     * Default: false
+     */
+    onsetDetection?: boolean;
+    /**
+     * Fraction of the frame that overlaps with the previous frame (0.0–0.75).
+     * Higher overlap gives more frequent pitch updates at the cost of CPU.
+     * - 0.0: no overlap (default, backward-compatible)
+     * - 0.5: 50% overlap (2x update rate)
+     * - 0.75: 75% overlap (4x update rate)
+     * Default: 0
+     */
+    overlapRatio?: number;
+    /**
+     * When true, frame size is automatically selected based on the configured instrument.
+     * Bass and cello use 4096 for better low-frequency resolution; others use 2048.
+     * Overridden if frameSize is explicitly provided.
+     * Default: true
+     */
+    adaptiveFrameSize?: boolean;
+    /**
+     * Quality preset that configures frameSize and overlapRatio together.
+     * Overrides individual frameSize/overlapRatio if provided.
+     */
+    quality?: QualityPreset;
+};
+export type TuningPreset = 'guitar_standard' | 'guitar_drop_d' | 'guitar_open_g' | 'bass_standard' | 'bass_drop_d' | 'violin_standard' | 'viola_standard' | 'cello_standard' | 'ukulele_standard';
+export type PitchEvent = {
+    hasPitch: boolean;
+    frequency: number;
+    confidence: number;
+    rmsDb: number;
+    noteName: string;
+    octave: number;
+    cents: number;
+    /** Nearest string in the active tuning, e.g. "E2". Empty string when no tuning is set. */
+    nearestString: string;
+    /** Cents deviation from that string's target frequency (negative = flat). */
+    stringDeviation: number;
+};
+export type EngineStatus = {
+    isRunning: boolean;
+    engineReady: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,OAAO,GACP,OAAO,GACP,SAAS,GACT,UAAU,GACV,OAAO,GACP,WAAW,CAAC;AAEhB,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,UAAU,GAAG,eAAe,CAAC;AAEzE,MAAM,MAAM,WAAW,GAAG;IACxB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,eAAe,GACf,eAAe,GACf,eAAe,GACf,aAAa,GACb,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC"}

package/lib/typescript/src/useTuner.d.ts

@@ -0,0 +1,15 @@
+import type { Instrument, PitchEvent, TunerConfig } from './types';
+type UseTunerOptions = TunerConfig & {
+    instrument?: Instrument;
+    a4?: number;
+};
+type UseTunerResult = {
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    latest: PitchEvent | null;
+    isRunning: boolean;
+    error: Error | null;
+};
+export declare function useTuner(opts?: UseTunerOptions): UseTunerResult;
+export {};
+//# sourceMappingURL=useTuner.d.ts.map

package/lib/typescript/src/useTuner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTuner.d.ts","sourceRoot":"","sources":["../../../src/useTuner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEnE,KAAK,eAAe,GAAG,WAAW,GAAG;IACnC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF,wBAAgB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,cAAc,CAiDnE"}

package/package.json

@@ -0,0 +1,141 @@
+{
+  "name": "react-native-tuner-engine",
+  "version": "1.0.0",
+  "description": "A high-performance React Native Turbo Module for real-time instrument tuning with native audio processing and pitch detection.",
+  "main": "./lib/module/index.js",
+  "source": "./src/index.tsx",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-tuner-engine-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "test": "jest",
+    "test:cpp": "cmake --build cpp/build --target tuner_engine_tests && ./cpp/build/tuner_engine_tests",
+    "lint": "eslint \"**/*.{js,ts,tsx}\""
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/denizyesilirmak/react-native-tuner-engine.git"
+  },
+  "author": "denizyesilirmak <denizyesilirmak@gmail.com> (https://github.com/denizyesilirmak)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/denizyesilirmak/react-native-tuner-engine/issues"
+  },
+  "homepage": "https://github.com/denizyesilirmak/react-native-tuner-engine#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.0.3",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@jest/globals": "^30.0.0",
+    "@react-native/babel-preset": "0.85.0",
+    "@react-native/eslint-config": "0.85.0",
+    "@react-native/jest-preset": "0.85.0",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "jest": "30.4.1",
+    "prettier": "^3.8.1",
+    "react": "19.2.3",
+    "react-native": "0.85.0",
+    "react-native-builder-bob": "^0.41.0",
+    "turbo": "^2.8.21",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "TunerEngineSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.tunerengine"
+    }
+  },
+  "jest": {
+    "preset": "@react-native/jest-preset",
+    "testEnvironment": "node",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "jest",
+      "eslint"
+    ],
+    "version": "0.62.0"
+  }
+}

package/src/NativeTunerEngine.ts

@@ -0,0 +1,17 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+export interface Spec extends TurboModule {
+  configure(opts: Object): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  setA4(hz: number): void;
+  setInstrument(name: string): void;
+  setTemperament(name: string): void;
+  setTuning(name: string): void;
+  requestPermission(): Promise<boolean>;
+  getStatus(): Object;
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('TunerEngine');

package/src/TunerEngine.ts

@@ -0,0 +1,62 @@
+import { DeviceEventEmitter } from 'react-native';
+import NativeTunerEngine from './NativeTunerEngine';
+import type {
+  EngineStatus,
+  Instrument,
+  PitchEvent,
+  Temperament,
+  TunerConfig,
+  TuningPreset,
+} from './types';
+
+type PitchCallback = (event: PitchEvent) => void;
+type Unsubscribe = () => void;
+
+class TunerEngine {
+  configure(opts: TunerConfig): Promise<void> {
+    return NativeTunerEngine.configure(opts);
+  }
+
+  start(): Promise<void> {
+    return NativeTunerEngine.start();
+  }
+
+  stop(): Promise<void> {
+    return NativeTunerEngine.stop();
+  }
+
+  requestPermission(): Promise<boolean> {
+    return NativeTunerEngine.requestPermission();
+  }
+
+  setA4(hz: number): void {
+    NativeTunerEngine.setA4(hz);
+  }
+
+  setInstrument(name: Instrument): void {
+    NativeTunerEngine.setInstrument(name);
+  }
+
+  setTemperament(name: Temperament): void {
+    NativeTunerEngine.setTemperament(name);
+  }
+
+  setTuning(name: TuningPreset | ''): void {
+    NativeTunerEngine.setTuning(name);
+  }
+
+  getStatus(): EngineStatus {
+    return NativeTunerEngine.getStatus() as EngineStatus;
+  }
+
+  onPitch(callback: PitchCallback): Unsubscribe {
+    (globalThis as any).__tunerEngineOnPitch = callback;
+    const sub = DeviceEventEmitter.addListener('onPitch', callback);
+    return () => {
+      (globalThis as any).__tunerEngineOnPitch = undefined;
+      sub.remove();
+    };
+  }
+}
+
+export default new TunerEngine();

package/src/index.tsx

@@ -0,0 +1,11 @@
+export { default as TunerEngine } from './TunerEngine';
+export { useTuner } from './useTuner';
+export type {
+  EngineStatus,
+  Instrument,
+  PitchEvent,
+  QualityPreset,
+  Temperament,
+  TunerConfig,
+  TuningPreset,
+} from './types';

package/src/types.ts

@@ -0,0 +1,109 @@
+export type Instrument =
+  | 'guitar'
+  | 'bass'
+  | 'violin'
+  | 'viola'
+  | 'cello'
+  | 'ukulele'
+  | 'mandolin'
+  | 'banjo'
+  | 'chromatic';
+
+export type Temperament = 'equal' | 'just';
+
+/**
+ * Quality preset that maps to a frame size + overlap combination.
+ * - low-latency: frameSize=1024, overlap=0 — fastest response, less accuracy on low notes
+ * - balanced: frameSize=2048, overlap=0.5 — good for most instruments
+ * - high-accuracy: frameSize=4096, overlap=0.75 — best for bass/cello, ~21ms update rate
+ */
+export type QualityPreset = 'low-latency' | 'balanced' | 'high-accuracy';
+
+export type TunerConfig = {
+  /** Audio sample rate in Hz. Default: 48000 */
+  sampleRate?: number;
+  /** DSP frame size in samples. Default: 2048 */
+  frameSize?: number;
+  /** Noise gate threshold in dBFS. Frames quieter than this are ignored. Default: -55 */
+  noiseGateDb?: number;
+  /** Minimum detector confidence (0–1) to emit a pitch event. Default: 0.75 */
+  confidenceThreshold?: number;
+  /** Lowest frequency to detect in Hz. Default: 60 */
+  minFrequency?: number;
+  /** Highest frequency to detect in Hz. Default: 1200 */
+  maxFrequency?: number;
+  /** A4 reference pitch in Hz. Default: 440 */
+  a4?: number;
+  /**
+   * PostProcessor EMA smoothing factor (0.05–1.0). Lower = smoother/slower,
+   * higher = more responsive but jittery. Default: 0.35
+   */
+  emaAlpha?: number;
+  /**
+   * Consecutive frames required to confirm a note change (1–10).
+   * Higher = more stable note display, lower = faster switching. Default: 3
+   */
+  hysteresisFrames?: number;
+  /**
+   * High-pass filter cutoff in Hz (20–300). Cuts rumble below this frequency.
+   * Lower for bass guitar (e.g. 30), higher for violin (e.g. 100). Default: 70
+   */
+  hpfCutoffHz?: number;
+  /**
+   * Enable onset detection. When enabled, the PostProcessor resets on note
+   * attacks for faster response. Minimal CPU cost (one comparison per frame).
+   * Default: false
+   */
+  onsetDetection?: boolean;
+  /**
+   * Fraction of the frame that overlaps with the previous frame (0.0–0.75).
+   * Higher overlap gives more frequent pitch updates at the cost of CPU.
+   * - 0.0: no overlap (default, backward-compatible)
+   * - 0.5: 50% overlap (2x update rate)
+   * - 0.75: 75% overlap (4x update rate)
+   * Default: 0
+   */
+  overlapRatio?: number;
+  /**
+   * When true, frame size is automatically selected based on the configured instrument.
+   * Bass and cello use 4096 for better low-frequency resolution; others use 2048.
+   * Overridden if frameSize is explicitly provided.
+   * Default: true
+   */
+  adaptiveFrameSize?: boolean;
+  /**
+   * Quality preset that configures frameSize and overlapRatio together.
+   * Overrides individual frameSize/overlapRatio if provided.
+   */
+  quality?: QualityPreset;
+};
+
+export type TuningPreset =
+  | 'guitar_standard'
+  | 'guitar_drop_d'
+  | 'guitar_open_g'
+  | 'bass_standard'
+  | 'bass_drop_d'
+  | 'violin_standard'
+  | 'viola_standard'
+  | 'cello_standard'
+  | 'ukulele_standard';
+
+export type PitchEvent = {
+  hasPitch: boolean;
+  frequency: number;
+  confidence: number;
+  rmsDb: number;
+  noteName: string;
+  octave: number;
+  cents: number;
+  /** Nearest string in the active tuning, e.g. "E2". Empty string when no tuning is set. */
+  nearestString: string;
+  /** Cents deviation from that string's target frequency (negative = flat). */
+  stringDeviation: number;
+};
+
+export type EngineStatus = {
+  isRunning: boolean;
+  engineReady: boolean;
+};

package/src/useTuner.ts

@@ -0,0 +1,67 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import TunerEngine from './TunerEngine';
+import type { Instrument, PitchEvent, TunerConfig } from './types';
+
+type UseTunerOptions = TunerConfig & {
+  instrument?: Instrument;
+  a4?: number;
+};
+
+type UseTunerResult = {
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  latest: PitchEvent | null;
+  isRunning: boolean;
+  error: Error | null;
+};
+
+export function useTuner(opts: UseTunerOptions = {}): UseTunerResult {
+  const [latest, setLatest] = useState<PitchEvent | null>(null);
+  const [isRunning, setIsRunning] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const optsRef = useRef(opts);
+  optsRef.current = opts;
+
+  const unsubscribeRef = useRef<(() => void) | null>(null);
+
+  const stop = useCallback(async () => {
+    unsubscribeRef.current?.();
+    unsubscribeRef.current = null;
+    await TunerEngine.stop();
+    setIsRunning(false);
+  }, []);
+
+  const start = useCallback(async () => {
+    setError(null);
+    try {
+      const granted = await TunerEngine.requestPermission();
+      if (!granted) {
+        throw new Error('Microphone permission denied');
+      }
+
+      const { instrument, a4, ...config } = optsRef.current;
+      await TunerEngine.configure(config);
+
+      if (instrument) TunerEngine.setInstrument(instrument);
+      if (a4 !== undefined) TunerEngine.setA4(a4);
+
+      unsubscribeRef.current = TunerEngine.onPitch(setLatest);
+
+      await TunerEngine.start();
+      setIsRunning(true);
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setIsRunning(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      unsubscribeRef.current?.();
+      TunerEngine.stop();
+    };
+  }, []);
+
+  return { start, stop, latest, isRunning, error };
+}