@sushanglewis/lincoln 1.5.0 → 1.5.1

package/framework/tools/lincoln-record/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "lincoln-record"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+anyhow = "1.0.103"
+chrono = { version = "0.4.45", features = ["serde"] }
+clap = { version = "4.6.1", features = ["derive"] }
+cpal = "0.18.1"
+crossbeam-channel = "0.5.16"
+dirs = "6.0.0"
+env_logger = "0.11.11"
+hound = "3.5.1"
+log = "0.4.33"
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.150"
+tokio = { version = "1.52.3", features = ["rt-multi-thread", "macros", "process", "signal", "fs"] }
+toml = "0.8"
+ureq = "3.0"
+whisper-rs = { version = "0.14", features = ["metal"] }
+
+[dev-dependencies]
+tempfile = "3.27.0"

package/framework/tools/lincoln-record/diarize/diarize.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Lightweight local speaker diarization for testing and fallback.
+
+This implementation uses zero-crossing rate heuristics and is intentionally
+simple. In production it should be replaced with whisperx + pyannote.audio
+once models and HuggingFace tokens are available.
+"""
+
+import argparse
+import json
+import math
+import struct
+import wave
+
+
+def read_mono_16bit(path: str) -> tuple[int, bytes]:
+    with wave.open(path, "rb") as wf:
+        channels = wf.getnchannels()
+        rate = wf.getframerate()
+        frames = wf.getnframes()
+        data = wf.readframes(frames)
+        if channels != 1:
+            raise ValueError("only mono WAV files are supported")
+        return rate, data
+
+
+def samples_from_bytes(data: bytes) -> list[float]:
+    count = len(data) // 2
+    ints = struct.unpack(f"<{count}h", data)
+    return [s / 32768.0 for s in ints]
+
+
+def zero_crossing_rate(samples: list[float]) -> float:
+    if len(samples) < 2:
+        return 0.0
+    crossings = sum(1 for i in range(1, len(samples)) if samples[i - 1] * samples[i] < 0)
+    return crossings / len(samples)
+
+
+def rms(samples: list[float]) -> float:
+    if not samples:
+        return 0.0
+    return math.sqrt(sum(s * s for s in samples) / len(samples))
+
+
+def diarize(path: str, window_seconds: float = 0.5) -> list[dict]:
+    rate, data = read_mono_16bit(path)
+    samples = samples_from_bytes(data)
+    window_size = int(rate * window_seconds)
+
+    features = []
+    for start in range(0, len(samples), window_size):
+        chunk = samples[start : start + window_size]
+        if rms(chunk) < 0.01:
+            continue
+        features.append(
+            {
+                "start": start / rate,
+                "end": min(start + window_size, len(samples)) / rate,
+                "zcr": zero_crossing_rate(chunk),
+            }
+        )
+
+    if not features:
+        return []
+
+    # Classify into two speakers by median zero-crossing rate.
+    zcrs = [f["zcr"] for f in features]
+    threshold = sum(zcrs) / len(zcrs)
+
+    segments = []
+    current_speaker = "Speaker 1" if features[0]["zcr"] <= threshold else "Speaker 2"
+    current_start = features[0]["start"]
+    current_end = features[0]["end"]
+
+    for feature in features[1:]:
+        speaker = "Speaker 1" if feature["zcr"] <= threshold else "Speaker 2"
+        if speaker == current_speaker:
+            current_end = feature["end"]
+        else:
+            segments.append(
+                {
+                    "start": current_start,
+                    "end": current_end,
+                    "speaker": current_speaker,
+                }
+            )
+            current_speaker = speaker
+            current_start = feature["start"]
+            current_end = feature["end"]
+
+    segments.append(
+        {
+            "start": current_start,
+            "end": current_end,
+            "speaker": current_speaker,
+        }
+    )
+    return segments
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Local speaker diarization")
+    parser.add_argument("audio", help="input WAV file")
+    parser.add_argument("--output", required=True, help="output JSON file")
+    parser.add_argument(
+        "--window", type=float, default=0.5, help="analysis window in seconds"
+    )
+    args = parser.parse_args()
+
+    segments = diarize(args.audio, args.window)
+    with open(args.output, "w", encoding="utf-8") as f:
+        json.dump(segments, f, indent=2)
+
+
+if __name__ == "__main__":
+    main()

package/framework/tools/lincoln-record/diarize/merge.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Merge diarization output with transcript segments."""
+
+import argparse
+import json
+
+
+def overlap(a_start: float, a_end: float, b_start: float, b_end: float) -> float:
+    return max(0.0, min(a_end, b_end) - max(a_start, b_start))
+
+
+def merge(transcript: list[dict], diarization: list[dict]) -> list[dict]:
+    merged = []
+    for t in transcript:
+        t_start = t.get("start", 0.0)
+        t_end = t.get("end", t_start)
+        best_speaker = None
+        best_overlap = 0.0
+        for d in diarization:
+            d_start = d.get("start", 0.0)
+            d_end = d.get("end", d_start)
+            ov = overlap(t_start, t_end, d_start, d_end)
+            if ov > best_overlap:
+                best_overlap = ov
+                best_speaker = d.get("speaker")
+        merged.append(
+            {
+                "start": t_start,
+                "end": t_end,
+                "speaker": best_speaker,
+                "text": t.get("text", ""),
+            }
+        )
+    return merged
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Merge diarization with transcript")
+    parser.add_argument("transcript", help="transcript JSON file")
+    parser.add_argument("diarization", help="diarization JSON file")
+    parser.add_argument("--output", required=True, help="output JSON file")
+    args = parser.parse_args()
+
+    with open(args.transcript, encoding="utf-8") as f:
+        transcript = json.load(f)
+    with open(args.diarization, encoding="utf-8") as f:
+        diarization = json.load(f)
+
+    merged = merge(transcript, diarization)
+    with open(args.output, "w", encoding="utf-8") as f:
+        json.dump(merged, f, indent=2)
+
+
+if __name__ == "__main__":
+    main()

