@octane-xplat/recorder 0.0.0-stage → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+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

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# `@octane-xplat/recorder`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```sh
+pnpm add @octane-xplat/recorder
+```
+
+Microphone recording for Octane xplat apps — one take produces a complete
+16-bit PCM **WAV** file (`audio/wav`) on every target. iOS drives
+`AVAudioRecorder`, Android drives `AudioRecord`, and web captures through
+`getUserMedia` + `AudioWorklet` (ScriptProcessor fallback) — no plugin
+dependency. The leaf owns permission, capture, metering, and honest state
+reporting; your app owns the interaction (hold-to-record, limits,
+transcription, insertion).
+
+```ts
+import { createAudioRecorder } from '@octane-xplat/recorder'
+
+const recorder = createAudioRecorder()
+const off = recorder.subscribe((snapshot) => {
+	// { state, permission, durationSeconds, meterLevel, error }
+})
+
+await recorder.start() // asks for the microphone if still undetermined
+// ... record ...
+const take = await recorder.stop() // { bytes, mimeType: 'audio/wav', durationSeconds, path? }
+off()
+recorder.dispose()
+```
+
+`state` is explicit: `recording`, `paused` (app-paused), `interrupted` (the OS
+suspended capture — a call, a silenced mic, a dead track; it becomes `paused`
+when the interruption clears so the app can `resume()`), `idle`, and `error`
+(`snapshot().error` carries the cause). `permission` reports
+`undetermined | granted | denied | unavailable | unsupported` — a denied or
+failed `start()` rejects _and_ updates the snapshot, never a silent no-op.
+
+```ts
+if (recorder.capabilities().supported) {
+	await recorder.pause()
+	await recorder.resume() // also resumes a cleared interruption
+	await recorder.cancel() // discards the open take
+}
+```
+
+Notes and limits:
+
+- `restart(options)` discards the open take and starts a new one.
+- `options.sampleRate` (default 44100) and `options.channels` (1 or 2, default
+  1. are requests — the result's `sampleRate`/`channels` report what was
+     actually written.
+- Native takes also return `path` (a temp file your app owns and deletes);
+  `bytes` always carries the full WAV file.
+- Android: background capture requires an app-owned foreground service — the
+  leaf does not start one.
+- iOS: the leaf sets `AVAudioSessionCategoryPlayAndRecord` (mix + duck) while
+  a take is open and deactivates on stop/cancel.
+- The native entry requires iOS or Android — other targets get the web
+  implementation or a thrown error, never a silent no-op.
+
+For playback of the result see [`@octane-xplat/audio`](../audio/README.md).
+Permission dispatch through `@octane-xplat/platform` answers
+`permissions.ensure('microphone')`.

package/dist/native/index.js

@@ -0,0 +1,16 @@
+import { createAudioRecorder as createAudioRecorder$1, requestMicrophonePermission } from "./index3.js";
+import { createAudioRecorder as createAudioRecorder$2, requestMicrophonePermission as requestMicrophonePermission$1 } from "./index4.js";
+import { Application } from "@nativescript/core";
+//#region src/index.ts
+var createAudioRecorder = () => {
+	if (Application.android) return createAudioRecorder$1();
+	if (Application.ios) return createAudioRecorder$2();
+	throw new Error("@octane-xplat/recorder requires iOS or Android");
+};
+var permissionOwners = globalThis.__xplatPermissionOwners ??= {};
+permissionOwners.microphone = async () => {
+	const state = Application.android ? await requestMicrophonePermission() : Application.ios ? await requestMicrophonePermission$1() : "unsupported";
+	return state === "granted" ? "granted" : state === "unsupported" ? "unsupported" : "denied";
+};
+//#endregion
+export { createAudioRecorder };

package/dist/native/index2.js

@@ -0,0 +1,46 @@
+//#region src/wav.ts
+var ascii = (view, at, text) => {
+	for (let i = 0; i < text.length; i++) view.setUint8(at + i, text.charCodeAt(i));
+};
+/** The 44-byte canonical WAV header for 16-bit PCM. `dataLength` is the
+*  number of PCM bytes that follow. */
+function wavHeader(dataLength, sampleRate, channels) {
+	const bytes = /* @__PURE__ */ new Uint8Array(44);
+	const view = new DataView(bytes.buffer);
+	ascii(view, 0, "RIFF");
+	view.setUint32(4, 36 + dataLength, true);
+	ascii(view, 8, "WAVE");
+	ascii(view, 12, "fmt ");
+	view.setUint32(16, 16, true);
+	view.setUint16(20, 1, true);
+	view.setUint16(22, channels, true);
+	view.setUint32(24, sampleRate, true);
+	view.setUint32(28, sampleRate * channels * 2, true);
+	view.setUint16(32, channels * 2, true);
+	view.setUint16(34, 16, true);
+	ascii(view, 36, "data");
+	view.setUint32(40, dataLength, true);
+	return bytes;
+}
+/** Base64 → bytes. Native read-backs cross the bridge as base64 strings
+*  (one JNI/ObjC call instead of per-byte marshalling). */
+function decodeBase64(value) {
+	const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+	const out = new Uint8Array(Math.ceil(value.length * 3 / 4));
+	let buffer = 0;
+	let bits = 0;
+	let at = 0;
+	for (const char of value) {
+		const index = alphabet.indexOf(char);
+		if (index < 0) continue;
+		buffer = buffer << 6 | index;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out[at++] = buffer >> bits & 255;
+		}
+	}
+	return out.subarray(0, at);
+}
+//#endregion
+export { decodeBase64, wavHeader };

package/dist/native/index3.js

@@ -0,0 +1,330 @@
+import { decodeBase64, wavHeader } from "./index2.js";
+import { Application, ApplicationSettings, Utils } from "@nativescript/core";
+//#region src/recorder.android.ts
+var PERMISSION = "android.permission.RECORD_AUDIO";
+var ASKED_KEY = "octane-xplat.recorder.asked";
+var requestCode = 7921;
+var appContext = () => Utils.android.getApplicationContext();
+function microphonePresent() {
+	try {
+		return appContext()?.getPackageManager?.().hasSystemFeature?.("android.hardware.microphone") !== false;
+	} catch {
+		return true;
+	}
+}
+function microphonePermissionState() {
+	if (!microphonePresent()) return "unavailable";
+	const context = appContext();
+	if (!context?.checkSelfPermission) return "unsupported";
+	if (context.checkSelfPermission(PERMISSION) === android.content.pm.PackageManager.PERMISSION_GRANTED) return "granted";
+	return ApplicationSettings.getBoolean(ASKED_KEY, false) ? "denied" : "undetermined";
+}
+async function requestMicrophonePermission() {
+	if (!microphonePresent()) return "unavailable";
+	const context = appContext();
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity;
+	if (!context?.checkSelfPermission || !activity?.requestPermissions) return "unsupported";
+	if (context.checkSelfPermission(PERMISSION) === android.content.pm.PackageManager.PERMISSION_GRANTED) return "granted";
+	ApplicationSettings.setBoolean(ASKED_KEY, true);
+	return await new Promise((resolve) => {
+		const code = requestCode++;
+		const onResult = (args) => {
+			if (args.requestCode !== code) return;
+			Application.android.off(Application.android.activityRequestPermissionsEvent, onResult);
+			resolve(args.grantResults?.[0] === android.content.pm.PackageManager.PERMISSION_GRANTED ? "granted" : "denied");
+		};
+		Application.android.on(Application.android.activityRequestPermissionsEvent, onResult);
+		activity.requestPermissions([PERMISSION], code);
+	});
+}
+var asError = (cause) => cause instanceof Error ? cause : new Error(String(cause));
+/** Copy a Uint8Array into a Java byte[] for java.io writers. */
+var toJavaBytes = (bytes) => {
+	const native = Array.create("byte", bytes.length);
+	for (let i = 0; i < bytes.length; i++) native[i] = bytes[i];
+	return native;
+};
+/** Patch the two RIFF size fields after streaming PCM — RandomAccessFile
+*  writes big-endian, so emit each little-endian byte directly. */
+var patchWavSizes = (file, dataLength) => {
+	const raf = new java.io.RandomAccessFile(file, "rw");
+	try {
+		const sizes = /* @__PURE__ */ new Uint8Array(8);
+		const view = new DataView(sizes.buffer);
+		view.setUint32(0, 36 + dataLength, true);
+		view.setUint32(4, dataLength, true);
+		raf.seek(4);
+		raf.write(toJavaBytes(sizes.subarray(0, 4)));
+		raf.seek(40);
+		raf.write(toJavaBytes(sizes.subarray(4, 8)));
+	} finally {
+		raf.close();
+	}
+};
+var readFileBytes = (path) => {
+	const file = new java.io.File(path);
+	const stream = new java.io.FileInputStream(file);
+	try {
+		const bytes = Array.create("byte", file.length());
+		new java.io.DataInputStream(stream).readFully(bytes);
+		return decodeBase64(android.util.Base64.encodeToString(bytes, android.util.Base64.NO_WRAP));
+	} finally {
+		stream.close();
+	}
+};
+var createAudioRecorder = () => {
+	const listeners = /* @__PURE__ */ new Set();
+	let record;
+	let thread;
+	let recordingCallback;
+	let output;
+	let takePath;
+	let capturing = false;
+	let bytesWritten = 0;
+	let peak = 0;
+	let state = "idle";
+	let permission = microphonePermissionState();
+	let error;
+	let options = {
+		sampleRate: 44100,
+		channels: 1
+	};
+	let timer;
+	let opening = false;
+	let disposed = false;
+	const snapshot = () => ({
+		state,
+		permission,
+		durationSeconds: bytesWritten / (options.sampleRate * options.channels * 2),
+		meterLevel: state === "recording" ? peak / 32768 : null,
+		error
+	});
+	const emit = () => {
+		const value = snapshot();
+		for (const listener of listeners) listener(value);
+	};
+	const updatePeak = (buffer, length) => {
+		for (let i = 0; i + 1 < length; i += 2) {
+			const sample = Math.abs((buffer[i + 1] << 8 | buffer[i] & 255) << 16 >> 16);
+			if (sample > peak) peak = sample;
+		}
+	};
+	const readLoop = (audioRecord, out, chunkSize) => {
+		const chunk = Array.create("byte", chunkSize);
+		while (capturing) {
+			const read = audioRecord.read(chunk, 0, chunkSize);
+			if (read > 0) try {
+				out.write(chunk, 0, read);
+				bytesWritten += read;
+				updatePeak(chunk, read);
+			} catch {}
+			else if (read < 0) {
+				fail(/* @__PURE__ */ new Error(`AudioRecord read failed (${read})`));
+				return;
+			}
+		}
+	};
+	const suspendCapture = () => {
+		capturing = false;
+		try {
+			record?.stop();
+		} catch {}
+		try {
+			if (thread && java.lang.Thread.currentThread() !== thread) thread.join(500);
+		} catch {}
+		thread = void 0;
+	};
+	const resumeCapture = () => {
+		const audioRecord = record;
+		const out = output;
+		if (!audioRecord || !out) throw new Error("AudioRecorder has no open take");
+		audioRecord.startRecording();
+		capturing = true;
+		const chunkSize = Math.max(4096, audioRecord.getBufferSizeInFrames() * options.channels * 2);
+		thread = new java.lang.Thread(new java.lang.Runnable({ run: () => readLoop(audioRecord, out, chunkSize) }));
+		thread.start();
+	};
+	const fail = (cause) => {
+		error = cause;
+		suspendCapture();
+		state = "error";
+		emit();
+	};
+	const closeTake = (discard) => {
+		suspendCapture();
+		try {
+			output?.close();
+		} catch {}
+		output = void 0;
+		if (recordingCallback && record) try {
+			record.unregisterAudioRecordingCallback(recordingCallback);
+		} catch {}
+		recordingCallback = void 0;
+		try {
+			record?.release();
+		} catch {}
+		record = void 0;
+		if (discard && takePath) try {
+			new java.io.File(takePath).delete();
+		} catch {}
+	};
+	const start = async (next) => {
+		if (disposed) throw new Error("AudioRecorder is disposed");
+		if (state !== "idle" || opening) throw new Error(`AudioRecorder cannot start while ${opening ? "starting" : state}`);
+		opening = true;
+		try {
+			permission = await requestMicrophonePermission();
+			emit();
+			if (permission !== "granted") {
+				error = /* @__PURE__ */ new Error(`Microphone permission is ${permission}`);
+				emit();
+				throw error;
+			}
+		} finally {
+			opening = false;
+		}
+		options = {
+			sampleRate: next?.sampleRate ?? options.sampleRate,
+			channels: next?.channels ?? options.channels
+		};
+		error = void 0;
+		bytesWritten = 0;
+		peak = 0;
+		const context = appContext();
+		if (!context) throw new Error("AudioRecorder needs an Android application context");
+		const channelConfig = options.channels === 2 ? android.media.AudioFormat.CHANNEL_IN_STEREO : android.media.AudioFormat.CHANNEL_IN_MONO;
+		const encoding = android.media.AudioFormat.ENCODING_PCM_16BIT;
+		const minBuffer = android.media.AudioRecord.getMinBufferSize(options.sampleRate, channelConfig, encoding);
+		try {
+			if (minBuffer <= 0) throw new Error(`This device cannot capture ${options.sampleRate} Hz ${options.channels}-channel PCM`);
+			record = new android.media.AudioRecord(android.media.MediaRecorder.AudioSource.MIC, options.sampleRate, channelConfig, encoding, Math.max(minBuffer, 4096));
+			if (record.getState() !== android.media.AudioRecord.STATE_INITIALIZED) throw new Error("AudioRecord failed to initialize — no usable microphone input");
+			const file = java.io.File.createTempFile("octane-recorder-", ".wav", context.getCacheDir());
+			takePath = file.getAbsolutePath();
+			output = new java.io.FileOutputStream(file);
+			output.write(toJavaBytes(wavHeader(0, options.sampleRate, options.channels)));
+			const mainHandler = new android.os.Handler(android.os.Looper.getMainLooper());
+			const executor = new java.util.concurrent.Executor({ execute(command) {
+				mainHandler.post(command);
+			} });
+			recordingCallback = new android.media.AudioManager.AudioRecordingCallback.extend({ onRecordingConfigChanged(configs) {
+				let silenced = false;
+				for (let i = 0; configs && i < configs.size(); i++) silenced ||= configs.get(i).isClientSilenced() === true;
+				if (silenced && (state === "recording" || state === "paused")) {
+					suspendCapture();
+					state = "interrupted";
+					emit();
+				} else if (!silenced && state === "interrupted") {
+					state = "paused";
+					emit();
+				}
+			} })();
+			record.registerAudioRecordingCallback(executor, recordingCallback);
+			resumeCapture();
+		} catch (cause) {
+			closeTake(true);
+			error = asError(cause);
+			state = "error";
+			emit();
+			throw error;
+		}
+		state = "recording";
+		emit();
+	};
+	const pause = async () => {
+		if (state !== "recording") throw new Error(`AudioRecorder cannot pause while ${state}`);
+		suspendCapture();
+		state = "paused";
+		emit();
+	};
+	const resume = async () => {
+		if (state !== "paused") throw new Error(`AudioRecorder cannot resume while ${state}`);
+		try {
+			resumeCapture();
+		} catch (cause) {
+			fail(asError(cause));
+			throw error;
+		}
+		state = "recording";
+		emit();
+	};
+	const restart = async (next) => {
+		if (state !== "idle") await cancel();
+		await start(next);
+	};
+	const stop = async () => {
+		if (!record || !takePath || !output) throw new Error("AudioRecorder has no take to stop");
+		const takenPath = takePath;
+		const dataLength = bytesWritten;
+		closeTake(false);
+		patchWavSizes(new java.io.File(takenPath), dataLength);
+		const result = {
+			mimeType: "audio/wav",
+			bytes: readFileBytes(takenPath),
+			durationSeconds: dataLength / (options.sampleRate * options.channels * 2),
+			sampleRate: options.sampleRate,
+			channels: options.channels,
+			path: takenPath
+		};
+		takePath = void 0;
+		state = "idle";
+		emit();
+		return result;
+	};
+	const cancel = async () => {
+		if (state === "idle" && !record && !takePath) return;
+		closeTake(true);
+		takePath = void 0;
+		state = "idle";
+		error = void 0;
+		emit();
+	};
+	return {
+		capabilities: () => ({
+			supported: true,
+			pause: true,
+			metering: true,
+			userGestureRequired: false,
+			reason: "Foreground capture only — background microphone use needs an app-owned foreground service."
+		}),
+		snapshot,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			listener(snapshot());
+			timer ??= setInterval(() => {
+				emit();
+				peak = 0;
+			}, 250);
+			return () => {
+				listeners.delete(listener);
+				if (!listeners.size && timer) {
+					clearInterval(timer);
+					timer = void 0;
+				}
+			};
+		},
+		requestPermission: async () => {
+			permission = await requestMicrophonePermission();
+			emit();
+			return permission;
+		},
+		start,
+		pause,
+		resume,
+		restart,
+		stop,
+		cancel,
+		dispose: () => {
+			if (disposed) return;
+			disposed = true;
+			closeTake(true);
+			takePath = void 0;
+			if (timer) clearInterval(timer);
+			timer = void 0;
+			listeners.clear();
+			state = "idle";
+		}
+	};
+};
+//#endregion
+export { createAudioRecorder, microphonePermissionState, requestMicrophonePermission };