@infilectai/aira 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InfilectAI
+
+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,75 @@
-# Temporary Holding Version
+# @infilectai/aira
 
-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.
+Standalone, npm-publishable macOS meeting detection, speaker attribution, and audio capture SDK.
+
+`@infilectai/aira` ships a tiny (~450 KB), zero-dependency native macOS helper (`bin/aira-capture`) that handles:
+- **Meeting Detection**: Google Meet, Zoom, and Microsoft Teams (`watchActiveMeetings`, `onMeetingDetected`)
+- **Native Speaker & Roster Scraping**: 250ms macOS Accessibility + DOM inspection fused with local microphone RMS activity
+- **Zero-Screen-Recording Audio Capture**: CoreAudio Process Tap (`CATapDescription` + `AudioHardwareCreateProcessTap`, macOS 14.2+) with `ScreenCaptureKit` fallback
+
+Transcription (STT) and Diarization are **100% pluggable** — connect any OpenAI-compatible HTTP endpoint, WebSocket STT stream, custom callback, or [InfilectAI/AiraEngine][engine] as an optional local on-device compute provider.
+
+[engine]: https://github.com/InfilectAI/AiraEngine
+
+## Quick Start (Pluggable Endpoints)
+
+```ts
+import { Aira, HttpSTTProvider, HttpDiarizationProvider } from '@infilectai/aira'
+
+// 1. Plug in ANY OpenAI-compatible STT endpoint (OpenAI, Groq, local whisper.cpp, FastAPI, etc.)
+//    and optional Diarization endpoint:
+const aira = await Aira.create({
+  stt: {
+    url: 'https://api.openai.com/v1/audio/transcriptions',
+    apiKey: process.env.OPENAI_API_KEY,
+    model: 'whisper-1',
+  },
+  // Optional: plug in any /v1/audio/diarize endpoint or callback
+  diarize: {
+    url: 'http://127.0.0.1:8000/v1/audio/diarize',
+  },
+})
+
+// 2. Or plug in a custom callback for any SDK (Deepgram, ElevenLabs, AssemblyAI, etc.):
+const airaWithCallback = await Aira.create({
+  stt: async (wavBuffer) => {
+    // Call any STT SDK or API and return text or { text, segments }
+    return { text: 'Hello team', segments: [{ id: 0, start: 0, end: 1.5, text: 'Hello team' }] }
+  },
+})
+
+// 3. Detect meetings and start live speaker-attributed transcription:
+aira.onMeetingDetected((meeting) => {
+  console.log(`New meeting: ${meeting.title} on ${meeting.platform}`)
+  aira.startMeeting(meeting)
+})
+
+aira.on('transcript', (event) => {
+  console.log(`[${event.name || 'Speaker'}] ${event.text}`)
+})
+```
+
+## Using `AiraEngine` as a Local On-Device Provider
+
+If you run [InfilectAI/AiraEngine][engine] locally (WhisperKit `whisper-large-v3` + SpeakerKit Pyannote + Gemma 4), pass its `baseUrl` or `AiraEngineProvider`:
+
+```ts
+import { Aira, AiraEngineProvider } from '@infilectai/aira'
+
+const engineProvider = new AiraEngineProvider('http://127.0.0.1:50060')
+const aira = await Aira.create({
+  baseUrl: 'http://127.0.0.1:50060',
+  stt: engineProvider,
+  diarize: engineProvider,
+})
+```
+
+## Build & Pack
+
+```sh
+npm install
+npm run build
+npm pack --dry-run
+```
+
+`npm run build` compiles `native/AiraCapture.swift` + `native/NativeMeetingScraper.swift` into `bin/aira-capture` (~450 KB, linked only against Apple system frameworks) and compiles TypeScript to `dist/`.

package/dist/attribution.d.ts

