@sushanglewis/lincoln 1.5.0 → 1.5.2

package/framework/tools/lincoln-record/src/cli.rs

@@ -0,0 +1,96 @@
+use clap::Parser;
+use std::path::PathBuf;
+
+/// Top-level CLI for `lincoln-record`.
+#[derive(Debug, Clone, Parser)]
+#[command(name = "lincoln-record")]
+#[command(about = "Headless local recorder and transcriber for Lincoln interviews")]
+#[command(version)]
+pub enum Cli {
+    /// Record microphone and optional system audio.
+    Record(RecordArgs),
+    /// Stop a running recording session.
+    Stop(StopArgs),
+    /// Transcribe an existing audio file.
+    Transcribe(TranscribeArgs),
+    /// List available audio input devices.
+    Devices,
+    /// Download models and warm up caches.
+    Warmup(WarmupArgs),
+}
+
+/// Arguments for the `warmup` subcommand.
+#[derive(Debug, Clone, Parser)]
+pub struct WarmupArgs {
+    #[arg(long, help = "Model name to download")]
+    pub model: Option<String>,
+
+    #[arg(long, help = "Engine name")]
+    pub engine: Option<String>,
+
+    #[arg(long, help = "Output directory for the model cache")]
+    pub cache_dir: Option<PathBuf>,
+}
+
+/// Arguments for the `record` subcommand.
+#[derive(Debug, Clone, Parser)]
+pub struct RecordArgs {
+    #[arg(long, help = "Unique session identifier for this interview")]
+    pub session_id: String,
+
+    #[arg(long, help = "Microphone device name to use")]
+    pub mic: Option<String>,
+
+    #[arg(long, help = "Automatically capture system audio on macOS")]
+    pub system_auto: bool,
+
+    #[arg(long, default_value = "whisper", help = "Transcription engine")]
+    pub engine: String,
+
+    #[arg(long, help = "Model name or path")]
+    pub model: Option<String>,
+
+    #[arg(long, help = "Enable speaker diarization")]
+    pub diarize: bool,
+
+    #[arg(long, help = "Output directory")]
+    pub output: Option<PathBuf>,
+
+    #[arg(long, help = "Language code (e.g. en, zh)")]
+    pub language: Option<String>,
+
+    /// Recording duration in seconds. Hidden while full SIGINT stop control is in progress.
+    #[arg(long, hide = true)]
+    pub duration: Option<f32>,
+}
+
+/// Arguments for the `stop` subcommand.
+#[derive(Debug, Clone, Parser)]
+pub struct StopArgs {
+    #[arg(long, help = "Session identifier to stop")]
+    pub session_id: String,
+}
+
+/// Arguments for the `transcribe` subcommand.
+#[derive(Debug, Clone, Parser)]
+pub struct TranscribeArgs {
+    pub path: PathBuf,
+
+    #[arg(long, help = "Session identifier")]
+    pub session_id: Option<String>,
+
+    #[arg(long, default_value = "whisper", help = "Transcription engine")]
+    pub engine: String,
+
+    #[arg(long, help = "Model name or path")]
+    pub model: Option<String>,
+
+    #[arg(long, help = "Enable speaker diarization")]
+    pub diarize: bool,
+
+    #[arg(long, help = "Output directory")]
+    pub output: Option<PathBuf>,
+
+    #[arg(long, help = "Language code (e.g. en, zh)")]
+    pub language: Option<String>,
+}

package/framework/tools/lincoln-record/src/config.rs

