@clarionhq/recorder 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clarion
+
+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,110 @@
+# @clarionhq/recorder
+
+React Native microphone capture → AAC `.m4a`. Built on the New Architecture with [Nitro Modules](https://nitro.margelo.com). 16 KB page-size compliant.
+
+```tsx
+import { RecorderEngine } from '@clarionhq/recorder';
+
+const engine = new RecorderEngine({ emitAudioLevel: true });
+engine.on(e => {
+  if (e.type === 'state') setState(e.state);
+  if (e.type === 'audio-level') setRms(e.rms);
+  if (e.type === 'recording-complete') console.log(e.result.uri);
+});
+
+await engine.start();   // permission, prepare and record — one call
+// later…
+await engine.stop();    // finalizes the m4a and resets to `idle`
+```
+
+## Install
+
+```sh
+pnpm add @clarionhq/recorder @clarionhq/core react-native-nitro-modules
+cd ios && pod install
+```
+
+## Requirements
+
+| | |
+|---|---|
+| React Native | 0.77+ with New Architecture + Hermes |
+| Android | API 26+ |
+| iOS | 15.1+ |
+| Expo | bare workflow only (prebuild) |
+
+## Permissions
+
+**Android** — `RECORD_AUDIO` is auto-merged into your manifest. Request at runtime:
+
+```tsx
+await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.RECORD_AUDIO);
+```
+
+**iOS** — add `NSMicrophoneUsageDescription` to `Info.plist`. The library prompts the user automatically on first `start()`.
+
+## API
+
+### `new RecorderEngine(options?)`
+
+```ts
+type RecorderEngineOptions = {
+  outputDirectory?: string;       // default: app cache dir / 'clarion-recorder'
+  filenamePrefix?: string;        // default: 'clarion'
+  rotateAfterMs?: number;         // split into chunks every N ms
+  emitAudioLevel?: boolean;       // default: false
+  audioLevelIntervalMs?: number;  // default: 50
+  aacBitrate?: number;            // default: 32_000
+};
+```
+
+### Lifecycle
+
+| Method | Behavior |
+|---|---|
+| `start()` | Begin recording. Auto-handles permission + `prepare()` from `idle`/`error`. |
+| `pause()` / `resume()` | Gapless pause — audio session stays warm. |
+| `stop()` | Finalize the m4a → fire `recording-complete` → state → `idle`. |
+| `discard()` | Abort and delete the partial file → state → `idle`. |
+| `release()` | Permanently dispose. Engine cannot be reused after this. |
+| `prepare()` | Optional. Pre-warm the audio session before showing your record UI. |
+
+### Events
+
+```ts
+type ClarionEvent =
+  | { type: 'state'; state: EngineState }
+  | { type: 'audio-level'; rms: number; peak: number }   // 0..1 linear (not dB)
+  | { type: 'chunk'; uri: string; startMs: number; endMs: number; sizeBytes: number }
+  | { type: 'recording-complete'; result: RecorderResult }
+  | { type: 'error'; error: ClarionError };
+```
+
+States: `idle → preparing → ready → starting → recording → paused → stopping → idle`, plus `error` and `released` as terminals. Method calls from invalid states throw `ClarionError({ code: 'INVALID_STATE' })`; runtime errors arrive via the `error` event. See [`@clarionhq/core/errors`](https://github.com/Th4nderG0d/clarion/blob/main/packages/core/src/errors.ts) for the full code list.
+
+### React cleanup
+
+```tsx
+useEffect(() => {
+  const engine = new RecorderEngine();
+  const off = engine.on(handle);
+  return () => { off(); engine.release(); };   // important — frees the mic
+}, []);
+```
+
+## Limitations
+
+- **No background recording.** App suspending mid-recording will truncate the file. Callers who need background must configure `UIBackgroundModes: audio` (iOS) + a foreground service (Android) themselves; opt-in support may land in v0.2.
+- **No playback.** Use [`expo-av`](https://docs.expo.dev/versions/latest/sdk/audio/) or [`react-native-track-player`](https://rntp.dev) — Clarion produces m4a files that play cleanly in both.
+- **No managed Expo support.** Bare workflow / prebuild only until a config plugin ships.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| iOS build: `fmt` library `consteval` errors on Xcode 26 | Add `FMT_USE_CONSTEVAL=0` patch to your `Podfile` post_install (see `example/ios/Podfile` in the repo). |
+| `PERMISSION_DENIED` fires repeatedly | iOS: confirm `NSMicrophoneUsageDescription` is in Info.plist. Android: confirm `PermissionsAndroid.request(RECORD_AUDIO)` returned `granted` before calling `start()`. |
+
+## License
+
+MIT

package/android/CMakeLists.txt

@@ -0,0 +1,9 @@
+project(ClarionRecorder)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+add_library(${PROJECT_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/ClarionRecorder+autolinking.cmake)

package/android/build.gradle

@@ -0,0 +1,97 @@
+buildscript {
+  ext.getExtOrDefault = { name ->
+    return rootProject.ext.has(name)
+      ? rootProject.ext.get(name)
+      : project.properties["ClarionRecorder_" + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply from: "../nitrogen/generated/android/ClarionRecorder+autolinking.gradle"
+
+android {
+  namespace "com.clarionhq.recorder"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion").toInteger()
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion").toInteger()
+    targetSdkVersion getExtOrDefault("targetSdkVersion").toInteger()
+    consumerProguardFiles "proguard-rules.pro"
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-O2 -frtti -fexceptions -Wall -Wno-unused-variable -fstack-protector-all"
+        // -Wl,-z,max-page-size=16384 makes the produced .so 16 KB page-aligned —
+        // required by Google Play for new Android 15+ uploads.
+        arguments "-DANDROID_STL=c++_shared",
+                  "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON",
+                  "-DCMAKE_SHARED_LINKER_FLAGS=-Wl,-z,max-page-size=16384"
+        abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  buildFeatures {
+    buildConfig false
+    prefab true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  sourceSets {
+    main {
+      manifest.srcFile "src/main/AndroidManifest.xml"
+      java.srcDirs += [
+        "src/main/java",
+        "$projectDir/../nitrogen/generated/android/kotlin",
+      ]
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF/DEPENDENCIES",
+      "META-INF/LICENSE",
+      "META-INF/LICENSE.txt",
+      "META-INF/NOTICE",
+      "META-INF/NOTICE.txt"
+    ]
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation project(":react-native-nitro-modules")
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"
+}

package/android/gradle.properties

@@ -0,0 +1,4 @@
+ClarionRecorder_kotlinVersion=2.0.21
+ClarionRecorder_minSdkVersion=26
+ClarionRecorder_targetSdkVersion=35
+ClarionRecorder_compileSdkVersion=35

package/android/proguard-rules.pro

@@ -0,0 +1 @@
+-keep class com.clarionhq.recorder.** { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.RECORD_AUDIO" />
+  <uses-feature android:name="android.hardware.microphone" android:required="false" />
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,7 @@
+#include <jni.h>
+#include <fbjni/fbjni.h>
+#include "ClarionRecorderOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* /*reserved*/) {
+  return margelo::nitro::clarion::recorder::initialize(vm);
+}

package/android/src/main/java/com/clarionhq/recorder/AudioLevelMeter.kt

@@ -0,0 +1,38 @@
+package com.clarionhq.recorder
+
+import kotlin.math.abs
+import kotlin.math.min
+import kotlin.math.sqrt
+
+internal data class AudioLevels(val rms: Double, val peak: Double)
+
+internal object AudioLevelMeter {
+  private const val PCM_16_MAX = 32_768.0
+
+  fun compute(pcm: ByteArray, length: Int): AudioLevels {
+    if (length < 2) return AudioLevels(0.0, 0.0)
+
+    val sampleCount = length / 2
+    var sumSquares = 0.0
+    var peakAbs = 0
+
+    var i = 0
+    while (i < length - 1) {
+      val low = pcm[i].toInt() and 0xFF
+      val high = pcm[i + 1].toInt()
+      val sample = (high shl 8) or low
+      val signed = if (sample > 32_767) sample - 65_536 else sample
+
+      val abs = abs(signed)
+      if (abs > peakAbs) peakAbs = abs
+
+      val normalized = signed.toDouble()
+      sumSquares += normalized * normalized
+      i += 2
+    }
+
+    val rms = sqrt(sumSquares / sampleCount) / PCM_16_MAX
+    val peak = peakAbs.toDouble() / PCM_16_MAX
+    return AudioLevels(min(rms, 1.0), min(peak, 1.0))
+  }
+}

package/android/src/main/java/com/clarionhq/recorder/ClarionRecorderPackage.kt

@@ -0,0 +1,27 @@
+package com.clarionhq.recorder
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+import com.margelo.nitro.clarion.recorder.ClarionRecorderOnLoad
+
+/**
+ * Stub ReactPackage so React Native's autolinker discovers this library.
+ * Nitro registers the actual HybridObject via JNI inside the C++ library — this
+ * class triggers the System.loadLibrary call (idempotent) at startup so the
+ * registration runs before any JS code calls `createHybridObject('ClarionRecorder')`.
+ */
+class ClarionRecorderPackage : ReactPackage {
+  init {
+    ClarionRecorderOnLoad.initializeNative()
+  }
+
+  override fun createNativeModules(
+    reactContext: ReactApplicationContext,
+  ): List<NativeModule> = emptyList()
+
+  override fun createViewManagers(
+    reactContext: ReactApplicationContext,
+  ): List<ViewManager<*, *>> = emptyList()
+}

package/android/src/main/java/com/clarionhq/recorder/EncodeFile.kt

@@ -0,0 +1,62 @@
+package com.clarionhq.recorder
+
+import android.media.MediaCodec
+import android.media.MediaCodecInfo
+import android.media.MediaFormat
+import android.media.MediaMuxer
+import java.io.File
+import java.util.UUID
+
+internal class EncodeFile private constructor(
+  val path: String,
+  val codec: MediaCodec,
+  val muxer: MediaMuxer,
+) {
+  var muxerTrackIndex: Int = -1
+  var muxerStarted: Boolean = false
+  var bytesWritten: Long = 0L
+
+  fun close() {
+    runCatching { codec.stop() }
+    runCatching { codec.release() }
+    runCatching { if (muxerStarted) muxer.stop() }
+    runCatching { muxer.release() }
+  }
+
+  companion object {
+    fun open(
+      outputDir: File,
+      filenamePrefix: String,
+      sampleRate: Int,
+      channels: Int,
+      aacBitrate: Int,
+      maxInputSize: Int,
+    ): EncodeFile {
+      if (!outputDir.exists()) outputDir.mkdirs()
+
+      val file = File(
+        outputDir,
+        "$filenamePrefix-${UUID.randomUUID()}.${RecorderConstants.OUTPUT_EXTENSION}",
+      )
+
+      val format = MediaFormat.createAudioFormat(
+        MediaFormat.MIMETYPE_AUDIO_AAC,
+        sampleRate,
+        channels,
+      ).apply {
+        setInteger(MediaFormat.KEY_AAC_PROFILE, MediaCodecInfo.CodecProfileLevel.AACObjectLC)
+        setInteger(MediaFormat.KEY_BIT_RATE, aacBitrate)
+        setInteger(MediaFormat.KEY_MAX_INPUT_SIZE, maxInputSize)
+      }
+
+      val codec = MediaCodec.createEncoderByType(MediaFormat.MIMETYPE_AUDIO_AAC).apply {
+        configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
+        start()
+      }
+
+      val muxer = MediaMuxer(file.absolutePath, MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4)
+
+      return EncodeFile(path = file.absolutePath, codec = codec, muxer = muxer)
+    }
+  }
+}

package/android/src/main/java/com/clarionhq/recorder/RecorderConfig.kt

@@ -0,0 +1,33 @@
+package com.clarionhq.recorder
+
+internal data class RecorderConfig(
+  val sampleRate: Int,
+  val channels: Int,
+  val bitDepth: Int,
+  val outputDirectory: String?,
+  val filenamePrefix: String?,
+  val rotateAfterMs: Long?,
+  val emitAudioLevel: Boolean,
+  val audioLevelIntervalMs: Int,
+  val aacBitrate: Int,
+) {
+  init {
+    require(sampleRate in setOf(8_000, 16_000, 22_050, 44_100, 48_000)) {
+      "Unsupported sample rate: $sampleRate"
+    }
+    require(channels in 1..2) { "Channels must be 1 or 2, got $channels" }
+    require(bitDepth == 16) { "Only 16-bit PCM is supported (got $bitDepth)" }
+    require(aacBitrate in 16_000..256_000) { "AAC bitrate out of range: $aacBitrate" }
+    require(audioLevelIntervalMs >= 10) { "audioLevelIntervalMs too low: $audioLevelIntervalMs" }
+    rotateAfterMs?.let { require(it >= 1_000) { "rotateAfterMs must be >= 1000ms" } }
+  }
+}
+
+internal data class RecorderResult(
+  val uri: String,
+  val durationMs: Long,
+  val sizeBytes: Long,
+  val sampleRate: Int,
+  val channels: Int,
+  val bitDepth: Int,
+)

package/android/src/main/java/com/clarionhq/recorder/RecorderConstants.kt

@@ -0,0 +1,16 @@
+package com.clarionhq.recorder
+
+internal object RecorderConstants {
+  const val CODEC_DEQUEUE_TIMEOUT_US = 10_000L
+  const val PCM_QUEUE_POLL_TIMEOUT_MS = 200L
+  const val ENCODE_THREAD_JOIN_TIMEOUT_MS = 3_000L
+  const val CAPTURE_THREAD_JOIN_TIMEOUT_MS = 1_000L
+  const val CANCEL_ENCODE_JOIN_TIMEOUT_MS = 1_000L
+  const val CANCEL_CAPTURE_JOIN_TIMEOUT_MS = 500L
+  const val PCM_QUEUE_CAPACITY = 128
+  const val CAPTURE_BUFFER_FRACTION_OF_SECOND = 5
+  const val DEFAULT_CACHE_SUBDIR = "clarion-recorder"
+  const val DEFAULT_FILENAME_PREFIX = "clarion"
+  const val OUTPUT_EXTENSION = "m4a"
+  const val URI_SCHEME = "file://"
+}