@moodbar/native 0.2.0

package/LICENSE-APACHE

@@ -0,0 +1,193 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and its Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the Work,
+      and to permit persons to whom the Work is furnished to do so,
+      subject to the following conditions:
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the format in question.
+
+   Copyright 2026 Gil Desmarais
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gil Desmarais
+
+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,30 @@
+# @moodbar/native
+
+React Native bindings for Moodbar analysis and rendering (PNG/SVG) on iOS and Android.
+
+## Install
+
+```bash
+npm install @moodbar/native
+```
+
+## Usage
+
+```ts
+import { analyze, render, generate } from "@moodbar/native";
+
+const analysis = await analyze({ uri: "file:///path/to/input.mp3" });
+const pngBytes = await render(analysis, "png", { width: 1200, height: 96 });
+const svg = await render(analysis, "svg", { width: 1200, height: 96, shape: "Waveform" });
+
+await analysis.dispose();
+
+const fromMemory = await generate(
+  { bytes: new Uint8Array([/* encoded audio bytes */]) },
+  "png"
+);
+```
+
+`analyze({ uri })` accepts:
+- iOS: file paths and `file://` URIs
+- Android: file paths, `file://` URIs, and `content://` URIs

package/android/build.gradle

@@ -0,0 +1,35 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+group = 'expo.modules.moodbarnative'
+version = '0.0.0'
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+apply from: new File(project(':expo-modules-core').projectDir, 'ExpoModulesCorePlugin.gradle')
+
+android {
+  namespace "expo.modules.moodbarnative"
+  compileSdkVersion safeExtGet('compileSdkVersion', 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 24)
+    targetSdkVersion safeExtGet('targetSdkVersion', 35)
+  }
+
+  sourceSets {
+    main {
+      jniLibs.srcDirs = ['src/main/jniLibs']
+    }
+  }
+
+  lintOptions {
+    abortOnError false
+  }
+}
+
+dependencies {
+  implementation project(':expo-modules-core')
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/include/moodbar_native_ffi.h

@@ -0,0 +1,66 @@
+#ifndef MOODBAR_NATIVE_FFI_H
+#define MOODBAR_NATIVE_FFI_H
+
+#pragma once
+
+/* This file is generated by cbindgen. */
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+enum MoodbarNativeStatus {
+  Ok = 0,
+  InvalidArgument = 1,
+  NotFound = 2,
+  Internal = 3,
+};
+typedef int32_t MoodbarNativeStatus;
+
+typedef struct MoodbarNativeAnalysisSummary {
+  uint64_t handle;
+  uint32_t frame_count;
+  uint32_t channel_count;
+} MoodbarNativeAnalysisSummary;
+
+typedef struct MoodbarNativeBuffer {
+  uint8_t *ptr;
+  size_t len;
+  size_t cap;
+} MoodbarNativeBuffer;
+
+MoodbarNativeStatus moodbar_native_analysis_from_path(const char *path,
+                                                      const char *options_json,
+                                                      struct MoodbarNativeAnalysisSummary *out_summary);
+
+MoodbarNativeStatus moodbar_native_analysis_from_bytes(const uint8_t *bytes,
+                                                       size_t bytes_len,
+                                                       const char *extension,
+                                                       const char *options_json,
+                                                       struct MoodbarNativeAnalysisSummary *out_summary);
+
+MoodbarNativeStatus moodbar_native_analysis_dispose(uint64_t handle);
+
+MoodbarNativeStatus moodbar_native_render_svg(uint64_t handle,
+                                              const char *options_json,
+                                              struct MoodbarNativeBuffer *out_svg_utf8);
+
+MoodbarNativeStatus moodbar_native_render_png(uint64_t handle,
+                                              const char *options_json,
+                                              struct MoodbarNativeBuffer *out_png);
+
+MoodbarNativeStatus moodbar_native_last_error(struct MoodbarNativeBuffer *out_message_utf8);
+
+/**
+ * Frees a heap buffer previously returned by this library.
+ *
+ * # Safety
+ *
+ * `buffer` must be a valid, writable pointer obtained from this library, and must not be
+ * freed more than once.
+ */
+void moodbar_native_buffer_free(struct MoodbarNativeBuffer *buffer);
+
+#endif  /* MOODBAR_NATIVE_FFI_H */

package/android/src/main/java/expo/modules/moodbarnative/MoodbarNativeModule.kt

@@ -0,0 +1,96 @@
+package expo.modules.moodbarnative
+
+import android.net.Uri
+import android.util.Base64
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import org.json.JSONObject
+
+class MoodbarNativeModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("MoodbarNative")
+
+    AsyncFunction("analyzeFromUri") { uri: String, optionsJson: String ->
+      val payload = parseResponse(analyzeUri(uri, optionsJson))
+      mapOf(
+        "handle" to payload.getLong("handle"),
+        "frameCount" to payload.getInt("frameCount"),
+        "channelCount" to payload.getInt("channelCount"),
+      )
+    }
+
+    AsyncFunction("analyzeFromBase64") { base64: String, extension: String?, optionsJson: String ->
+      val bytes = try {
+        Base64.decode(base64, Base64.DEFAULT)
+      } catch (error: IllegalArgumentException) {
+        throw CodedException("ERR_INVALID_BASE64", "input bytes were not valid base64", error)
+      }
+
+      val payload = parseResponse(NativeBridge.nativeAnalyzeFromBytes(bytes, extension, optionsJson))
+      mapOf(
+        "handle" to payload.getLong("handle"),
+        "frameCount" to payload.getInt("frameCount"),
+        "channelCount" to payload.getInt("channelCount"),
+      )
+    }
+
+    AsyncFunction("renderSvg") { handle: Long, optionsJson: String ->
+      val payload = parseResponse(NativeBridge.nativeRenderSvg(handle, optionsJson))
+      payload.getString("svg")
+    }
+
+    AsyncFunction("renderPng") { handle: Long, optionsJson: String ->
+      val payload = parseResponse(NativeBridge.nativeRenderPng(handle, optionsJson))
+      payload.getString("pngBase64")
+    }
+
+    AsyncFunction("disposeAnalysis") { handle: Long ->
+      parseResponse(NativeBridge.nativeDisposeAnalysis(handle))
+      null
+    }
+  }
+
+  private fun analyzeUri(uri: String, optionsJson: String): String {
+    val parsed = Uri.parse(uri)
+    return when (parsed.scheme?.lowercase()) {
+      "content" -> {
+        val context = appContext.reactContext
+          ?: throw CodedException("ERR_CONTEXT_UNAVAILABLE", "React context is unavailable for content URI decode")
+        val bytes = context.contentResolver.openInputStream(parsed)?.use { it.readBytes() }
+          ?: throw CodedException("ERR_URI_READ_FAILED", "could not read content URI: $uri")
+        val extension = inferExtension(parsed)
+        NativeBridge.nativeAnalyzeFromBytes(bytes, extension, optionsJson)
+      }
+      null, "", "file" -> {
+        val path = parsed.path
+          ?: throw CodedException("ERR_INVALID_URI", "file URI is missing a path: $uri")
+        NativeBridge.nativeAnalyzeFromUri(path, optionsJson)
+      }
+      else -> throw CodedException(
+        "ERR_UNSUPPORTED_URI_SCHEME",
+        "unsupported URI scheme '${parsed.scheme}': only file:// and content:// are supported on Android"
+      )
+    }
+  }
+
+  private fun inferExtension(uri: Uri): String? {
+    val segment = uri.lastPathSegment ?: return null
+    val idx = segment.lastIndexOf('.')
+    if (idx < 0 || idx == segment.length - 1) {
+      return null
+    }
+    return segment.substring(idx + 1).lowercase()
+  }
+
+  private fun parseResponse(raw: String): JSONObject {
+    val payload = JSONObject(raw)
+    if (!payload.optBoolean("ok", false)) {
+      throw CodedException(
+        "ERR_MOODBAR_NATIVE",
+        payload.optString("error", "native moodbar call failed")
+      )
+    }
+    return payload
+  }
+}