@@ -0,0 +1,118 @@
+import type { CaptureAudioPayload, CaptureRosterPayload, CaptureSpeakerPayload } from './capture.js';
+import { type DiarizationProvider, type STTProvider } from './providers.js';
+import type { EyesEvent, Participant, TranscribeOptions } from './types.js';
+export interface SpeakerSpan {
+    participantId: string;
+    name: string;
+    t0: number;
+    t1: number;
+    source: string;
+}
+export interface StitchedDiarizeSegment {
+    t0: number;
+    t1: number;
+    speakerId: string;
+}
+/**
+ * Rolling-window cross-batch cluster stitcher for any stateless `DiarizationProvider`.
+ * Matches local cluster labels across overlapping windows by maximum timeline overlap
+ * to produce session-stable anonymous IDs (`S0`, `S1`, ...).
+ */
+export declare class IncrementalDiarizer {
+    readonly windowSeconds: number;
+    readonly hopSeconds: number;
+    private nextGlobalId;
+    private lastBatch;
+    private committedThrough;
+    constructor(windowSeconds?: number, hopSeconds?: number);
+    process(provider: DiarizationProvider, pcmWindow: Buffer, windowStart: number): Promise<StitchedDiarizeSegment[]>;
+    speakerAt(t: number): string | null;
+}
+/**
+ * Maintains the Recall-style speaker timeline (`speakerSpans`), audio energy history,
+ * and diarization cluster map (`speakerMap`) to attribute any `[t0, t1]` transcript segment.
+ */
+export declare class SpeakerAttributionTimeline {
+    readonly diarizer?: IncrementalDiarizer | undefined;
+    roster: Participant[];
+    localUserId: string;
+    localUserName: string;
+    currentSpeakerId: string;
+    currentSpeakerName: string;
+    private lastVisualUpdateMs;
+    readonly speakerSpans: SpeakerSpan[];
+    readonly audioHistory: {
+        t0: number;
+        t1: number;
+        sysRMS: number;
+        micRMS: number;
+        micActive: boolean;
+    }[];
+    readonly speakerMap: Map<string, string>;
+    private readonly uiLagCompensationSeconds;
+    constructor(diarizer?: IncrementalDiarizer | undefined);
+    updateRoster(payload: CaptureRosterPayload): void;
+    recordSpeakerActivity(payload: CaptureSpeakerPayload): void;
+    recordAudioChunk(chunk: CaptureAudioPayload): void;
+    hasSpeechEnergy(t0: number, t1: number): boolean;
+    private energyStats;
+    bestVisualSpeaker(t0: number, t1: number): {
+        id: string;
+        name: string;
+    } | null;
+    applyDiarizationSegments(segments: StitchedDiarizeSegment[], currentAudioSeconds: number): {
+        participantId: string;
+        name: string;
+        t: number;
+    }[];
+    speakerAt(t0: number, t1: number): {
+        id: string;
+        name: string;
+    };
+}
+export interface MeetingSessionPipelineOptions {
+    stt?: STTProvider;
+    diarize?: DiarizationProvider;
+    transcribeOptions?: TranscribeOptions;
+    /** Chunk duration in seconds when using a batch/HTTP STT provider (default: 3.5s). */
+    batchChunkSeconds?: number;
+    onEvent: (event: EyesEvent) => void;
+}
+/**
+ * Connects live `NativeCaptureBridge` events (audio, roster, speaker spans) to any
+ * pluggable `STTProvider` (streaming WebSocket OR batch HTTP/callback) and optional `DiarizationProvider`.
+ */
+export declare class MeetingSessionPipeline {
+    private readonly opts;
+    readonly timeline: SpeakerAttributionTimeline;
+    private readonly diarizer?;
+    private sttStream?;
+    private closed;
+    private lastConfirmedText;
+    private lastConfirmedEnd;
+    private lastPartialText;
+    private lastPartialT0;
+    private lastPartialT1;
+    private batchPcmChunks;
+    private batchPcmBytes;
+    private batchStartT0;
+    private batchLatestT1;
+    private batchHasSpeech;
+    private batchSilenceDuration;
+    private batchInFlight;
+    private diarizePcmBuffer;
+    private diarizeWindowStart;
+    private diarizeTimer;
+    private diarizeBusy;
+    private currentAudioSeconds;
+    constructor(opts: MeetingSessionPipelineOptions);
+    start(): Promise<void>;
+    handleRoster(payload: CaptureRosterPayload): void;
+    handleSpeakerActivity(payload: CaptureSpeakerPayload): void;
+    handleSpeakerChange(payload: CaptureSpeakerPayload): void;
+    handleAudio(chunk: CaptureAudioPayload): void;
+    private flushBatchSTTChunk;
+    private consumeSTTStream;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=attribution.d.ts.map

package/dist/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"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"}