@clarionhq/recorder 0.0.1 → 0.1.0

package/nitrogen/generated/shared/c++/NativeRecorderConfig.hpp

@@ -0,0 +1,116 @@
+///
+/// NativeRecorderConfig.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+#include <string>
+#include <optional>
+
+namespace margelo::nitro::clarion::recorder {
+
+  /**
+   * A struct which can be represented as a JavaScript object (NativeRecorderConfig).
+   */
+  struct NativeRecorderConfig final {
+  public:
+    double sampleRate     SWIFT_PRIVATE;
+    double channels     SWIFT_PRIVATE;
+    double bitDepth     SWIFT_PRIVATE;
+    std::optional<std::string> outputDirectory     SWIFT_PRIVATE;
+    std::optional<std::string> filenamePrefix     SWIFT_PRIVATE;
+    std::optional<double> rotateAfterMs     SWIFT_PRIVATE;
+    bool emitAudioLevel     SWIFT_PRIVATE;
+    double audioLevelIntervalMs     SWIFT_PRIVATE;
+    double aacBitrate     SWIFT_PRIVATE;
+
+  public:
+    NativeRecorderConfig() = default;
+    explicit NativeRecorderConfig(double sampleRate, double channels, double bitDepth, std::optional<std::string> outputDirectory, std::optional<std::string> filenamePrefix, std::optional<double> rotateAfterMs, bool emitAudioLevel, double audioLevelIntervalMs, double aacBitrate): sampleRate(sampleRate), channels(channels), bitDepth(bitDepth), outputDirectory(outputDirectory), filenamePrefix(filenamePrefix), rotateAfterMs(rotateAfterMs), emitAudioLevel(emitAudioLevel), audioLevelIntervalMs(audioLevelIntervalMs), aacBitrate(aacBitrate) {}
+
+  public:
+    friend bool operator==(const NativeRecorderConfig& lhs, const NativeRecorderConfig& rhs) = default;
+  };
+
+} // namespace margelo::nitro::clarion::recorder
+
+namespace margelo::nitro {
+
+  // C++ NativeRecorderConfig <> JS NativeRecorderConfig (object)
+  template <>
+  struct JSIConverter<margelo::nitro::clarion::recorder::NativeRecorderConfig> final {
+    static inline margelo::nitro::clarion::recorder::NativeRecorderConfig fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::clarion::recorder::NativeRecorderConfig(
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "sampleRate"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "channels"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "bitDepth"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "outputDirectory"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "filenamePrefix"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "rotateAfterMs"))),
+        JSIConverter<bool>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "emitAudioLevel"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "audioLevelIntervalMs"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "aacBitrate")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::clarion::recorder::NativeRecorderConfig& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "sampleRate"), JSIConverter<double>::toJSI(runtime, arg.sampleRate));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "channels"), JSIConverter<double>::toJSI(runtime, arg.channels));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "bitDepth"), JSIConverter<double>::toJSI(runtime, arg.bitDepth));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "outputDirectory"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.outputDirectory));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "filenamePrefix"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.filenamePrefix));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "rotateAfterMs"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.rotateAfterMs));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "emitAudioLevel"), JSIConverter<bool>::toJSI(runtime, arg.emitAudioLevel));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "audioLevelIntervalMs"), JSIConverter<double>::toJSI(runtime, arg.audioLevelIntervalMs));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "aacBitrate"), JSIConverter<double>::toJSI(runtime, arg.aacBitrate));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "sampleRate")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "channels")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "bitDepth")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "outputDirectory")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "filenamePrefix")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "rotateAfterMs")))) return false;
+      if (!JSIConverter<bool>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "emitAudioLevel")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "audioLevelIntervalMs")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "aacBitrate")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/nitrogen/generated/shared/c++/NativeRecorderError.hpp

@@ -0,0 +1,91 @@
+///
+/// NativeRecorderError.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+#include <string>
+
+namespace margelo::nitro::clarion::recorder {
+
+  /**
+   * A struct which can be represented as a JavaScript object (NativeRecorderError).
+   */
+  struct NativeRecorderError final {
+  public:
+    std::string code     SWIFT_PRIVATE;
+    std::string message     SWIFT_PRIVATE;
+    bool recoverable     SWIFT_PRIVATE;
+
+  public:
+    NativeRecorderError() = default;
+    explicit NativeRecorderError(std::string code, std::string message, bool recoverable): code(code), message(message), recoverable(recoverable) {}
+
+  public:
+    friend bool operator==(const NativeRecorderError& lhs, const NativeRecorderError& rhs) = default;
+  };
+
+} // namespace margelo::nitro::clarion::recorder
+
+namespace margelo::nitro {
+
+  // C++ NativeRecorderError <> JS NativeRecorderError (object)
+  template <>
+  struct JSIConverter<margelo::nitro::clarion::recorder::NativeRecorderError> final {
+    static inline margelo::nitro::clarion::recorder::NativeRecorderError fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::clarion::recorder::NativeRecorderError(
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "code"))),
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "message"))),
+        JSIConverter<bool>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "recoverable")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::clarion::recorder::NativeRecorderError& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "code"), JSIConverter<std::string>::toJSI(runtime, arg.code));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "message"), JSIConverter<std::string>::toJSI(runtime, arg.message));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "recoverable"), JSIConverter<bool>::toJSI(runtime, arg.recoverable));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "code")))) return false;
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "message")))) return false;
+      if (!JSIConverter<bool>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "recoverable")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/nitrogen/generated/shared/c++/NativeRecorderResult.hpp