package/android/src/main/java/expo/modules/moodbarnative/NativeBridge.kt

@@ -0,0 +1,13 @@
+package expo.modules.moodbarnative
+
+object NativeBridge {
+  init {
+    System.loadLibrary("moodbar_native_ffi")
+  }
+
+  external fun nativeAnalyzeFromUri(uri: String, optionsJson: String): String
+  external fun nativeAnalyzeFromBytes(bytes: ByteArray, extension: String?, optionsJson: String): String
+  external fun nativeRenderSvg(handle: Long, optionsJson: String): String
+  external fun nativeRenderPng(handle: Long, optionsJson: String): String
+  external fun nativeDisposeAnalysis(handle: Long): String
+}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android"],
+  "apple": {
+    "modules": ["MoodbarNativeModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.moodbarnative.MoodbarNativeModule"]
+  }
+}

package/index.d.ts

@@ -0,0 +1,62 @@
+export type NormalizeMode = "PerChannelPeak" | "GlobalPeak";
+export type DetectionMode = "SpectralEnergy" | "SpectralFlux";
+export type SvgShape = "Strip" | "Waveform";
+
+export interface AnalyzeOptions {
+  fft_size?: number;
+  low_cut_hz?: number;
+  mid_cut_hz?: number;
+  normalize_mode?: NormalizeMode;
+  deterministic_floor?: number;
+  detection_mode?: DetectionMode;
+  frames_per_color?: number;
+  band_edges_hz?: number[];
+}
+
+export interface RenderOptions {
+  width?: number;
+  height?: number;
+  shape?: SvgShape;
+  background?: "transparent" | "black" | "white" | "none";
+  max_gradient_stops?: number;
+}
+
+export type MoodbarInput =
+  | { uri: string }
+  | { bytes: Uint8Array; name?: string; mimeType?: string };
+
+export interface MoodbarAnalysis {
+  readonly frameCount: number;
+  readonly channelCount: number;
+  readonly disposed: boolean;
+  dispose(): Promise<void>;
+}
+
+export function analyze(
+  input: MoodbarInput,
+  options?: AnalyzeOptions
+): Promise<MoodbarAnalysis>;
+
+export function render(
+  analysis: MoodbarAnalysis,
+  format: "png",
+  options?: RenderOptions
+): Promise<Uint8Array>;
+export function render(
+  analysis: MoodbarAnalysis,
+  format: "svg",
+  options?: RenderOptions
+): Promise<string>;
+
+export function generate(
+  input: MoodbarInput,
+  format: "png",
+  options?: AnalyzeOptions & RenderOptions
+): Promise<Uint8Array>;
+export function generate(
+  input: MoodbarInput,
+  format: "svg",
+  options?: AnalyzeOptions & RenderOptions
+): Promise<string>;
+
+export function disposeAnalysis(analysis: MoodbarAnalysis): Promise<void>;