package/framework/tools/lincoln-record/src/audio/capture/microphone.rs

@@ -0,0 +1,194 @@
+use crate::audio::source::AudioSource;
+use anyhow::{Context, Result};
+use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
+use cpal::{SampleFormat, Stream, StreamConfig};
+use crossbeam_channel::{Receiver, Select, Sender, bounded};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+const AUDIO_CHANNEL_CAPACITY: usize = 50;
+
+/// An [AudioSource] that captures live microphone input until stopped or the
+/// maximum duration is reached.
+pub struct MicrophoneSource {
+    sample_rate: u32,
+    channels: u16,
+    audio_sender: Sender<Option<Vec<f32>>>,
+    audio_receiver: Receiver<Option<Vec<f32>>>,
+    /// Kept alive so the OS continues to deliver samples while we iterate.
+    #[allow(dead_code)]
+    stream: Stream,
+    target_samples: usize,
+    stop_flag: Arc<AtomicBool>,
+    stop_sender: Sender<()>,
+    stop_receiver: Receiver<()>,
+}
+
+/// Handle that can request an early stop of a [MicrophoneSource].
+#[derive(Clone)]
+pub struct StopHandle {
+    sender: Sender<()>,
+}
+
+impl StopHandle {
+    /// Request a stop. The associated iterator will terminate after draining
+    /// any buffered audio chunks.
+    pub fn stop(&self) {
+        let _ = self.sender.try_send(());
+    }
+}
+
+impl MicrophoneSource {
+    /// Open the requested microphone (or the system default) and start capturing.
+    pub fn new(device_name: Option<&str>, duration_seconds: f32) -> Result<Self> {
+        anyhow::ensure!(duration_seconds > 0.0, "duration must be greater than zero");
+
+        let host = cpal::default_host();
+        let device = match device_name {
+            Some(name) => host
+                .input_devices()?
+                .find(|d| d.to_string() == name)
+                .with_context(|| format!("microphone not found: {}", name))?,
+            None => host
+                .default_input_device()
+                .context("no default input device")?,
+        };
+
+        let config = device.default_input_config()?;
+        let sample_rate = config.sample_rate();
+        let channels = config.channels();
+        let sample_format = config.sample_format();
+
+        let stream_config = StreamConfig {
+            channels,
+            sample_rate: config.sample_rate(),
+            buffer_size: cpal::BufferSize::Default,
+        };
+
+        let (audio_sender, audio_receiver) = bounded::<Option<Vec<f32>>>(AUDIO_CHANNEL_CAPACITY);
+        let callback_sender = audio_sender.clone();
+        let stop_flag = Arc::new(AtomicBool::new(false));
+        let callback_stop_flag = Arc::clone(&stop_flag);
+
+        let stream = match sample_format {
+            SampleFormat::F32 => device.build_input_stream(
+                stream_config,
+                move |data: &[f32], _: &cpal::InputCallbackInfo| {
+                    if callback_stop_flag.load(Ordering::Relaxed) {
+                        let _ = callback_sender.try_send(None);
+                        return;
+                    }
+                    if let Err(error) = callback_sender.try_send(Some(data.to_vec())) {
+                        log::warn!("dropping audio chunk: {}", error);
+                    }
+                },
+                |error| log::error!("microphone stream error: {}", error),
+                None,
+            ),
+            other => anyhow::bail!("unsupported sample format: {:?}", other),
+        }
+        .context("failed to build microphone stream")?;
+
+        stream.play().context("failed to start microphone stream")?;
+
+        let frames = (sample_rate as f32 * duration_seconds).ceil() as usize;
+        let target_samples = frames.saturating_mul(channels as usize);
+        let (stop_sender, stop_receiver) = bounded::<()>(1);
+
+        Ok(Self {
+            sample_rate,
+            channels,
+            audio_sender,
+            audio_receiver,
+            stream,
+            target_samples,
+            stop_flag,
+            stop_sender,
+            stop_receiver,
+        })
+    }
+
+    /// Return a handle that can be used to request an early stop.
+    pub fn stop_handle(&self) -> StopHandle {
+        StopHandle {
+            sender: self.stop_sender.clone(),
+        }
+    }
+
+    /// Signal the capture to stop. The iterator will terminate after draining
+    /// any buffered chunks.
+    pub fn stop(&self) {
+        self.stop_flag.store(true, Ordering::Relaxed);
+        let _ = self.audio_sender.try_send(None);
+    }
+}
+
+impl AudioSource for MicrophoneSource {
+    fn sample_rate(&self) -> u32 {
+        self.sample_rate
+    }
+
+    fn channels(&self) -> u16 {
+        self.channels
+    }
+
+    fn duration_seconds(&self) -> f32 {
+        (self.target_samples / (self.channels as usize).max(1)) as f32 / (self.sample_rate as f32)
+    }
+
+    fn iter(&self) -> Box<dyn Iterator<Item = f32> + Send + '_> {
+        Box::new(MicrophoneIter {
+            audio_receiver: &self.audio_receiver,
+            stop_receiver: &self.stop_receiver,
+            chunk: Vec::new(),
+            position: 0,
+            remaining: self.target_samples,
+        })
+    }
+}
+
+struct MicrophoneIter<'a> {
+    audio_receiver: &'a Receiver<Option<Vec<f32>>>,
+    stop_receiver: &'a Receiver<()>,
+    chunk: Vec<f32>,
+    position: usize,
+    remaining: usize,
+}
+
+impl Iterator for MicrophoneIter<'_> {
+    type Item = f32;
+
+    fn next(&mut self) -> Option<f32> {
+        loop {
+            if self.remaining == 0 {
+                return None;
+            }
+            if self.position < self.chunk.len() {
+                let sample = self.chunk[self.position];
+                self.position += 1;
+                self.remaining -= 1;
+                return Some(sample);
+            }
+
+            let mut select = Select::new();
+            let audio_handle = select.recv(self.audio_receiver);
+            let stop_handle = select.recv(self.stop_receiver);
+            let oper = select.select();
+
+            match oper.index() {
+                index if index == audio_handle => match oper.recv(self.audio_receiver) {
+                    Ok(Some(chunk)) => {
+                        self.chunk = chunk;
+                        self.position = 0;
+                    }
+                    Ok(None) | Err(_) => return None,
+                },
+                index if index == stop_handle => {
+                    let _ = oper.recv(self.stop_receiver);
+                    return None;
+                }
+                _ => return None,
+            }
+        }
+    }
+}

