@sushanglewis/lincoln 1.5.0 → 1.5.2

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

@@ -0,0 +1,248 @@
+use crate::config::Config;
+use anyhow::{Context, Result};
+use std::io::{Read, Write};
+use std::path::{Path, PathBuf};
+
+const HUGGINGFACE_BASE: &str = "https://huggingface.co/ggerganov/whisper.cpp/resolve/main";
+const HF_MIRROR_BASE: &str = "https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main";
+
+/// Known Whisper model names and their published filenames.
+fn model_filename(name: &str) -> Option<&str> {
+    match name {
+        "tiny" => Some("ggml-tiny.bin"),
+        "base" => Some("ggml-base.bin"),
+        "small" => Some("ggml-small.bin"),
+        "medium" => Some("ggml-medium.bin"),
+        "large-v1" => Some("ggml-large-v1.bin"),
+        "large-v2" => Some("ggml-large-v2.bin"),
+        "large-v3" => Some("ggml-large-v3.bin"),
+        "large-v3-turbo" => Some("ggml-large-v3-turbo.bin"),
+        _ => None,
+    }
+}
+
+fn model_url(name: &str) -> Option<String> {
+    model_filename(name).map(|file| format!("{}/{}", HUGGINGFACE_BASE, file))
+}
+
+fn model_name_from_arg(model_arg: Option<&Path>) -> String {
+    model_arg
+        .and_then(|path| {
+            if path.is_file() || looks_like_file_path(path) {
+                // File paths are handled separately; do not treat them as model names.
+                None
+            } else {
+                path.file_name().and_then(|name| name.to_str()).map(|s| s.to_string())
+            }
+        })
+        .unwrap_or_default()
+}
+
+fn looks_like_file_path(path: &Path) -> bool {
+    path.extension().is_some()
+        || path
+            .parent()
+            .map(|parent| !parent.as_os_str().is_empty())
+            .unwrap_or(false)
+}
+
+/// Return the default model-cache directory (`~/.cache/lincoln/models`).
+pub fn default_cache_dir() -> PathBuf {
+    dirs::home_dir()
+        .map(|home| home.join(".cache").join("lincoln").join("models"))
+        .unwrap_or_else(|| PathBuf::from(".lincoln").join("cache").join("models"))
+}
+
+/// Resolve the absolute path to the Whisper model.
+///
+/// Priority:
+/// 1. `model_arg` if it points to an existing file.
+/// 2. `model_arg` as a model name inside the cache directory.
+/// 3. `config.transcription.model` as a model name inside the cache directory.
+///
+/// Returns an error with download instructions if the file is missing.
+pub fn resolve_model_path(model_arg: Option<&Path>, config: &Config) -> Result<PathBuf> {
+    let cache_dir = config
+        .model_cache_dir
+        .clone()
+        .unwrap_or_else(default_cache_dir);
+    let engine = config.transcription.engine.clone();
+
+    if let Some(path) = model_arg.filter(|p| p.is_file() || looks_like_file_path(p)) {
+        return Ok(path.to_path_buf());
+    }
+
+    let model_name = model_name_from_arg(model_arg);
+    let model_name = if model_name.is_empty() {
+        config.transcription.model.as_str()
+    } else {
+        model_name.as_str()
+    };
+
+    let path = cache_path_for_model(model_name, &engine, &cache_dir);
+
+    if model_filename(model_name).is_some() {
+        return Ok(path);
+    }
+
+    let url = manual_download_url(model_name);
+
+    anyhow::bail!(
+        "Whisper model not found: {}\n\n\
+         You can either:\n\
+         1. Download it automatically: lincoln-record warmup --model {}\n\
+         2. Download manually: {}\n\
+         3. Place it at: {}\n\n\
+         To use a different model, pass --model <name-or-path> or set it in ~/.lincolnrc.",
+        model_name,
+        model_name,
+        url,
+        path.display()
+    )
+}
+
+/// Resolve the cache path for a model name without checking existence.
+pub fn cache_path_for_model(name: &str, engine: &str, cache_dir: &Path) -> PathBuf {
+    cache_dir.join(engine).join(format!("ggml-{}.bin", name))
+}
+
+/// Return the manual download URL for a known model name.
+pub fn manual_download_url(name: &str) -> String {
+    model_url(name).unwrap_or_else(|| format!("{}/ggml-{}.bin", HUGGINGFACE_BASE, name))
+}
+
+fn mirror_download_url(name: &str) -> String {
+    model_filename(name)
+        .map(|file| format!("{}/{}", HF_MIRROR_BASE, file))
+        .unwrap_or_else(|| format!("{}/ggml-{}.bin", HF_MIRROR_BASE, name))
+}
+
+/// Validate that a model name is known.
+pub fn validate_model_name(name: &str) -> Result<()> {
+    if model_filename(name).is_some() {
+        Ok(())
+    } else {
+        anyhow::bail!(
+            "unknown model '{}'. Known models: tiny, base, small, medium, large-v1, large-v2, large-v3, large-v3-turbo",
+            name
+        )
+    }
+}
+
+/// Download a Whisper model into the cache directory.
+///
+/// Progress is reported via `progress(downloaded_bytes, total_bytes_hint)`.
+/// If the model file already exists, it is returned immediately.
+/// If the primary HuggingFace host is unreachable, falls back to hf-mirror.com.
+pub fn download_model<F>(
+    name: &str,
+    engine: &str,
+    cache_dir: &Path,
+    mut progress: F,
+) -> Result<PathBuf>
+where
+    F: FnMut(usize, Option<u64>),
+{
+    validate_model_name(name)?;
+    let dest = cache_path_for_model(name, engine, cache_dir);
+    if dest.is_file() {
+        return Ok(dest);
+    }
+
+    let parent = dest
+        .parent()
+        .context("model cache path has no parent directory")?;
+    std::fs::create_dir_all(parent)
+        .with_context(|| format!("failed to create cache directory: {}", parent.display()))?;
+
+    let urls = [manual_download_url(name), mirror_download_url(name)];
+    let mut last_error: Option<anyhow::Error> = None;
+
+    for url in urls {
+        match download_from_url(&url, &dest, &mut progress) {
+            Ok(()) => return Ok(dest),
+            Err(error) => {
+                last_error = Some(error.context(format!("failed to download from: {}", url)));
+            }
+        }
+    }
+
+    Err(last_error.unwrap_or_else(|| anyhow::anyhow!("download failed")))
+}
+
+fn download_from_url<F>(url: &str, dest: &Path, progress: &mut F) -> Result<()>
+where
+    F: FnMut(usize, Option<u64>),
+{
+    let mut response = ureq::get(url)
+        .call()
+        .with_context(|| format!("failed to start download from: {}", url))?;
+
+    let total = response.body().content_length();
+
+    let temp = dest.with_extension("bin.tmp");
+    let mut file = std::fs::File::create(&temp)
+        .with_context(|| format!("failed to create temporary file: {}", temp.display()))?;
+
+    let mut reader = response.body_mut().as_reader();
+    let mut buffer = [0u8; 8192];
+    let mut downloaded = 0usize;
+
+    loop {
+        let n = reader
+            .read(&mut buffer)
+            .context("failed to read download chunk")?;
+        if n == 0 {
+            break;
+        }
+        file.write_all(&buffer[..n])
+            .with_context(|| format!("failed to write to: {}", temp.display()))?;
+        downloaded += n;
+        progress(downloaded, total);
+    }
+
+    file.flush().context("failed to flush downloaded model")?;
+    drop(file);
+
+    std::fs::rename(&temp, dest)
+        .with_context(|| format!("failed to move downloaded model to: {}", dest.display()))?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_cache_dir_under_home() {
+        let dir = default_cache_dir();
+        assert!(dir.to_string_lossy().contains(".cache/lincoln/models"));
+    }
+
+    #[test]
+    fn download_model_returns_existing_file_without_download() {
+        let tmp = std::env::temp_dir().join(format!(
+            "lincoln-model-test-{}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&tmp).unwrap();
+        let cache_dir = tmp.join("cache");
+        let dest = cache_path_for_model("tiny", "whisper", &cache_dir);
+        std::fs::create_dir_all(dest.parent().unwrap()).unwrap();
+        std::fs::write(&dest, b"fake model").unwrap();
+
+        let result = download_model("tiny", "whisper", &cache_dir, |_downloaded, _total| {});
+        assert_eq!(result.unwrap(), dest);
+
+        std::fs::remove_dir_all(&tmp).ok();
+    }
+
+    #[test]
+    fn mirror_url_matches_hf_mirror_host() {
+        assert_eq!(
+            mirror_download_url("base"),
+            "https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-base.bin"
+        );
+    }
+}

package/framework/tools/lincoln-record/src/output/metadata.rs

@@ -0,0 +1,30 @@
+use serde::{Deserialize, Serialize};
+
+/// Recording session metadata written alongside `transcript.md`.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct SessionMetadata {
+    pub session_id: String,
+    pub process_slug: String,
+    pub started_at: String,
+    pub ended_at: Option<String>,
+    pub engine: String,
+    pub model: String,
+    pub diarization: bool,
+    pub devices: DeviceInfo,
+    pub files: FileInfo,
+}
+
+/// Audio devices used for the session.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct DeviceInfo {
+    pub microphone: String,
+    pub system: Option<String>,
+}
+
+/// Output file names relative to the session directory.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct FileInfo {
+    pub transcript: String,
+    pub audio: String,
+    pub metadata: String,
+}

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