package/index.js

@@ -0,0 +1,177 @@
+const { requireNativeModule } = require("expo-modules-core");
+
+const Native = requireNativeModule("MoodbarNative");
+const finalizer =
+  typeof FinalizationRegistry === "function"
+    ? new FinalizationRegistry((handle) => {
+        Native.disposeAnalysis(handle).catch(() => {});
+      })
+    : null;
+
+class NativeAnalysis {
+  constructor(handle, frameCount, channelCount) {
+    this.__nativeHandle = handle;
+    this.frameCount = frameCount;
+    this.channelCount = channelCount;
+    this.disposed = false;
+
+    if (finalizer) {
+      finalizer.register(this, handle, this);
+    }
+  }
+
+  async dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    if (finalizer) {
+      finalizer.unregister(this);
+    }
+    await Native.disposeAnalysis(this.__nativeHandle);
+  }
+}
+
+function assertAnalysis(analysis) {
+  if (!(analysis instanceof NativeAnalysis)) {
+    throw new TypeError("analysis must be returned by analyze() from @moodbar/native");
+  }
+  if (analysis.disposed) {
+    throw new Error("analysis handle has already been disposed");
+  }
+}
+
+function stringifyOptions(options) {
+  if (!options) {
+    return "{}";
+  }
+  return JSON.stringify(options);
+}
+
+function inferExtension(name, mimeType) {
+  if (typeof name === "string") {
+    const match = name.match(/\.([A-Za-z0-9]+)$/);
+    if (match) {
+      return match[1].toLowerCase();
+    }
+  }
+
+  if (typeof mimeType === "string") {
+    const slash = mimeType.indexOf("/");
+    if (slash >= 0 && slash < mimeType.length - 1) {
+      return mimeType.slice(slash + 1).toLowerCase();
+    }
+  }
+
+  return null;
+}
+
+const BASE64_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const BASE64_REVERSE = (() => {
+  const out = new Uint8Array(256);
+  out.fill(255);
+  for (let i = 0; i < BASE64_ALPHABET.length; i += 1) {
+    out[BASE64_ALPHABET.charCodeAt(i)] = i;
+  }
+  out["=".charCodeAt(0)] = 0;
+  return out;
+})();
+
+function bytesToBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i];
+    const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    const triple = (a << 16) | (b << 8) | c;
+
+    out += BASE64_ALPHABET[(triple >> 18) & 63];
+    out += BASE64_ALPHABET[(triple >> 12) & 63];
+    out += i + 1 < bytes.length ? BASE64_ALPHABET[(triple >> 6) & 63] : "=";
+    out += i + 2 < bytes.length ? BASE64_ALPHABET[triple & 63] : "=";
+  }
+  return out;
+}
+
+function base64ToBytes(base64) {
+  const clean = base64.replace(/\s+/g, "");
+  if (clean.length % 4 !== 0) {
+    throw new Error("invalid base64 payload from native renderPng");
+  }
+
+  const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
+  const outLen = (clean.length / 4) * 3 - padding;
+  const out = new Uint8Array(outLen);
+  let outIdx = 0;
+
+  for (let i = 0; i < clean.length; i += 4) {
+    const c0 = BASE64_REVERSE[clean.charCodeAt(i)];
+    const c1 = BASE64_REVERSE[clean.charCodeAt(i + 1)];
+    const c2 = BASE64_REVERSE[clean.charCodeAt(i + 2)];
+    const c3 = BASE64_REVERSE[clean.charCodeAt(i + 3)];
+    if (c0 === 255 || c1 === 255 || c2 === 255 || c3 === 255) {
+      throw new Error("invalid base64 payload from native renderPng");
+    }
+
+    const triple = (c0 << 18) | (c1 << 12) | (c2 << 6) | c3;
+    if (outIdx < outLen) out[outIdx++] = (triple >> 16) & 255;
+    if (outIdx < outLen) out[outIdx++] = (triple >> 8) & 255;
+    if (outIdx < outLen) out[outIdx++] = triple & 255;
+  }
+
+  return out;
+}
+
+async function analyze(input, options) {
+  const optionsJson = stringifyOptions(options);
+
+  if (input && typeof input.uri === "string") {
+    const result = await Native.analyzeFromUri(input.uri, optionsJson);
+    return new NativeAnalysis(result.handle, result.frameCount, result.channelCount);
+  }
+
+  if (input && input.bytes instanceof Uint8Array) {
+    const extension = inferExtension(input.name, input.mimeType);
+    const base64 = bytesToBase64(input.bytes);
+    const result = await Native.analyzeFromBase64(base64, extension, optionsJson);
+    return new NativeAnalysis(result.handle, result.frameCount, result.channelCount);
+  }
+
+  throw new TypeError("input must be { uri: string } or { bytes: Uint8Array }");
+}
+
+async function render(analysis, format, options) {
+  assertAnalysis(analysis);
+
+  const optionsJson = stringifyOptions(options);
+  if (format === "png") {
+    const pngBase64 = await Native.renderPng(analysis.__nativeHandle, optionsJson);
+    return base64ToBytes(pngBase64);
+  }
+  if (format === "svg") {
+    return Native.renderSvg(analysis.__nativeHandle, optionsJson);
+  }
+  throw new TypeError('format must be "png" or "svg"');
+}
+
+async function generate(input, format, options) {
+  const analysis = await analyze(input, options);
+  try {
+    return await render(analysis, format, options);
+  } finally {
+    await analysis.dispose();
+  }
+}
+
+async function disposeAnalysis(analysis) {
+  assertAnalysis(analysis);
+  await analysis.dispose();
+}
+
+module.exports = {
+  analyze,
+  render,
+  generate,
+  disposeAnalysis,
+};