@@ -0,0 +1,103 @@
+///
+/// NativeRecorderResult.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+#include <string>
+
+namespace margelo::nitro::clarion::recorder {
+
+  /**
+   * A struct which can be represented as a JavaScript object (NativeRecorderResult).
+   */
+  struct NativeRecorderResult final {
+  public:
+    std::string uri     SWIFT_PRIVATE;
+    double durationMs     SWIFT_PRIVATE;
+    double sizeBytes     SWIFT_PRIVATE;
+    double sampleRate     SWIFT_PRIVATE;
+    double channels     SWIFT_PRIVATE;
+    double bitDepth     SWIFT_PRIVATE;
+
+  public:
+    NativeRecorderResult() = default;
+    explicit NativeRecorderResult(std::string uri, double durationMs, double sizeBytes, double sampleRate, double channels, double bitDepth): uri(uri), durationMs(durationMs), sizeBytes(sizeBytes), sampleRate(sampleRate), channels(channels), bitDepth(bitDepth) {}
+
+  public:
+    friend bool operator==(const NativeRecorderResult& lhs, const NativeRecorderResult& rhs) = default;
+  };
+
+} // namespace margelo::nitro::clarion::recorder
+
+namespace margelo::nitro {
+
+  // C++ NativeRecorderResult <> JS NativeRecorderResult (object)
+  template <>
+  struct JSIConverter<margelo::nitro::clarion::recorder::NativeRecorderResult> final {
+    static inline margelo::nitro::clarion::recorder::NativeRecorderResult fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::clarion::recorder::NativeRecorderResult(
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "uri"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "durationMs"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "sizeBytes"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "sampleRate"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "channels"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "bitDepth")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::clarion::recorder::NativeRecorderResult& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "uri"), JSIConverter<std::string>::toJSI(runtime, arg.uri));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "durationMs"), JSIConverter<double>::toJSI(runtime, arg.durationMs));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "sizeBytes"), JSIConverter<double>::toJSI(runtime, arg.sizeBytes));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "sampleRate"), JSIConverter<double>::toJSI(runtime, arg.sampleRate));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "channels"), JSIConverter<double>::toJSI(runtime, arg.channels));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "bitDepth"), JSIConverter<double>::toJSI(runtime, arg.bitDepth));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "uri")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "durationMs")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "sizeBytes")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "sampleRate")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "channels")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "bitDepth")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,11 +1,69 @@
 {
   "name": "@clarionhq/recorder",
-  "version": "0.0.1",
-  "description": "Clarion recorder — placeholder, full release coming soon",
-  "main": "index.js",
+  "version": "0.1.0",
+  "description": "Clarion recorder — PCM capture to m4a for React Native (offline-first)",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "lib",
+    "src",
+    "android/src",
+    "android/build.gradle",
+    "android/gradle.properties",
+    "android/AndroidManifest.xml",
+    "ios",
+    "nitrogen",
+    "nitro.json",
+    "clarionhq-recorder.podspec",
+    "README.md",
+    "LICENSE",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/.*"
+  ],
+  "keywords": [
+    "react-native",
+    "audio",
+    "recorder",
+    "pcm",
+    "m4a",
+    "aac",
+    "audiorecord",
+    "avaudioengine",
+    "nitro-modules",
+    "turbomodule",
+    "fabric",
+    "new-architecture"
+  ],
+  "dependencies": {
+    "@clarionhq/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.3.1",
+    "react-native": ">=0.77.0",
+    "react-native-nitro-modules": ">=0.35.0"
+  },
+  "devDependencies": {
+    "nitrogen": "^0.35.6",
+    "react": "18.3.1",
+    "react-native": "0.77.3",
+    "react-native-nitro-modules": "^0.35.6"
+  },
   "license": "MIT",
-  "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "https://github.com/clarionhq/clarion" },
-  "homepage": "https://github.com/clarionhq/clarion",
-  "keywords": ["react-native", "audio", "speech", "voice"]
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Th4nderG0d/clarion",
+    "directory": "packages/recorder"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "nitro:codegen": "nitrogen",
+    "clean": "rm -rf lib nitrogen"
+  }
+}

