@superbased/macos-speech

Offline on-device speech recognition for macOS via SFSpeechRecognizer. Published as an optional dependency of the superbased npm package; not intended as a standalone consumer surface.

Requirements

• macOS 10.15+ (arm64 or x64)
• Node.js 20+ (prebuilts published for the N-API versions actually in use)
• Speech framework permission (NSSpeechRecognitionUsageDescription in the host app's Info.plist)
• On-device recognition requires the relevant language model installed via System Settings → Accessibility → Live Captions / System Settings → General → Language & Region.

Install

npm install @superbased/macos-speech

Prebuilts are published ahead of time so npm install never falls through to node-gyp rebuild on consumer boxes. If a prebuilt is unavailable for your combination of Node + arch, install fails with a clear error — file an issue rather than shipping a broken package.

API

import {
  authorizationStatus,
  requestAuthorization,
  isOnDeviceAvailable,
  transcribeFile,
} from '@superbased/macos-speech';

// Synchronous status — does not prompt.
authorizationStatus(); // 'notDetermined' | 'denied' | 'restricted' | 'authorized'

// Prompts if notDetermined; resolves with the resulting status.
await requestAuthorization();

// Probe whether on-device recognition is supported for a locale.
isOnDeviceAvailable({ locale: 'en-US' });

// Transcribe a file. Fails fast with a structured Error if permission
// is not granted or the locale is unsupported.
const { text, confidence, locale } = await transcribeFile({
  audioPath: '/absolute/path/to/audio.wav',
  locale: 'en-US',
  contextualStrings: ['SuperBased', 'OmniFocus'],
});

Error shape

All rejections are Error instances with a code property for programmatic branching:

| code | Cause | Remediation | |---|---|---| | unauthorized | Permission not granted | Call requestAuthorization(); user must accept in System Settings → Privacy & Security → Speech Recognition | | locale_not_supported | No recognizer registered for the locale | Try a different locale (en-US is widely supported); ensure the language is installed on the device | | audio_file_not_found | opts.audioPath doesn't exist | Verify the path; must be absolute | | recognition_failed | Speech framework returned an NSError | err.nsErrorCode contains the raw NSError code |

Building from source

npm install
npm run build       # node-gyp rebuild

Requires Xcode command-line tools. binding.gyp targets MACOSX_DEPLOYMENT_TARGET=10.15 and links against the Speech, AVFoundation, and Foundation frameworks.

License

MIT. Authored by Gaja AI Private Limited.