package/ios/MoodbarNativeFFI.xcframework/Info.plist

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AvailableLibraries</key>
+	<array>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libmoodbar_native_ffi.a</string>
+			<key>HeadersPath</key>
+			<string>Headers</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64</string>
+			<key>LibraryPath</key>
+			<string>libmoodbar_native_ffi.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+		</dict>
+		<dict>
+			<key>BinaryPath</key>
+			<string>libmoodbar_native_ffi_simulator.a</string>
+			<key>HeadersPath</key>
+			<string>Headers</string>
+			<key>LibraryIdentifier</key>
+			<string>ios-arm64_x86_64-simulator</string>
+			<key>LibraryPath</key>
+			<string>libmoodbar_native_ffi_simulator.a</string>
+			<key>SupportedArchitectures</key>
+			<array>
+				<string>arm64</string>
+				<string>x86_64</string>
+			</array>
+			<key>SupportedPlatform</key>
+			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
+		</dict>
+	</array>
+	<key>CFBundlePackageType</key>
+	<string>XFWK</string>
+	<key>XCFrameworkFormatVersion</key>
+	<string>1.0</string>
+</dict>
+</plist>

package/ios/MoodbarNativeFFI.xcframework/ios-arm64/Headers/MoodbarNativeFFI.h

@@ -0,0 +1 @@
+#include "moodbar_native_ffi.h"