package/framework/tools/lincoln-record/src/audio/capture/mod.rs

@@ -0,0 +1 @@
+pub mod microphone;

package/framework/tools/lincoln-record/src/audio/devices.rs

@@ -0,0 +1,20 @@
+use cpal::traits::HostTrait;
+use log::warn;
+
+/// Enumerate the names of all available audio input devices.
+pub fn list_input_devices() -> Result<Vec<String>, cpal::Error> {
+    let host = cpal::default_host();
+    let devices = host.input_devices()?;
+    Ok(devices.map(|device| device.to_string()).collect())
+}
+
+/// Return the name of the default audio input device, if any.
+pub fn default_input_device() -> Option<String> {
+    let host = cpal::default_host();
+    host.default_input_device().map(|device| device.to_string())
+}
+
+/// Log a warning when device enumeration fails so callers can still fall back.
+pub fn log_device_enumeration_error(error: &cpal::Error) {
+    warn!("failed to enumerate audio input devices: {}", error);
+}

package/framework/tools/lincoln-record/src/audio/mod.rs

@@ -0,0 +1,5 @@
+pub mod capture;
+pub mod devices;
+pub mod resampler;
+pub mod saver;
+pub mod source;

package/framework/tools/lincoln-record/src/audio/resampler.rs

@@ -0,0 +1,44 @@
+use anyhow::{Result, ensure};
+
+/// Naive linear-interpolation resampling for interleaved `f32` PCM.
+///
+/// This is intentionally simple for Phase 2; it will be replaced with a
+/// higher-quality resampler once the pipeline stabilizes.
+pub fn resample_interleaved(
+    input: &[f32],
+    input_rate: u32,
+    output_rate: u32,
+    channels: u16,
+) -> Result<Vec<f32>> {
+    ensure!(input_rate > 0, "input_rate must be greater than zero");
+    ensure!(output_rate > 0, "output_rate must be greater than zero");
+    let channels = channels as usize;
+    ensure!(channels > 0, "channels must be greater than zero");
+    ensure!(
+        input.len().is_multiple_of(channels),
+        "input length must be a multiple of channels"
+    );
+
+    let input_frames = input.len() / channels;
+    let output_frames =
+        (input_frames as f64 * output_rate as f64 / input_rate as f64).ceil() as usize;
+    let ratio = input_rate as f64 / output_rate as f64;
+
+    let mut output = Vec::with_capacity(output_frames.saturating_mul(channels));
+
+    for out_frame in 0..output_frames {
+        let in_pos = out_frame as f64 * ratio;
+        let index = in_pos as usize;
+        let frac = in_pos - index as f64;
+        let next_index = (index + 1).min(input_frames.saturating_sub(1));
+
+        for channel in 0..channels {
+            let current = input[index * channels + channel];
+            let next = input[next_index * channels + channel];
+            let sample = current + (next - current) * frac as f32;
+            output.push(sample);
+        }
+    }
+
+    Ok(output)
+}