@@ -0,0 +1,2 @@
+pub mod metadata;
+pub mod transcript;

package/framework/tools/lincoln-record/src/output/transcript.rs

@@ -0,0 +1,42 @@
+pub use crate::transcription::provider::TranscriptSegment;
+
+/// Format segments as a Lincoln-standard `transcript.md` document.
+pub fn format_transcript(session_id: &str, segments: &[TranscriptSegment]) -> String {
+    let mut speakers: Vec<String> = segments
+        .iter()
+        .filter_map(|segment| segment.speaker.clone())
+        .fold(Vec::new(), |mut acc, speaker| {
+            if !acc.contains(&speaker) {
+                acc.push(speaker);
+            }
+            acc
+        });
+    speakers.sort();
+
+    let mut output = String::new();
+    output.push_str(&format!("# Interview: {}\n\n", session_id));
+    output.push_str("## Speakers\n\n");
+    for speaker in &speakers {
+        output.push_str(&format!("- {}\n", speaker));
+    }
+    output.push_str("\n## Transcript\n\n");
+
+    for segment in segments {
+        let speaker = segment.speaker.as_deref().unwrap_or("Unknown");
+        let timestamp = format_timestamp(segment.start);
+        output.push_str(&format!(
+            "**[{}] {}**: {}\n\n",
+            timestamp, speaker, segment.text
+        ));
+    }
+
+    output
+}
+
+fn format_timestamp(seconds: f64) -> String {
+    let total_seconds = seconds as u64;
+    let hours = total_seconds / 3600;
+    let minutes = (total_seconds % 3600) / 60;
+    let secs = total_seconds % 60;
+    format!("{:02}:{:02}:{:02}", hours, minutes, secs)
+}