package/ios/MoodbarNativeFFI.xcframework/ios-arm64/Headers/moodbar_native_ffi.h

@@ -0,0 +1,66 @@
+#ifndef MOODBAR_NATIVE_FFI_H
+#define MOODBAR_NATIVE_FFI_H
+
+#pragma once
+
+/* This file is generated by cbindgen. */
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+enum MoodbarNativeStatus {
+  Ok = 0,
+  InvalidArgument = 1,
+  NotFound = 2,
+  Internal = 3,
+};
+typedef int32_t MoodbarNativeStatus;
+
+typedef struct MoodbarNativeAnalysisSummary {
+  uint64_t handle;
+  uint32_t frame_count;
+  uint32_t channel_count;
+} MoodbarNativeAnalysisSummary;
+
+typedef struct MoodbarNativeBuffer {
+  uint8_t *ptr;
+  size_t len;
+  size_t cap;
+} MoodbarNativeBuffer;
+
+MoodbarNativeStatus moodbar_native_analysis_from_path(const char *path,
+                                                      const char *options_json,
+                                                      struct MoodbarNativeAnalysisSummary *out_summary);
+
+MoodbarNativeStatus moodbar_native_analysis_from_bytes(const uint8_t *bytes,
+                                                       size_t bytes_len,
+                                                       const char *extension,
+                                                       const char *options_json,
+                                                       struct MoodbarNativeAnalysisSummary *out_summary);
+
+MoodbarNativeStatus moodbar_native_analysis_dispose(uint64_t handle);
+
+MoodbarNativeStatus moodbar_native_render_svg(uint64_t handle,
+                                              const char *options_json,
+                                              struct MoodbarNativeBuffer *out_svg_utf8);
+
+MoodbarNativeStatus moodbar_native_render_png(uint64_t handle,
+                                              const char *options_json,
+                                              struct MoodbarNativeBuffer *out_png);
+
+MoodbarNativeStatus moodbar_native_last_error(struct MoodbarNativeBuffer *out_message_utf8);
+
+/**
+ * Frees a heap buffer previously returned by this library.
+ *
+ * # Safety
+ *
+ * `buffer` must be a valid, writable pointer obtained from this library, and must not be
+ * freed more than once.
+ */
+void moodbar_native_buffer_free(struct MoodbarNativeBuffer *buffer);
+
+#endif  /* MOODBAR_NATIVE_FFI_H */