@@ -0,0 +1,135 @@
+use anyhow::Context;
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+
+/// Top-level configuration for `lincoln-record`.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct Config {
+    #[serde(default)]
+    pub audio: AudioConfig,
+    #[serde(default)]
+    pub transcription: TranscriptionConfig,
+    #[serde(default)]
+    pub diarization: DiarizationConfig,
+    #[serde(default)]
+    pub output: OutputConfig,
+    #[serde(default)]
+    pub model_cache_dir: Option<std::path::PathBuf>,
+}
+
+/// Audio capture and pipeline settings.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct AudioConfig {
+    #[serde(default = "default_sample_rate")]
+    pub sample_rate: u32,
+    #[serde(default = "default_channels")]
+    pub channels: u16,
+}
+
+/// Transcription engine settings.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct TranscriptionConfig {
+    #[serde(default = "default_engine")]
+    pub engine: String,
+    #[serde(default = "default_model")]
+    pub model: String,
+    #[serde(default = "default_language")]
+    pub language: String,
+}
+
+/// Speaker diarization settings.
+#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
+pub struct DiarizationConfig {
+    #[serde(default)]
+    pub enabled: bool,
+    #[serde(default)]
+    pub hf_token: String,
+}
+
+/// Output formatting and retention settings.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+pub struct OutputConfig {
+    #[serde(default = "default_output_format")]
+    pub format: String,
+    #[serde(default = "default_keep_recording")]
+    pub keep_recording: bool,
+}
+
+impl Default for AudioConfig {
+    fn default() -> Self {
+        Self {
+            sample_rate: 48000,
+            channels: 2,
+        }
+    }
+}
+
+impl Default for TranscriptionConfig {
+    fn default() -> Self {
+        Self {
+            engine: default_engine(),
+            model: default_model(),
+            language: default_language(),
+        }
+    }
+}
+
+impl Default for OutputConfig {
+    fn default() -> Self {
+        Self {
+            format: "markdown".to_string(),
+            keep_recording: true,
+        }
+    }
+}
+
+impl Config {
+    /// Load configuration from `path`. Returns defaults if the file is missing.
+    pub fn load_from_path<P: AsRef<Path>>(path: P) -> anyhow::Result<Self> {
+        let path = path.as_ref();
+        if !path.exists() {
+            return Ok(Self::default());
+        }
+        let contents = std::fs::read_to_string(path)
+            .with_context(|| format!("failed to read config: {}", path.display()))?;
+        let config: Config = toml::from_str(&contents)
+            .with_context(|| format!("failed to parse config: {}", path.display()))?;
+        Ok(config)
+    }
+
+    /// Load configuration from `~/.lincolnrc`, falling back to defaults.
+    pub fn load() -> anyhow::Result<Self> {
+        let path = dirs::home_dir()
+            .map(|home| home.join(".lincolnrc"))
+            .unwrap_or_else(|| PathBuf::from(".lincolnrc"));
+        Self::load_from_path(path)
+    }
+}
+
+fn default_sample_rate() -> u32 {
+    48000
+}
+
+fn default_channels() -> u16 {
+    2
+}
+
+fn default_engine() -> String {
+    "whisper".to_string()
+}
+
+fn default_model() -> String {
+    "large-v3".to_string()
+}
+
+fn default_language() -> String {
+    "auto".to_string()
+}
+
+fn default_output_format() -> String {
+    "markdown".to_string()
+}
+
+fn default_keep_recording() -> bool {
+    true
+}

package/framework/tools/lincoln-record/src/lib.rs

@@ -0,0 +1,6 @@
+pub mod audio;
+pub mod cli;
+pub mod config;
+pub mod model;
+pub mod output;
+pub mod transcription;

package/framework/tools/lincoln-record/src/main.rs