package/framework/tools/lincoln-record/src/transcription/diarization.rs

@@ -0,0 +1,64 @@
+use crate::transcription::provider::TranscriptSegment;
+use anyhow::{Context, Result};
+use std::path::Path;
+use std::process::Command;
+
+/// Run the Python diarization sidecar on `audio_path` and merge the result with
+/// `transcript_segments`. Returns a new segment list with speaker labels.
+pub fn diarize_and_merge(
+    audio_path: &Path,
+    transcript_segments: &[TranscriptSegment],
+    work_dir: &Path,
+) -> Result<Vec<TranscriptSegment>> {
+    let transcript_json = work_dir.join("transcripts.json");
+    let diarization_json = work_dir.join("diarization.json");
+    let merged_json = work_dir.join("merged.json");
+
+    std::fs::write(
+        &transcript_json,
+        serde_json::to_string_pretty(transcript_segments)?,
+    )
+    .with_context(|| "failed to write transcripts.json")?;
+
+    let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
+    let diarize_script = project_root.join("diarize/diarize.py");
+    let merge_script = project_root.join("diarize/merge.py");
+
+    let diarize_output = Command::new("python3")
+        .arg(&diarize_script)
+        .arg(audio_path)
+        .arg("--output")
+        .arg(&diarization_json)
+        .output()
+        .with_context(|| format!("failed to execute {}", diarize_script.display()))?;
+    if !diarize_output.status.success() {
+        anyhow::bail!(
+            "{} failed: {}",
+            diarize_script.display(),
+            String::from_utf8_lossy(&diarize_output.stderr)
+        );
+    }
+
+    let merge_output = Command::new("python3")
+        .arg(&merge_script)
+        .arg(&transcript_json)
+        .arg(&diarization_json)
+        .arg("--output")
+        .arg(&merged_json)
+        .output()
+        .with_context(|| format!("failed to execute {}", merge_script.display()))?;
+    if !merge_output.status.success() {
+        anyhow::bail!(
+            "{} failed: {}",
+            merge_script.display(),
+            String::from_utf8_lossy(&merge_output.stderr)
+        );
+    }
+
+    let raw = std::fs::read_to_string(&merged_json)
+        .with_context(|| format!("failed to read {}", merged_json.display()))?;
+    let segments: Vec<TranscriptSegment> =
+        serde_json::from_str(&raw).with_context(|| "failed to parse merged diarization json")?;
+
+    Ok(segments)
+}

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