package/ios/MoodbarNativeFFI.xcframework/ios-arm64_x86_64-simulator/Headers/MoodbarNativeFFI.h

@@ -0,0 +1 @@
+#include "moodbar_native_ffi.h"

package/ios/MoodbarNativeFFI.xcframework/ios-arm64_x86_64-simulator/Headers/moodbar_native_ffi.h

@@ -0,0 +1,66 @@
+#ifndef MOODBAR_NATIVE_FFI_H
+#define MOODBAR_NATIVE_FFI_H
+
+#pragma once
+
+/* This file is generated by cbindgen. */
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+enum MoodbarNativeStatus {
+  Ok = 0,
+  InvalidArgument = 1,
+  NotFound = 2,
+  Internal = 3,
+};
+typedef int32_t MoodbarNativeStatus;
+
+typedef struct MoodbarNativeAnalysisSummary {
+  uint64_t handle;
+  uint32_t frame_count;
+  uint32_t channel_count;
+} MoodbarNativeAnalysisSummary;
+
+typedef struct MoodbarNativeBuffer {
+  uint8_t *ptr;
+  size_t len;
+  size_t cap;
+} MoodbarNativeBuffer;
+
+MoodbarNativeStatus moodbar_native_analysis_from_path(const char *path,
+                                                      const char *options_json,
+                                                      struct MoodbarNativeAnalysisSummary *out_summary);
+
+MoodbarNativeStatus moodbar_native_analysis_from_bytes(const uint8_t *bytes,
+                                                       size_t bytes_len,
+                                                       const char *extension,
+                                                       const char *options_json,
+                                                       struct MoodbarNativeAnalysisSummary *out_summary);
+
+MoodbarNativeStatus moodbar_native_analysis_dispose(uint64_t handle);
+
+MoodbarNativeStatus moodbar_native_render_svg(uint64_t handle,
+                                              const char *options_json,
+                                              struct MoodbarNativeBuffer *out_svg_utf8);
+
+MoodbarNativeStatus moodbar_native_render_png(uint64_t handle,
+                                              const char *options_json,
+                                              struct MoodbarNativeBuffer *out_png);
+
+MoodbarNativeStatus moodbar_native_last_error(struct MoodbarNativeBuffer *out_message_utf8);
+
+/**
+ * Frees a heap buffer previously returned by this library.
+ *
+ * # Safety
+ *
+ * `buffer` must be a valid, writable pointer obtained from this library, and must not be
+ * freed more than once.
+ */
+void moodbar_native_buffer_free(struct MoodbarNativeBuffer *buffer);
+
+#endif  /* MOODBAR_NATIVE_FFI_H */

package/ios/MoodbarNativeModule.swift