package/framework/tools/lincoln-record/src/audio/saver.rs

@@ -0,0 +1,87 @@
+use crate::audio::resampler::resample_interleaved;
+use crate::audio::source::AudioSource;
+use anyhow::{Context, Result, bail};
+use hound::{WavSpec, WavWriter};
+use std::path::Path;
+
+const MAX_AMPLITUDE: f32 = i16::MAX as f32;
+
+/// Write all samples from `source` to a 16-bit PCM WAV file at `output`.
+///
+/// If `target_sample_rate` or `target_channels` differ from the source, the
+/// samples are resampled and duplicated/mixed down using simple rules.
+pub fn write_source_to_wav(
+    source: &dyn AudioSource,
+    output: &Path,
+    target_sample_rate: u32,
+    target_channels: u16,
+) -> Result<()> {
+    anyhow::ensure!(
+        target_sample_rate > 0,
+        "target_sample_rate must be greater than zero"
+    );
+    anyhow::ensure!(
+        target_channels > 0,
+        "target_channels must be greater than zero"
+    );
+
+    let spec = WavSpec {
+        channels: target_channels,
+        sample_rate: target_sample_rate,
+        bits_per_sample: 16,
+        sample_format: hound::SampleFormat::Int,
+    };
+
+    let mut writer = WavWriter::create(output, spec)
+        .with_context(|| format!("failed to create wav writer: {}", output.display()))?;
+
+    let frames = (source.sample_rate() as f32 * source.duration_seconds()).max(0.0) as usize;
+    let expected_samples = frames.saturating_mul(source.channels() as usize);
+    let samples: Vec<f32> = source.iter().take(expected_samples).collect();
+
+    let final_samples = if source.sample_rate() != target_sample_rate {
+        resample_interleaved(
+            &samples,
+            source.sample_rate(),
+            target_sample_rate,
+            source.channels(),
+        )?
+    } else {
+        samples
+    };
+
+    let final_channels = target_channels as usize;
+    let source_channels = source.channels() as usize;
+
+    for frame in final_samples.chunks(source_channels) {
+        match (source_channels, final_channels) {
+            (1, 2) => {
+                let value = frame.first().copied().unwrap_or(0.0);
+                writer.write_sample(to_i16(value))?;
+                writer.write_sample(to_i16(value))?;
+            }
+            (2, 1) => {
+                let left = frame.first().copied().unwrap_or(0.0);
+                let right = frame.get(1).copied().unwrap_or(0.0);
+                writer.write_sample(to_i16((left + right) * 0.5))?;
+            }
+            (s, t) if s == t => {
+                for value in frame {
+                    writer.write_sample(to_i16(*value))?;
+                }
+            }
+            _ => bail!(
+                "unsupported channel conversion from {} to {}",
+                source_channels,
+                final_channels
+            ),
+        }
+    }
+
+    writer.finalize()?;
+    Ok(())
+}
+
+fn to_i16(sample: f32) -> i16 {
+    (sample.clamp(-1.0, 1.0) * MAX_AMPLITUDE) as i16
+}