@@ -0,0 +1,3 @@
+pub mod diarization;
+pub mod provider;
+pub mod whisper;

package/framework/tools/lincoln-record/src/transcription/provider.rs

@@ -0,0 +1,43 @@
+use anyhow::Result;
+use serde::{Deserialize, Serialize};
+use std::path::Path;
+
+/// A single transcript segment with timing and optional speaker label.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptSegment {
+    pub start: f64,
+    pub end: f64,
+    pub speaker: Option<String>,
+    pub text: String,
+}
+
+/// Abstraction over local transcription engines.
+pub trait TranscriptionProvider: Send + Sync {
+    /// Transcribe `audio_path` and return segments ordered by time.
+    fn transcribe(
+        &self,
+        audio_path: &Path,
+        language: Option<&str>,
+    ) -> Result<Vec<TranscriptSegment>>;
+}
+
+/// A deterministic provider for tests and development.
+pub struct MockProvider {
+    segments: Vec<TranscriptSegment>,
+}
+
+impl MockProvider {
+    pub fn new(segments: Vec<TranscriptSegment>) -> Self {
+        Self { segments }
+    }
+}
+
+impl TranscriptionProvider for MockProvider {
+    fn transcribe(
+        &self,
+        _audio_path: &Path,
+        _language: Option<&str>,
+    ) -> Result<Vec<TranscriptSegment>> {
+        Ok(self.segments.clone())
+    }
+}

package/framework/tools/lincoln-record/src/transcription/whisper.rs