@@ -0,0 +1,129 @@
+import ExpoModulesCore
+import Foundation
+
+public class MoodbarNativeModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("MoodbarNative")
+
+    AsyncFunction("analyzeFromUri") { (uri: String, optionsJson: String?) throws -> [String: Any] in
+      let resolvedPath = try self.resolvePath(from: uri)
+      var summary = MoodbarNativeAnalysisSummary(handle: 0, frame_count: 0, channel_count: 0)
+      let status = resolvedPath.withCString { pathPtr in
+        withOptionalCString(optionsJson) { optionsPtr in
+          moodbar_native_analysis_from_path(pathPtr, optionsPtr, &summary)
+        }
+      }
+      try throwIfNeeded(status)
+      return [
+        "handle": summary.handle,
+        "frameCount": Int(summary.frame_count),
+        "channelCount": Int(summary.channel_count),
+      ]
+    }
+
+    AsyncFunction("analyzeFromBase64") { (base64: String, fileExtension: String?, optionsJson: String?) throws -> [String: Any] in
+      guard let data = Data(base64Encoded: base64) else {
+        throw NSError(domain: "MoodbarNative", code: 1, userInfo: [NSLocalizedDescriptionKey: "input bytes were not valid base64"])
+      }
+
+      var summary = MoodbarNativeAnalysisSummary(handle: 0, frame_count: 0, channel_count: 0)
+      let status = data.withUnsafeBytes { rawBuffer in
+        let bytes = rawBuffer.bindMemory(to: UInt8.self).baseAddress
+        return withOptionalCString(fileExtension) { extensionPtr in
+          withOptionalCString(optionsJson) { optionsPtr in
+            moodbar_native_analysis_from_bytes(bytes, data.count, extensionPtr, optionsPtr, &summary)
+          }
+        }
+      }
+
+      try throwIfNeeded(status)
+      return [
+        "handle": summary.handle,
+        "frameCount": Int(summary.frame_count),
+        "channelCount": Int(summary.channel_count),
+      ]
+    }
+
+    AsyncFunction("renderSvg") { (handle: UInt64, optionsJson: String?) throws -> String in
+      var out = MoodbarNativeBuffer(ptr: nil, len: 0, cap: 0)
+      defer { moodbar_native_buffer_free(&out) }
+      let status = withOptionalCString(optionsJson) { optionsPtr in
+        moodbar_native_render_svg(handle, optionsPtr, &out)
+      }
+      try throwIfNeeded(status)
+
+      let data = consumeBuffer(out)
+      guard let svg = String(data: data, encoding: .utf8) else {
+        throw NSError(domain: "MoodbarNative", code: 3, userInfo: [NSLocalizedDescriptionKey: "native SVG payload was not UTF-8"])
+      }
+      return svg
+    }
+
+    AsyncFunction("renderPng") { (handle: UInt64, optionsJson: String?) throws -> String in
+      var out = MoodbarNativeBuffer(ptr: nil, len: 0, cap: 0)
+      defer { moodbar_native_buffer_free(&out) }
+      let status = withOptionalCString(optionsJson) { optionsPtr in
+        moodbar_native_render_png(handle, optionsPtr, &out)
+      }
+      try throwIfNeeded(status)
+
+      let data = consumeBuffer(out)
+      return data.base64EncodedString()
+    }
+
+    AsyncFunction("disposeAnalysis") { (handle: UInt64) throws -> Void in
+      let status = moodbar_native_analysis_dispose(handle)
+      try throwIfNeeded(status)
+    }
+  }
+
+  private func withOptionalCString<T>(_ value: String?, _ body: (UnsafePointer<CChar>?) -> T) -> T {
+    guard let value else {
+      return body(nil)
+    }
+    return value.withCString { cString in
+      body(cString)
+    }
+  }
+
+  private func throwIfNeeded(_ status: MoodbarNativeStatus) throws {
+    if status == 0 {
+      return
+    }
+
+    var out = MoodbarNativeBuffer(ptr: nil, len: 0, cap: 0)
+    _ = moodbar_native_last_error(&out)
+    defer { moodbar_native_buffer_free(&out) }
+
+    let data = consumeBuffer(out)
+    let message = String(data: data, encoding: .utf8) ?? "native moodbar call failed"
+    throw NSError(
+      domain: "MoodbarNative",
+      code: Int(status),
+      userInfo: [NSLocalizedDescriptionKey: message]
+    )
+  }
+
+  private func consumeBuffer(_ buffer: MoodbarNativeBuffer) -> Data {
+    guard let ptr = buffer.ptr else {
+      return Data()
+    }
+    return Data(bytes: ptr, count: buffer.len)
+  }
+
+  private func resolvePath(from uri: String) throws -> String {
+    guard let url = URL(string: uri), url.scheme != nil else {
+      return uri
+    }
+
+    if url.isFileURL {
+      return url.path
+    }
+
+    throw NSError(
+      domain: "MoodbarNative",
+      code: 4,
+      userInfo: [NSLocalizedDescriptionKey: "unsupported URI scheme for iOS: \(uri)"]
+    )
+  }
+}

package/ios/include/MoodbarNativeFFI.h