@@ -0,0 +1,242 @@
+use anyhow::Context;
+use clap::Parser;
+use lincoln_record::audio::capture::microphone::MicrophoneSource;
+use lincoln_record::audio::devices::{
+    default_input_device, list_input_devices, log_device_enumeration_error,
+};
+use lincoln_record::audio::saver::write_source_to_wav;
+use lincoln_record::audio::source::AudioSource;
+use lincoln_record::cli::{Cli, RecordArgs, TranscribeArgs, WarmupArgs};
+use lincoln_record::config::Config;
+use lincoln_record::model::{default_cache_dir, download_model, resolve_model_path};
+use lincoln_record::output::metadata::{DeviceInfo, FileInfo, SessionMetadata};
+use lincoln_record::output::transcript::format_transcript;
+use lincoln_record::transcription::diarization::diarize_and_merge;
+use lincoln_record::transcription::provider::{
+    MockProvider, TranscriptSegment, TranscriptionProvider,
+};
+use lincoln_record::transcription::whisper::WhisperProvider;
+use std::path::PathBuf;
+
+#[tokio::main]
+async fn main() {
+    env_logger::init();
+
+    let config = match Config::load() {
+        Ok(config) => config,
+        Err(error) => {
+            log::error!("failed to load config: {:#}", error);
+            std::process::exit(1);
+        }
+    };
+
+    let result = match Cli::parse() {
+        Cli::Devices => {
+            run_devices();
+            Ok(())
+        }
+        Cli::Record(args) => run_record(args).await,
+        Cli::Transcribe(args) => run_transcribe(args, &config).await,
+        Cli::Warmup(args) => run_warmup(args, &config),
+        other => {
+            eprintln!("{:?} is not yet implemented", other);
+            std::process::exit(1);
+        }
+    };
+
+    if let Err(error) = result {
+        log::error!("{:#}", error);
+        std::process::exit(1);
+    }
+}
+
+fn run_devices() {
+    match default_input_device() {
+        Some(name) => println!("Default input: {}", name),
+        None => eprintln!("No default input device found"),
+    }
+    match list_input_devices() {
+        Ok(devices) => {
+            for name in devices {
+                println!("  {}", name);
+            }
+        }
+        Err(error) => log_device_enumeration_error(&error),
+    }
+}
+
+async fn run_record(args: RecordArgs) -> anyhow::Result<()> {
+    validate_session_id(&args.session_id)?;
+
+    let output_dir = args.output.unwrap_or_else(|| PathBuf::from("."));
+    let session_dir = output_dir.join(&args.session_id);
+    tokio::fs::create_dir_all(&session_dir).await?;
+
+    let output_path = session_dir.join("audio.wav");
+    let duration = args.duration.unwrap_or(30.0);
+    let mic = args.mic;
+
+    let output_path_clone = output_path.clone();
+    let source = MicrophoneSource::new(mic.as_deref(), duration)?;
+    let stop_handle = source.stop_handle();
+    let mut handle = tokio::task::spawn_blocking(move || {
+        write_source_to_wav(
+            &source,
+            &output_path_clone,
+            source.sample_rate(),
+            source.channels(),
+        )
+    });
+
+    tokio::select! {
+        _ = tokio::signal::ctrl_c() => {
+            log::info!("received stop signal, shutting down recording");
+            stop_handle.stop();
+            (&mut handle).await??;
+        }
+        result = &mut handle => {
+            result??;
+        }
+    }
+
+    println!("Wrote {}", output_path.display());
+    Ok(())
+}
+
+async fn run_transcribe(args: TranscribeArgs, config: &Config) -> anyhow::Result<()> {
+    let session_id = args.session_id.unwrap_or_else(|| {
+        args.path
+            .file_stem()
+            .unwrap_or_default()
+            .to_string_lossy()
+            .to_string()
+    });
+    validate_session_id(&session_id)?;
+
+    let output_dir = args.output.unwrap_or_else(|| PathBuf::from("."));
+    let session_dir = output_dir.join(&session_id);
+    tokio::fs::create_dir_all(&session_dir).await?;
+
+    let provider: Box<dyn TranscriptionProvider + Send + Sync> = match args.engine.as_str() {
+        "mock" => Box::new(MockProvider::new(vec![TranscriptSegment {
+            start: 0.0,
+            end: 1.0,
+            speaker: None,
+            text: "Mock transcription output".to_string(),
+        }])),
+        "whisper" => {
+            let model_arg = args.model.as_ref().map(|s| std::path::Path::new(s.as_str()));
+            let model_path = resolve_model_path(model_arg, config)?;
+            Box::new(WhisperProvider::new(
+                model_path,
+                language_choice(args.language.as_deref(), config.transcription.language.as_str()),
+            ))
+        }
+        other => anyhow::bail!(
+            "transcription engine '{}' is not yet implemented; use 'mock' or 'whisper'",
+            other
+        ),
+    };
+
+    let audio_path = args.path.clone();
+    let language = args.language.clone();
+    let diarize = args.diarize;
+    let diarize_work_dir = session_dir.clone();
+    let segments = tokio::task::spawn_blocking(move || {
+        let mut segs = provider.transcribe(&audio_path, language.as_deref())?;
+        if diarize {
+            segs = diarize_and_merge(&audio_path, &segs, &diarize_work_dir)?;
+        }
+        Ok::<_, anyhow::Error>(segs)
+    })
+    .await??;
+
+    let transcript = format_transcript(&session_id, &segments);
+    tokio::fs::write(session_dir.join("transcript.md"), transcript).await?;
+
+    let metadata = SessionMetadata {
+        session_id: session_id.clone(),
+        process_slug: "issue-25".to_string(),
+        started_at: chrono::Utc::now().to_rfc3339(),
+        ended_at: Some(chrono::Utc::now().to_rfc3339()),
+        engine: args.engine,
+        model: args.model.unwrap_or_else(|| config.transcription.model.clone()),
+        diarization: args.diarize,
+        devices: DeviceInfo {
+            microphone: "unknown".to_string(),
+            system: None,
+        },
+        files: FileInfo {
+            transcript: "transcript.md".to_string(),
+            audio: args
+                .path
+                .file_name()
+                .unwrap_or_default()
+                .to_string_lossy()
+                .to_string(),
+            metadata: "metadata.json".to_string(),
+        },
+    };
+    tokio::fs::write(
+        session_dir.join("metadata.json"),
+        serde_json::to_string_pretty(&metadata)?,
+    )
+    .await?;
+
+    println!("Wrote transcript and metadata to {}", session_dir.display());
+    Ok(())
+}
+
+fn run_warmup(args: WarmupArgs, config: &Config) -> anyhow::Result<()> {
+    let model_name = args
+        .model
+        .as_deref()
+        .unwrap_or(config.transcription.model.as_str());
+    let engine = args
+        .engine
+        .as_deref()
+        .unwrap_or(config.transcription.engine.as_str());
+    let cache_dir = args
+        .cache_dir
+        .clone()
+        .or_else(|| config.model_cache_dir.clone())
+        .unwrap_or_else(default_cache_dir);
+
+    eprintln!("Warming up {} model '{}' into {}...", engine, model_name, cache_dir.display());
+
+    let path = download_model(model_name, engine, &cache_dir, |downloaded, total| {
+        match total {
+            Some(t) => {
+                let pct = (downloaded as f64 / t as f64) * 100.0;
+                eprint!("\r  downloaded {} / {} bytes ({:.1}%)", downloaded, t, pct);
+            }
+            None => {
+                eprint!("\r  downloaded {} bytes", downloaded);
+            }
+        }
+    })
+    .context("model warmup failed")?;
+
+    eprintln!();
+    println!("Model ready at {}", path.display());
+    Ok(())
+}
+
+fn language_choice(cli: Option<&str>, config: &str) -> Option<String> {
+    cli.filter(|l| *l != "auto")
+        .or_else(|| if config == "auto" { None } else { Some(config) })
+        .map(|s| s.to_string())
+}
+
+fn validate_session_id(session_id: &str) -> anyhow::Result<()> {
+    if session_id.is_empty() {
+        anyhow::bail!("session-id must not be empty");
+    }
+    if session_id.len() > 128 {
+        anyhow::bail!("session-id must be 128 characters or fewer");
+    }
+    if session_id.contains('/') || session_id.contains('\\') || session_id.contains("..") {
+        anyhow::bail!("session-id must not contain path separators or parent references");
+    }
+    Ok(())
+}