@@ -0,0 +1,176 @@
+use crate::audio::resampler::resample_interleaved;
+use crate::transcription::provider::{TranscriptSegment, TranscriptionProvider};
+use anyhow::{Context, Result};
+use hound::WavReader;
+use std::path::Path;
+use whisper_rs::{FullParams, SamplingStrategy, WhisperContext, WhisperContextParameters};
+
+const WHISPER_SAMPLE_RATE: u32 = 16000;
+const WHISPER_CHANNELS: u16 = 1;
+
+/// A local Whisper transcription provider using whisper.cpp via `whisper-rs`.
+pub struct WhisperProvider {
+    model_path: std::path::PathBuf,
+    language: Option<String>,
+}
+
+impl WhisperProvider {
+    pub fn new(model_path: impl Into<std::path::PathBuf>, language: Option<String>) -> Self {
+        Self {
+            model_path: model_path.into(),
+            language,
+        }
+    }
+}
+
+impl TranscriptionProvider for WhisperProvider {
+    fn transcribe(&self,
+        audio_path: &Path,
+        language: Option<&str>,
+    ) -> Result<Vec<TranscriptSegment>> {
+        anyhow::ensure!(
+            self.model_path.is_file(),
+            "Whisper model not found: {}",
+            self.model_path.display()
+        );
+
+        let samples = load_whisper_audio(audio_path)
+            .with_context(|| format!("failed to load audio: {}", audio_path.display()))?;
+
+        let ctx = WhisperContext::new_with_params(
+            self.model_path.to_string_lossy().as_ref(),
+            WhisperContextParameters::default(),
+        )
+        .with_context(|| format!("failed to load Whisper model: {}", self.model_path.display()))?;
+
+        let mut params = FullParams::new(SamplingStrategy::Greedy { best_of: 1 });
+
+        let lang = language
+            .filter(|l| *l != "auto")
+            .or_else(|| self.language.as_deref().filter(|l| *l != "auto"));
+        params.set_language(lang);
+        params.set_print_special(false);
+        params.set_print_progress(false);
+        params.set_print_realtime(false);
+        params.set_print_timestamps(false);
+
+        let mut state = ctx.create_state().context("failed to create Whisper state")?;
+        state
+            .full(params, &samples)
+            .context("Whisper transcription failed")?;
+
+        let num_segments = state.full_n_segments().context("failed to get segment count")?;
+        let mut segments = Vec::with_capacity(num_segments as usize);
+        for index in 0..num_segments {
+            let text = state
+                .full_get_segment_text(index)
+                .context("failed to get segment text")?;
+            let start = state
+                .full_get_segment_t0(index)
+                .context("failed to get segment start")? as f64 / 1000.0;
+            let end = state
+                .full_get_segment_t1(index)
+                .context("failed to get segment end")? as f64 / 1000.0;
+            segments.push(TranscriptSegment {
+                start,
+                end,
+                speaker: None,
+                text: text.trim().to_string(),
+            });
+        }
+
+        Ok(segments)
+    }
+}
+
+/// Load a WAV file and convert it to 16 kHz mono f32 samples for Whisper.
+fn load_whisper_audio(path: &Path) -> Result<Vec<f32>> {
+    let mut reader = WavReader::open(path)
+        .with_context(|| format!("failed to open wav: {}", path.display()))?;
+    let spec = reader.spec();
+
+    anyhow::ensure!(
+        spec.sample_rate > 0,
+        "invalid sample rate: {}",
+        spec.sample_rate
+    );
+
+    let samples: Vec<f32> = match spec.sample_format {
+        hound::SampleFormat::Int => reader
+            .samples::<i16>()
+            .map(|sample| sample.map(|s| s as f32 / i16::MAX as f32))
+            .collect::<Result<_, _>>()
+            .context("failed to read i16 samples")?,
+        hound::SampleFormat::Float => reader
+            .samples::<f32>()
+            .collect::<Result<_, _>>()
+            .context("failed to read f32 samples")?,
+    };
+
+    let channels = spec.channels;
+    let mono = if channels == 1 {
+        samples
+    } else {
+        downmix_to_mono(&samples, channels)
+            .context("failed to downmix audio to mono")?
+    };
+
+    if spec.sample_rate == WHISPER_SAMPLE_RATE {
+        return Ok(mono);
+    }
+
+    resample_interleaved(
+        &mono,
+        spec.sample_rate,
+        WHISPER_SAMPLE_RATE,
+        WHISPER_CHANNELS,
+    )
+    .context("failed to resample audio to 16 kHz")
+}
+
+fn downmix_to_mono(samples: &[f32], channels: u16) -> Result<Vec<f32>> {
+    let channels = channels as usize;
+    anyhow::ensure!(channels > 0, "channels must be greater than zero");
+    anyhow::ensure!(
+        samples.len().is_multiple_of(channels),
+        "sample length is not a multiple of channels"
+    );
+
+    let divisor = channels as f32;
+    Ok(samples
+        .chunks_exact(channels)
+        .map(|frame| frame.iter().sum::<f32>() / divisor)
+        .collect())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    #[test]
+    fn test_downmix_stereo_to_mono() {
+        let stereo = vec![1.0f32, 1.0f32, -1.0f32, -1.0f32, 0.5f32, 0.5f32];
+        let mono = downmix_to_mono(&stereo, 2).unwrap();
+        assert_eq!(mono, vec![1.0f32, -1.0f32, 0.5f32]);
+    }
+
+    #[test]
+    fn test_whisper_provider_missing_model_errors() {
+        let provider = WhisperProvider::new("/nonexistent/model.bin", None);
+        let result = provider.transcribe(Path::new("/nonexistent/audio.wav"), None);
+        assert!(result.is_err());
+        let msg = format!("{}", result.unwrap_err());
+        assert!(msg.contains("Whisper model not found"));
+    }
+
+    #[test]
+    #[ignore = "requires a local Whisper ggml model"]
+    fn test_whisper_provider_transcribes_fixture() {
+        let model_path = PathBuf::from(std::env::var("WHISPER_MODEL").unwrap());
+        let audio_path = PathBuf::from(std::env::var("WHISPER_AUDIO").unwrap());
+        let provider = WhisperProvider::new(&model_path, None);
+        let segments = provider.transcribe(&audio_path, None).unwrap();
+        assert!(!segments.is_empty());
+    }
+}