package/src/RecorderEngine.ts

@@ -0,0 +1,298 @@
+import {
+  ClarionEmitter,
+  ClarionError,
+  DEFAULT_AUDIO_FORMAT,
+  assertTransition,
+  type ClarionEngine,
+  type ClarionEvent,
+  type EngineKind,
+  type EngineState,
+  type Listener,
+  type RecorderEngineConfig,
+  type RecorderResult,
+  type Unsubscribe,
+} from '@clarionhq/core';
+
+import { createNativeRecorder } from './native';
+import type {
+  ClarionRecorder,
+  NativeRecorderConfig,
+  NativeRecorderError,
+  NativeRecorderResult,
+} from './specs/ClarionRecorder.nitro';
+
+const VALID_STATES: readonly EngineState[] = [
+  'idle',
+  'preparing',
+  'ready',
+  'starting',
+  'recording',
+  'paused',
+  'stopping',
+  'error',
+  'released',
+];
+
+const isEngineState = (s: string): s is EngineState =>
+  (VALID_STATES as readonly string[]).includes(s);
+
+// 32 kbps is the highest AAC-LC bitrate universally supported across iOS
+// (Simulator + device) and Android for 16 kHz mono. Higher bitrates work
+// on Android but iOS's AAC encoder rejects them with
+// kAudioFormatUnsupportedDataFormatError. Callers can override for higher
+// sample rates / stereo where larger values are accepted.
+const DEFAULT_AAC_BITRATE = 32_000;
+const DEFAULT_AUDIO_LEVEL_INTERVAL_MS = 50;
+
+export interface RecorderEngineOptions extends RecorderEngineConfig {
+  aacBitrate?: number;
+}
+
+export class RecorderEngine implements ClarionEngine {
+  readonly kind: EngineKind = 'recorder';
+
+  private readonly emitter = new ClarionEmitter();
+  private readonly native: ClarionRecorder;
+  private readonly listenerIds: number[] = [];
+  private readonly options: RecorderEngineOptions;
+
+  private currentState: EngineState = 'idle';
+
+  constructor(options: RecorderEngineOptions = {}) {
+    this.options = options;
+    this.native = createNativeRecorder();
+    this.bindNativeListeners();
+  }
+
+  get state(): EngineState {
+    return this.currentState;
+  }
+
+  on(listener: Listener<ClarionEvent>): Unsubscribe {
+    return this.emitter.on(listener);
+  }
+
+  async prepare(): Promise<void> {
+    this.transitionTo('preparing');
+    try {
+      const config = this.buildNativeConfig();
+      await this.native.prepare(config);
+      // Native side fires state='ready' via the state listener — no JS-side transition needed.
+    } catch (err) {
+      this.handleNativeError(err, 'prepare');
+      throw err;
+    }
+  }
+
+  async start(): Promise<void> {
+    // Auto-recover from a previous error — caller can retry without manual reset.
+    if (this.currentState === 'error') {
+      this.setState('idle');
+    }
+    // Auto-prepare if no session yet — callers don't need to know about prepare().
+    if (this.currentState === 'idle') {
+      await this.prepare();
+    }
+    if (this.currentState !== 'ready') {
+      throw new ClarionError({
+        code: 'INVALID_STATE',
+        message: `Cannot start from state '${this.currentState}'`,
+      });
+    }
+    this.transitionTo('starting');
+    try {
+      await this.native.start();
+      // Native side fires state='recording' via the state listener.
+    } catch (err) {
+      this.handleNativeError(err, 'start');
+      throw err;
+    }
+  }
+
+  async pause(): Promise<void> {
+    if (this.currentState !== 'recording') {
+      throw new ClarionError({
+        code: 'INVALID_STATE',
+        message: `Cannot pause from state '${this.currentState}'`,
+      });
+    }
+    try {
+      await this.native.pause();
+    } catch (err) {
+      this.handleNativeError(err, 'pause');
+      throw err;
+    }
+  }
+
+  async resume(): Promise<void> {
+    if (this.currentState !== 'paused') {
+      throw new ClarionError({
+        code: 'INVALID_STATE',
+        message: `Cannot resume from state '${this.currentState}'`,
+      });
+    }
+    try {
+      await this.native.resume();
+    } catch (err) {
+      this.handleNativeError(err, 'resume');
+      throw err;
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.transitionTo('stopping');
+    try {
+      const result = await this.native.stop();
+      this.emitter.emit({
+        type: 'recording-complete',
+        result: this.toRecorderResult(result),
+      });
+    } catch (err) {
+      this.handleNativeError(err, 'stop');
+      throw err;
+    }
+  }
+
+  async discard(): Promise<void> {
+    try {
+      await this.native.discard();
+    } catch (err) {
+      this.handleNativeError(err, 'discard');
+      throw err;
+    }
+  }
+
+  async release(): Promise<void> {
+    try {
+      this.native.removeAllListeners();
+      await this.native.release();
+    } finally {
+      this.listenerIds.length = 0;
+      this.emitter.removeAll();
+      this.currentState = 'released';
+    }
+  }
+
+  private buildNativeConfig(): NativeRecorderConfig {
+    const format = DEFAULT_AUDIO_FORMAT;
+    const cfg: NativeRecorderConfig = {
+      sampleRate: format.sampleRate,
+      channels: format.channels,
+      bitDepth: format.bitDepth,
+      emitAudioLevel: this.options.emitAudioLevel ?? false,
+      audioLevelIntervalMs:
+        this.options.audioLevelIntervalMs ?? DEFAULT_AUDIO_LEVEL_INTERVAL_MS,
+      aacBitrate: this.options.aacBitrate ?? DEFAULT_AAC_BITRATE,
+    };
+    if (this.options.outputDirectory !== undefined) {
+      cfg.outputDirectory = this.options.outputDirectory;
+    }
+    if (this.options.filenamePrefix !== undefined) {
+      cfg.filenamePrefix = this.options.filenamePrefix;
+    }
+    if (this.options.rotateAfterMs !== undefined) {
+      cfg.rotateAfterMs = this.options.rotateAfterMs;
+    }
+    return cfg;
+  }
+
+  private bindNativeListeners(): void {
+    this.listenerIds.push(
+      this.native.addStateListener((nativeState) => {
+        if (!isEngineState(nativeState)) return;
+        this.setState(nativeState);
+      }),
+    );
+
+    this.listenerIds.push(
+      this.native.addAudioLevelListener((rms, peak) => {
+        this.emitter.emit({ type: 'audio-level', rms, peak });
+      }),
+    );
+
+    this.listenerIds.push(
+      this.native.addChunkListener((uri, startMs, endMs, sizeBytes) => {
+        this.emitter.emit({
+          type: 'chunk',
+          uri,
+          startMs,
+          endMs,
+          sizeBytes,
+        });
+      }),
+    );
+
+    this.listenerIds.push(
+      this.native.addErrorListener((err) => {
+        this.emitter.emit({
+          type: 'error',
+          error: this.toClarionError(err),
+        });
+      }),
+    );
+  }
+
+  private transitionTo(next: EngineState): void {
+    if (this.currentState === next) return;
+    assertTransition(this.currentState, next);
+    this.setState(next);
+  }
+
+  private setState(next: EngineState): void {
+    if (this.currentState === next) return;
+    this.currentState = next;
+    this.emitter.emit({ type: 'state', state: next });
+  }
+
+  private toRecorderResult(r: NativeRecorderResult): RecorderResult {
+    return {
+      uri: r.uri,
+      durationMs: r.durationMs,
+      sizeBytes: r.sizeBytes,
+      container: 'm4a',
+      audioFormat: {
+        sampleRate: r.sampleRate as RecorderResult['audioFormat']['sampleRate'],
+        channels: r.channels as RecorderResult['audioFormat']['channels'],
+        bitDepth: r.bitDepth as RecorderResult['audioFormat']['bitDepth'],
+      },
+    };
+  }
+
+  private toClarionError(err: NativeRecorderError): ClarionError {
+    return new ClarionError({
+      code: this.mapErrorCode(err.code),
+      message: err.message,
+      recoverable: err.recoverable,
+    });
+  }
+
+  private mapErrorCode(
+    code: string,
+  ): ClarionError['code'] {
+    const known: Record<string, ClarionError['code']> = {
+      PERMISSION_DENIED: 'PERMISSION_DENIED',
+      AUDIO_BUSY: 'AUDIO_BUSY',
+      IO_ERROR: 'IO_ERROR',
+      INTERRUPTED: 'INTERRUPTED',
+      CANCELLED: 'CANCELLED',
+      ENGINE_NOT_READY: 'ENGINE_NOT_READY',
+      INVALID_STATE: 'INVALID_STATE',
+      UNSUPPORTED_FORMAT: 'UNSUPPORTED_FORMAT',
+      INTERNAL_ERROR: 'INTERNAL_ERROR',
+    };
+    return known[code] ?? 'UNKNOWN';
+  }
+
+  private handleNativeError(err: unknown, where: string): void {
+    const error =
+      err instanceof ClarionError
+        ? err
+        : new ClarionError({
+            code: 'INTERNAL_ERROR',
+            message: `Recorder ${where} failed: ${String(err)}`,
+            cause: err,
+          });
+    this.emitter.emit({ type: 'error', error });
+    this.setState('error');
+  }
+}