@@ -0,0 +1 @@
+#include "moodbar_native_ffi.h"

package/ios/include/moodbar_native_ffi.h

@@ -0,0 +1,66 @@
+#ifndef MOODBAR_NATIVE_FFI_H
+#define MOODBAR_NATIVE_FFI_H
+
+#pragma once
+
+/* This file is generated by cbindgen. */
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+enum MoodbarNativeStatus {
+  Ok = 0,
+  InvalidArgument = 1,
+  NotFound = 2,
+  Internal = 3,
+};
+typedef int32_t MoodbarNativeStatus;
+
+typedef struct MoodbarNativeAnalysisSummary {
+  uint64_t handle;
+  uint32_t frame_count;
+  uint32_t channel_count;
+} MoodbarNativeAnalysisSummary;
+
+typedef struct MoodbarNativeBuffer {
+  uint8_t *ptr;
+  size_t len;
+  size_t cap;
+} MoodbarNativeBuffer;
+
+MoodbarNativeStatus moodbar_native_analysis_from_path(const char *path,
+                                                      const char *options_json,
+                                                      struct MoodbarNativeAnalysisSummary *out_summary);
+
+MoodbarNativeStatus moodbar_native_analysis_from_bytes(const uint8_t *bytes,
+                                                       size_t bytes_len,
+                                                       const char *extension,
+                                                       const char *options_json,
+                                                       struct MoodbarNativeAnalysisSummary *out_summary);
+
+MoodbarNativeStatus moodbar_native_analysis_dispose(uint64_t handle);
+
+MoodbarNativeStatus moodbar_native_render_svg(uint64_t handle,
+                                              const char *options_json,
+                                              struct MoodbarNativeBuffer *out_svg_utf8);
+
+MoodbarNativeStatus moodbar_native_render_png(uint64_t handle,
+                                              const char *options_json,
+                                              struct MoodbarNativeBuffer *out_png);
+
+MoodbarNativeStatus moodbar_native_last_error(struct MoodbarNativeBuffer *out_message_utf8);
+
+/**
+ * Frees a heap buffer previously returned by this library.
+ *
+ * # Safety
+ *
+ * `buffer` must be a valid, writable pointer obtained from this library, and must not be
+ * freed more than once.
+ */
+void moodbar_native_buffer_free(struct MoodbarNativeBuffer *buffer);
+
+#endif  /* MOODBAR_NATIVE_FFI_H */

package/moodbar-native.podspec

@@ -0,0 +1,30 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "MoodbarNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.description  = package["description"]
+  s.license      = package["license"]
+  s.author       = "Moodbar"
+  s.homepage     = package["homepage"]
+  s.platforms    = {
+    :ios => "14.0"
+  }
+  s.source       = {
+    :git => "https://github.com/gildesmarais/moodbar.rs.git"
+  }
+  s.static_framework = true
+
+  s.dependency "ExpoModulesCore"
+
+  s.source_files = "ios/**/*.{swift,h,m,mm}"
+  s.public_header_files = "ios/include/*.h"
+  s.vendored_frameworks = "ios/MoodbarNativeFFI.xcframework"
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+    "SWIFT_COMPILATION_MODE" => "wholemodule"
+  }
+end

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@moodbar/native",
+  "version": "0.2.0",
+  "description": "React Native bindings for moodbar audio visualization",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gildesmarais/moodbar.rs.git"
+  },
+  "homepage": "https://github.com/gildesmarais/moodbar.rs#readme",
+  "bugs": {
+    "url": "https://github.com/gildesmarais/moodbar.rs/issues"
+  },
+  "keywords": [
+    "moodbar",
+    "react-native",
+    "expo",
+    "audio",
+    "visualization"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "expo-module.config.json",
+    "moodbar-native.podspec",
+    "android",
+    "ios",
+    "README.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
+  "peerDependencies": {
+    "expo": "*",
+    "react-native": "*"
+  },
+  "dependencies": {
+    "expo-modules-core": "^2.6.0"
+  },
+  "sideEffects": false
+}