openbuilder 0.1.0

package/src/analytics/speaker-stats.ts

@@ -0,0 +1,104 @@
+/**
+ * speaker-stats.ts — Speaker talk-time analytics calculator
+ *
+ * Calculates per-speaker statistics from transcript data:
+ * - Talk time (estimated from caption timestamps + text length)
+ * - Percentage of meeting
+ * - Word count
+ */
+
+import type { ParsedTranscript, TranscriptLine } from "../utils/transcript-parser.js";
+
+export interface SpeakerStats {
+  speaker: string;
+  talkTimeSeconds: number;
+  talkTimeFormatted: string;
+  percentage: number;
+  wordCount: number;
+}
+
+export interface MeetingAnalytics {
+  speakers: SpeakerStats[];
+  totalDurationSeconds: number;
+  totalDurationFormatted: string;
+  participantCount: number;
+}
+
+/**
+ * Estimate talk time for each caption line.
+ *
+ * Strategy: For each speaker's line, estimate duration as the gap until the
+ * next line (capped at 30s to avoid inflating during pauses). For the last
+ * line, estimate based on word count (~150 words/minute speaking rate).
+ */
+function estimateLineDuration(lines: TranscriptLine[], index: number): number {
+  const MAX_GAP_SECONDS = 30;
+  const WORDS_PER_SECOND = 2.5; // ~150 words/minute
+
+  if (index < lines.length - 1) {
+    const gap = lines[index + 1]!.totalSeconds - lines[index]!.totalSeconds;
+    return Math.min(Math.max(gap, 1), MAX_GAP_SECONDS);
+  }
+
+  // Last line: estimate from word count
+  const wordCount = lines[index]!.text.split(/\s+/).length;
+  return Math.max(Math.round(wordCount / WORDS_PER_SECOND), 1);
+}
+
+/** Format seconds as M:SS or H:MM:SS */
+function formatDuration(totalSeconds: number): string {
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = Math.round(totalSeconds % 60);
+
+  if (hours > 0) {
+    return `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+  }
+  return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+
+/** Calculate speaker statistics from a parsed transcript. */
+export function calculateSpeakerStats(transcript: ParsedTranscript): MeetingAnalytics {
+  const speakerMap = new Map<string, { talkTimeSeconds: number; wordCount: number }>();
+
+  for (let i = 0; i < transcript.lines.length; i++) {
+    const line = transcript.lines[i]!;
+    const duration = estimateLineDuration(transcript.lines, i);
+    const wordCount = line.text.split(/\s+/).length;
+
+    const existing = speakerMap.get(line.speaker) ?? { talkTimeSeconds: 0, wordCount: 0 };
+    existing.talkTimeSeconds += duration;
+    existing.wordCount += wordCount;
+    speakerMap.set(line.speaker, existing);
+  }
+
+  // Calculate total talk time for percentage calculation
+  let totalTalkTime = 0;
+  for (const stats of speakerMap.values()) {
+    totalTalkTime += stats.talkTimeSeconds;
+  }
+
+  // Use the greater of transcript duration or total talk time for meeting duration
+  const totalDuration = Math.max(transcript.durationSeconds, totalTalkTime);
+
+  const speakers: SpeakerStats[] = [];
+  for (const [speaker, stats] of speakerMap.entries()) {
+    speakers.push({
+      speaker,
+      talkTimeSeconds: stats.talkTimeSeconds,
+      talkTimeFormatted: formatDuration(stats.talkTimeSeconds),
+      percentage: totalDuration > 0 ? Math.round((stats.talkTimeSeconds / totalDuration) * 100) : 0,
+      wordCount: stats.wordCount,
+    });
+  }
+
+  // Sort by talk time descending
+  speakers.sort((a, b) => b.talkTimeSeconds - a.talkTimeSeconds);
+
+  return {
+    speakers,
+    totalDurationSeconds: totalDuration,
+    totalDurationFormatted: formatDuration(totalDuration),
+    participantCount: speakers.length,
+  };
+}

package/src/audio/capture.ts

@@ -0,0 +1,374 @@
+/**
+ * capture.ts — PulseAudio audio capture via ffmpeg
+ *
+ * Sets up a PulseAudio virtual sink for isolating browser audio,
+ * then uses ffmpeg to capture audio from the sink monitor into
+ * WAV chunks suitable for Whisper transcription.
+ */
+
+import { spawn, execSync, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, unlinkSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+export interface AudioCaptureOptions {
+  sinkName: string;
+  chunkDurationSec?: number; // default 30
+  sampleRate?: number; // default 16000
+  outputDir?: string; // default auto-created temp dir
+}
+
+export interface AudioCapture {
+  /** The PulseAudio sink name (set PULSE_SINK to this before launching browser) */
+  sinkName: string;
+  /** Directory where WAV chunks are written */
+  outputDir: string;
+  /** PulseAudio module index (for unloading) */
+  moduleIndex: string;
+  /** Returns list of completed chunk file paths (not currently being written) */
+  getCompletedChunks(): string[];
+  /** Stops ffmpeg and cleans up PulseAudio sink */
+  stop(): void;
+  /** Cleans up temp files */
+  cleanup(): void;
+}
+
+/** Check if a command is available on PATH */
+function commandExists(cmd: string): boolean {
+  try {
+    execSync(`which ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Check if PulseAudio and ffmpeg are available */
+export function checkAudioDeps(): { available: boolean; missing: string[] } {
+  const missing: string[] = [];
+  if (!commandExists("pulseaudio") && !commandExists("pactl")) missing.push("pulseaudio");
+  if (!commandExists("ffmpeg")) missing.push("ffmpeg");
+  return { available: missing.length === 0, missing };
+}
+
+/** Start PulseAudio if not already running */
+function ensurePulseAudio(): void {
+  try {
+    execSync("pactl info", { stdio: "ignore", timeout: 5000 });
+  } catch {
+    // PulseAudio not running, start it
+    try {
+      execSync("pulseaudio --start --exit-idle-time=-1", { stdio: "ignore", timeout: 10000 });
+      // Wait a moment for it to be ready
+      execSync("sleep 1 && pactl info", { stdio: "ignore", timeout: 10000 });
+    } catch (err) {
+      throw new Error(
+        `Failed to start PulseAudio: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}
+
+/** Create a PulseAudio null sink and return the module index */
+function createSink(sinkName: string): string {
+  try {
+    const result = execSync(
+      `pactl load-module module-null-sink sink_name=${sinkName} sink_properties=device.description=OpenBuilderSink`,
+      { encoding: "utf-8", timeout: 5000 },
+    ).trim();
+    return result;
+  } catch (err) {
+    throw new Error(
+      `Failed to create PulseAudio sink "${sinkName}": ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+/** Remove a PulseAudio module by index */
+function removeSink(moduleIndex: string): void {
+  try {
+    execSync(`pactl unload-module ${moduleIndex}`, { stdio: "ignore", timeout: 5000 });
+  } catch {
+    // Best-effort cleanup
+  }
+}
+
+/** Create a PulseAudio pipe sink and return the module index and pipe path */
+function createPipeSink(sinkName: string): { moduleIndex: string; pipePath: string } {
+  const pipePath = `/tmp/${sinkName}-audio-pipe`;
+  
+  try {
+    // Create FIFO pipe
+    execSync(`mkfifo ${pipePath}`, { timeout: 5000 });
+    
+    // Load module-pipe-sink
+    const result = execSync(
+      `pactl load-module module-pipe-sink file=${pipePath} sink_name=${sinkName} format=s16le rate=16000 channels=1 sink_properties=device.description=OpenBuilderPipeSink`,
+      { encoding: "utf-8", timeout: 5000 },
+    ).trim();
+    
+    // Set as default sink
+    execSync(`pactl set-default-sink ${sinkName}`, { timeout: 5000 });
+    
+    return { moduleIndex: result, pipePath };
+  } catch (err) {
+    // Clean up pipe if it was created
+    try {
+      unlinkSync(pipePath);
+    } catch {}
+    throw new Error(
+      `Failed to create PulseAudio pipe sink "${sinkName}": ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+/** Test if pipe-sink approach works by playing a test sound and checking if data flows */
+async function testPipeSink(pipePath: string, sampleRate = 16000): Promise<boolean> {
+  return new Promise((resolve) => {
+    let resolved = false;
+    const timeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        resolve(false);
+      }
+    }, 10000); // 10 second timeout
+
+    // Spawn ffmpeg to read from pipe - it should receive data if pipe works
+    const ffmpeg = spawn("ffmpeg", [
+      "-f", "s16le",
+      "-ar", String(sampleRate),
+      "-ac", "1",
+      "-i", pipePath,
+      "-t", "2", // Only capture for 2 seconds
+      "-f", "null",
+      "-"
+    ], { stdio: ["ignore", "pipe", "pipe"] });
+
+    // Generate test audio in background
+    setTimeout(() => {
+      try {
+        execSync(`pactl play-sample bell`, { timeout: 3000, stdio: "ignore" });
+      } catch {
+        // Try alternative test sound
+        try {
+          execSync(`speaker-test -t sine -f 440 -l 1 -s 1 2>/dev/null`, { timeout: 3000, stdio: "ignore" });
+        } catch {
+          // No test sound available, but ffmpeg might still detect silence vs no pipe
+        }
+      }
+    }, 1000);
+
+    ffmpeg.on("exit", (code) => {
+      clearTimeout(timeout);
+      if (!resolved) {
+        resolved = true;
+        // If ffmpeg exits normally (even if no audio), pipe is working
+        resolve(code !== null);
+      }
+    });
+
+    ffmpeg.on("error", () => {
+      clearTimeout(timeout);
+      if (!resolved) {
+        resolved = true;
+        resolve(false);
+      }
+    });
+  });
+}
+
+/**
+ * Start audio capture from PulseAudio using pipe-sink approach with null-sink fallback.
+ *
+ * ffmpeg writes segmented WAV files (chunk_000.wav, chunk_001.wav, ...)
+ * of `chunkDurationSec` seconds each.
+ */
+export function startAudioCapture(options: AudioCaptureOptions): AudioCapture {
+  const {
+    sinkName,
+    chunkDurationSec = 30,
+    sampleRate = 16000,
+    outputDir: providedDir,
+  } = options;
+
+  // Ensure deps
+  const deps = checkAudioDeps();
+  if (!deps.available) {
+    throw new Error(`Missing audio dependencies: ${deps.missing.join(", ")}`);
+  }
+
+  // Start PulseAudio
+  ensurePulseAudio();
+
+  // Create output directory
+  const outputDir = providedDir ?? join(tmpdir(), `openbuilder-audio-${sinkName}-${Date.now()}`);
+  mkdirSync(outputDir, { recursive: true });
+
+  let moduleIndex: string;
+  let pipePath: string | null = null;
+  let ffmpeg: ChildProcess;
+  let audioMethod: "pipe-sink" | "null-sink";
+
+  // Try pipe-sink approach first
+  try {
+    const pipeResult = createPipeSink(sinkName);
+    moduleIndex = pipeResult.moduleIndex;
+    pipePath = pipeResult.pipePath;
+    
+    console.log(`  PulseAudio pipe-sink created: ${sinkName} (module ${moduleIndex})`);
+    
+    // Start ffmpeg reading from the pipe
+    const chunkPattern = join(outputDir, "chunk_%03d.wav");
+    ffmpeg = spawn(
+      "ffmpeg",
+      [
+        "-f", "s16le",
+        "-ar", String(sampleRate),
+        "-ac", "1",
+        "-i", pipePath,
+        "-f", "segment",
+        "-segment_time", String(chunkDurationSec),
+        "-reset_timestamps", "1",
+        chunkPattern,
+      ],
+      {
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    
+    audioMethod = "pipe-sink";
+    console.log(`  Using pipe-sink method with ffmpeg reading from ${pipePath}`);
+    
+  } catch (pipeErr) {
+    console.log(`  Pipe-sink failed: ${pipeErr instanceof Error ? pipeErr.message : String(pipeErr)}`);
+    console.log(`  Falling back to null-sink method...`);
+    
+    try {
+      // Fallback to null-sink approach (original method)
+      moduleIndex = createSink(sinkName);
+      pipePath = null;
+      console.log(`  PulseAudio null-sink created: ${sinkName} (module ${moduleIndex})`);
+
+      // Start ffmpeg capturing from the sink monitor
+      const monitorSource = `${sinkName}.monitor`;
+      const chunkPattern = join(outputDir, "chunk_%03d.wav");
+
+      ffmpeg = spawn(
+        "ffmpeg",
+        [
+          "-f", "pulse",
+          "-i", monitorSource,
+          "-ac", "1",
+          "-ar", String(sampleRate),
+          "-f", "segment",
+          "-segment_time", String(chunkDurationSec),
+          "-reset_timestamps", "1",
+          chunkPattern,
+        ],
+        {
+          stdio: ["ignore", "pipe", "pipe"],
+        },
+      );
+      
+      audioMethod = "null-sink";
+      console.log(`  Using null-sink method with PulseAudio monitor ${monitorSource}`);
+      
+    } catch (nullErr) {
+      throw new Error(
+        `Both pipe-sink and null-sink methods failed. Pipe: ${pipeErr instanceof Error ? pipeErr.message : String(pipeErr)}. Null: ${nullErr instanceof Error ? nullErr.message : String(nullErr)}`,
+      );
+    }
+  }
+
+  let ffmpegRunning = true;
+
+  ffmpeg.on("exit", (code) => {
+    ffmpegRunning = false;
+    if (code && code !== 255) {
+      console.error(`  ffmpeg exited with code ${code}`);
+    }
+  });
+
+  ffmpeg.on("error", (err) => {
+    ffmpegRunning = false;
+    console.error(`  ffmpeg error: ${err.message}`);
+  });
+
+  // Track which chunk is currently being written
+  // ffmpeg writes chunk_NNN.wav sequentially; the latest one is in-progress
+  let lastSeenChunks = new Set<string>();
+
+  const getCompletedChunks = (): string[] => {
+    if (!existsSync(outputDir)) return [];
+
+    const allChunks = readdirSync(outputDir)
+      .filter((f) => f.startsWith("chunk_") && f.endsWith(".wav"))
+      .sort();
+
+    if (allChunks.length === 0) return [];
+
+    // The last file is potentially still being written by ffmpeg
+    // Only return chunks that are NOT the latest one (unless ffmpeg has stopped)
+    if (ffmpegRunning && allChunks.length > 0) {
+      const completed = allChunks.slice(0, -1);
+      // Filter to only return newly completed (not yet seen)
+      const newChunks = completed.filter((c) => !lastSeenChunks.has(c));
+      for (const c of newChunks) lastSeenChunks.add(c);
+      return newChunks.map((c) => join(outputDir, c));
+    }
+
+    // ffmpeg stopped — all chunks are complete
+    const newChunks = allChunks.filter((c) => !lastSeenChunks.has(c));
+    for (const c of newChunks) lastSeenChunks.add(c);
+    return newChunks.map((c) => join(outputDir, c));
+  };
+
+  const stop = (): void => {
+    if (ffmpegRunning && ffmpeg.pid) {
+      // Send SIGINT for graceful shutdown (ffmpeg finalizes the current segment)
+      ffmpeg.kill("SIGINT");
+
+      // Give ffmpeg a moment to finalize, then force kill if needed
+      setTimeout(() => {
+        if (ffmpegRunning) {
+          ffmpeg.kill("SIGKILL");
+        }
+      }, 3000);
+    }
+
+    removeSink(moduleIndex);
+    
+    // Clean up pipe file if using pipe-sink
+    if (pipePath) {
+      try {
+        unlinkSync(pipePath);
+      } catch {
+        // Best-effort cleanup
+      }
+    }
+    
+    ffmpegRunning = false;
+  };
+
+  const cleanup = (): void => {
+    try {
+      if (existsSync(outputDir)) {
+        rmSync(outputDir, { recursive: true, force: true });
+      }
+    } catch {
+      // Best-effort
+    }
+  };
+
+  console.log(`  ffmpeg capturing audio → ${outputDir}`);
+  console.log(`  Method: ${audioMethod}, Chunk duration: ${chunkDurationSec}s, Sample rate: ${sampleRate}Hz`);
+
+  return {
+    sinkName,
+    outputDir,
+    moduleIndex,
+    getCompletedChunks,
+    stop,
+    cleanup,
+  };
+}

package/src/audio/pipeline.ts

@@ -0,0 +1,189 @@
+/**
+ * pipeline.ts — Audio capture + transcription pipeline
+ *
+ * Orchestrates PulseAudio audio capture and Whisper transcription
+ * to produce a real-time transcript file in the same format as
+ * the caption scraping approach: [HH:MM:SS] Speaker: text
+ */
+
+import { appendFileSync, writeFileSync } from "node:fs";
+import { startAudioCapture, checkAudioDeps, type AudioCapture } from "./capture.js";
+import { Transcriber, type TranscriptionResult } from "./transcriber.js";
+
+export interface AudioPipelineOptions {
+  /** Unique sink name for this meeting (e.g. "openbuilder_abc-defg-hij") */
+  sinkName: string;
+  /** Path to write the transcript file */
+  transcriptPath: string;
+  /** OpenAI API key for Whisper */
+  apiKey?: string;
+  /** Whisper model (default "whisper-1") */
+  whisperModel?: string;
+  /** Audio chunk duration in seconds (default 30) */
+  chunkDurationSec?: number;
+  /** Whether to print transcript lines to stdout */
+  verbose?: boolean;
+}
+
+export interface AudioPipeline {
+  /** Stop the pipeline and finalize transcript */
+  stop(): Promise<void>;
+  /** Clean up temp files */
+  cleanup(): void;
+  /** Returns timestamp of last transcribed text (for idle detection) */
+  getLastTranscriptAt(): number;
+}
+
+/**
+ * Check whether audio capture mode is available on this system.
+ * Returns { available, missing } where missing lists absent dependencies.
+ */
+export function isAudioCaptureAvailable(): { available: boolean; missing: string[] } {
+  return checkAudioDeps();
+}
+
+/**
+ * Start the audio capture + transcription pipeline.
+ *
+ * This function:
+ * 1. Creates a PulseAudio sink for browser audio isolation
+ * 2. Starts ffmpeg to capture audio into WAV chunks
+ * 3. Polls for completed chunks and sends them to Whisper
+ * 4. Writes transcription results to the transcript file
+ *
+ * The PULSE_SINK env var must be set to `sinkName` BEFORE launching
+ * the browser, so browser audio is routed to our sink.
+ */
+export async function startAudioPipeline(
+  options: AudioPipelineOptions,
+): Promise<AudioPipeline> {
+  const {
+    sinkName,
+    transcriptPath,
+    apiKey,
+    whisperModel,
+    chunkDurationSec = 30,
+    verbose = false,
+  } = options;
+
+  // Initialize transcript file
+  writeFileSync(transcriptPath, "");
+
+  // Start audio capture
+  const capture: AudioCapture = startAudioCapture({
+    sinkName,
+    chunkDurationSec,
+  });
+
+  // Initialize transcriber
+  const transcriber = new Transcriber({
+    apiKey,
+    model: whisperModel,
+  });
+
+  let lastTranscriptAt = Date.now();
+  let running = true;
+  let lastMinuteKey = "";
+  let chunkIndex = 0;
+
+  // Meeting start time — used to calculate absolute timestamps
+  const meetingStartTime = Date.now();
+
+  const writeTranscriptLine = (
+    offsetSec: number,
+    text: string,
+  ): void => {
+    // Convert chunk offset to absolute time
+    const absoluteMs = meetingStartTime + offsetSec * 1000;
+    const d = new Date(absoluteMs);
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    const ss = String(d.getSeconds()).padStart(2, "0");
+    const minuteKey = `${hh}:${mm}`;
+
+    let prefix = "";
+    if (lastMinuteKey && minuteKey !== lastMinuteKey) {
+      prefix = "\n";
+    }
+    lastMinuteKey = minuteKey;
+
+    // MVP: no speaker diarization, use "Speaker" as default
+    const line = `[${hh}:${mm}:${ss}] Speaker: ${text}`;
+    try {
+      appendFileSync(transcriptPath, `${prefix}${line}\n`);
+    } catch {
+      // Ignore write errors
+    }
+
+    lastTranscriptAt = Date.now();
+
+    if (verbose) {
+      console.log(`  [audio] ${line}`);
+    }
+  };
+
+  const processChunk = async (chunkPath: string): Promise<void> => {
+    const chunkStartSec = chunkIndex * chunkDurationSec;
+    chunkIndex++;
+
+    try {
+      const result: TranscriptionResult = await transcriber.transcribeChunk(chunkPath);
+
+      if (!result.text) return;
+
+      // Use segment timestamps if available, otherwise write as single block
+      if (result.segments.length > 0) {
+        for (const seg of result.segments) {
+          if (seg.text) {
+            writeTranscriptLine(chunkStartSec + seg.start, seg.text);
+          }
+        }
+      } else {
+        writeTranscriptLine(chunkStartSec, result.text);
+      }
+    } catch (err) {
+      console.error(
+        `  Transcription error (chunk ${chunkIndex}): ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+
+  // Polling loop: check for new completed chunks and transcribe them
+  const pollInterval = setInterval(async () => {
+    if (!running) return;
+
+    const chunks = capture.getCompletedChunks();
+    for (const chunkPath of chunks) {
+      await processChunk(chunkPath);
+    }
+  }, 5000); // Check every 5 seconds
+
+  const stop = async (): Promise<void> => {
+    running = false;
+    clearInterval(pollInterval);
+
+    // Stop ffmpeg (this finalizes the last chunk)
+    capture.stop();
+
+    // Wait a moment for the last chunk to be finalized
+    await new Promise((r) => setTimeout(r, 1000));
+
+    // Process any remaining chunks
+    const remaining = capture.getCompletedChunks();
+    for (const chunkPath of remaining) {
+      await processChunk(chunkPath);
+    }
+  };
+
+  const cleanup = (): void => {
+    capture.cleanup();
+  };
+
+  console.log(`  Audio pipeline started (sink: ${sinkName})`);
+
+  return {
+    stop,
+    cleanup,
+    getLastTranscriptAt: () => lastTranscriptAt,
+  };
+}