package/framework/tools/lincoln-record/src/audio/source.rs

@@ -0,0 +1,104 @@
+use std::f32::consts::PI;
+
+use anyhow::Result;
+
+/// Metadata describing an audio source.
+pub trait AudioSource: Send {
+    /// Sample rate in Hz.
+    fn sample_rate(&self) -> u32;
+    /// Number of interleaved channels.
+    fn channels(&self) -> u16;
+    /// Total duration in seconds.
+    fn duration_seconds(&self) -> f32;
+    /// Return an iterator yielding interleaved `f32` PCM samples.
+    fn iter(&self) -> Box<dyn Iterator<Item = f32> + Send + '_>;
+}
+
+/// A finite sine-wave source for tests and calibration.
+pub struct SineWaveSource {
+    sample_rate: f32,
+    channels: u16,
+    frequency: f32,
+    duration: f32,
+}
+
+impl SineWaveSource {
+    pub fn new(sample_rate: f32, channels: u16, frequency: f32, duration: f32) -> Result<Self> {
+        anyhow::ensure!(sample_rate > 0.0, "sample_rate must be greater than zero");
+        anyhow::ensure!(channels > 0, "channels must be greater than zero");
+        anyhow::ensure!(duration >= 0.0, "duration must be non-negative");
+
+        Ok(Self {
+            sample_rate,
+            channels,
+            frequency,
+            duration,
+        })
+    }
+}
+
+impl AudioSource for SineWaveSource {
+    fn sample_rate(&self) -> u32 {
+        self.sample_rate as u32
+    }
+
+    fn channels(&self) -> u16 {
+        self.channels
+    }
+
+    fn duration_seconds(&self) -> f32 {
+        self.duration
+    }
+
+    fn iter(&self) -> Box<dyn Iterator<Item = f32> + Send + '_> {
+        let sample_rate = self.sample_rate;
+        let frequency = self.frequency;
+        let channels = self.channels as usize;
+        let total_samples =
+            ((sample_rate * self.duration).ceil().max(0.0) as usize).saturating_mul(channels);
+        Box::new((0..total_samples).map(move |index| {
+            let sample_index = index / channels;
+            let t = sample_index as f32 / sample_rate;
+            (2.0 * PI * frequency * t).sin()
+        }))
+    }
+}
+
+/// An in-memory audio source for tests and offline processing.
+pub struct InMemorySource {
+    samples: Vec<f32>,
+    sample_rate: u32,
+    channels: u16,
+}
+
+impl InMemorySource {
+    pub fn new(samples: Vec<f32>, sample_rate: u32, channels: u16, duration: f32) -> Self {
+        let expected = ((sample_rate as f32 * duration.max(0.0)).ceil() as usize)
+            .saturating_mul(channels.max(1) as usize)
+            .min(samples.len());
+        Self {
+            samples: samples.into_iter().take(expected).collect(),
+            sample_rate,
+            channels,
+        }
+    }
+}
+
+impl AudioSource for InMemorySource {
+    fn sample_rate(&self) -> u32 {
+        self.sample_rate
+    }
+
+    fn channels(&self) -> u16 {
+        self.channels
+    }
+
+    fn duration_seconds(&self) -> f32 {
+        let frames = self.samples.len() / (self.channels as usize).max(1);
+        frames as f32 / self.sample_rate as f32
+    }
+
+    fn iter(&self) -> Box<dyn Iterator<Item = f32> + Send + '_> {
+        Box::new(self.samples.iter().copied())
+    }
+}