use std::borrow::Cow;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use is_terminal::IsTerminal;
use serde_json::json;
use uuid::Uuid;
use crate::audio::{self, PcmData};
use crate::catalog::Catalog;
use crate::cli::TranscribeArgs;
use crate::commands::Ctx;
use crate::config;
use crate::error::Error;
use crate::gpu;
use crate::output::{self, Segment, TranscriptionResult, SCHEMA_VERSION};
use crate::paths::AppPaths;
pub(crate) fn transcribe(ctx: &mut Ctx<'_>, args: TranscribeArgs) -> Result<(), Error> {
let ndjson = args.ndjson;
let named = args.argv_targets();
let outcome = transcribe_inner(ctx, args);
let Err(err) = outcome else {
return outcome;
};
if !ndjson || ctx.error_reported || named.is_empty() {
return Err(err);
}
for target in &named {
let resolved = target.display().to_string();
output::write_error(
&err,
ctx.correlation_id,
ctx.surface,
Some(crate::error::TargetRef {
resolved: &resolved,
source: "argv",
}),
)?;
}
output::write_value(
&json!({
"schema_version": SCHEMA_VERSION,
"correlation_id": ctx.correlation_id,
"summary": true,
"ok": 0u64,
"failed": named.len() as u64,
"total": named.len() as u64,
}),
ctx.surface,
)?;
ctx.error_reported = true;
Err(err)
}
fn transcribe_inner(ctx: &mut Ctx<'_>, args: TranscribeArgs) -> Result<(), Error> {
gpu::warn_ignored_cuda_env(ctx.ui);
let effective = ctx.store.effective();
let model_name = args
.model
.clone()
.or(effective.model.clone())
.unwrap_or_else(|| "large-v3".into());
let language = args
.language
.clone()
.or(effective.language.clone())
.unwrap_or_else(|| "auto".into());
let language_source = if args.language.is_some() {
"argv"
} else if ctx.store.language.is_some() {
"config"
} else {
"default"
};
if !crate::engine::is_known_language(&language) {
return Err(Error::Usage(format!("unknown language: {language}")));
}
let seeds = config::Store::seeds();
let beam = args
.beam
.or(effective.beam)
.or(seeds.beam)
.unwrap_or_default();
if !config::BEAM_RANGE.contains(&beam) {
return Err(Error::Usage(config::range_message(
"beam",
&config::BEAM_RANGE,
)));
}
let vad = args.vad.or(effective.vad).or(seeds.vad).unwrap_or_default();
if !config::VAD_RANGE.contains(&vad) {
return Err(Error::Usage(config::range_message(
"vad",
&config::VAD_RANGE,
)));
}
let concurrency = args
.concurrency
.or(effective.concurrency)
.or(seeds.concurrency)
.unwrap_or_default();
if !config::CONCURRENCY_RANGE.contains(&concurrency) {
return Err(Error::Usage(config::range_message(
"concurrency",
&config::CONCURRENCY_RANGE,
)));
}
let device = args
.device
.or(effective.device)
.or(seeds.device)
.unwrap_or_default();
let timeout = ctx
.timeout
.or(effective.timeout)
.or(seeds.timeout)
.unwrap_or_default();
let max_duration = effective
.max_duration
.or(config::Store::seeds().max_duration)
.unwrap_or_default();
let catalog = Catalog::load_or_seed(ctx.paths, effective.origin())?;
let entry = catalog.get(&model_name)?.clone();
let max_memory = args.max_memory.unwrap_or(effective.max_memory.unwrap_or(0));
if max_memory > 0 && max_memory < entry.size_bytes {
return Err(Error::MemoryCap);
}
gpu::publish_memory_cap(max_memory);
let poll_ms = effective
.probe_poll_ms
.or(seeds.probe_poll_ms)
.unwrap_or_default();
gpu::publish_probe_poll_ms(poll_ms);
crate::media_helper::publish_helper_poll_ms(poll_ms);
gpu::publish_nvidia_smi_path(
effective
.nvidia_smi_path
.clone()
.or(seeds.nvidia_smi_path.clone())
.unwrap_or_default(),
);
crate::media_helper::publish_helper_args(
effective
.helper_args
.clone()
.or(seeds.helper_args.clone())
.unwrap_or_default(),
);
let (targets, source) = resolve_transcribe_targets(ctx, &args)?;
if args.dry_run {
let mut envelope = json!({
"schema_version": SCHEMA_VERSION,
"correlation_id": ctx.correlation_id,
"dry_run": true,
"would_transcribe": {
"files": targets.len(),
"model": model_name,
"language": language,
"beam_size": beam,
"device": device,
"concurrency": concurrency,
"vad": vad,
}
});
let designated = match targets.as_slice() {
[only] => Some(only.display().to_string()),
_ if targets.is_empty() && source == "stdin" => Some("-".to_string()),
_ => None,
};
if let (Some(resolved), Some(map)) = (designated, envelope.as_object_mut()) {
map.insert("target_resolved".into(), resolved.into());
map.insert("target_source".into(), source.into());
}
return output::write_value(&envelope, ctx.surface);
}
let deadline_target = match targets.as_slice() {
[only] => Some((only.display().to_string(), source)),
_ if targets.is_empty() && source == "stdin" => Some(("-".to_string(), source)),
_ => None,
};
let emits_summary = !targets.is_empty() && (args.ndjson || targets.len() > 1);
let armed = if timeout == 0 {
0
} else if emits_summary {
timeout.saturating_add(effective.timeout_grace.unwrap_or(5))
} else {
timeout
};
crate::signal::publish_deadline(timeout);
crate::signal::arm_deadline(armed, ctx.correlation_id, deadline_target);
let stdin_pcm = if targets.is_empty() && source == "stdin" {
let forced = args.input_format.as_ref().map(|f| f.as_str());
let bytes = read_stdin(ctx.no_input, max_duration, forced)?;
Some(audio::decode_bytes(&bytes, forced)?)
} else {
None
};
let helper =
crate::media_helper::resolve_helper(effective.helper.as_deref().unwrap_or_default())
.unwrap_or_default();
let named_pcm = if let [only] = targets.as_slice() {
refuse_over_duration(only, max_duration)?;
let helper_may_recover =
helper_retry_allowed(&helper, effective.helper_fallback.unwrap_or(true));
if !audio::is_video_path(only) && !helper_may_recover {
let started = Instant::now();
let pcm = decode_path_with_hint(only, args.input_format.map(|f| f.as_str()))?;
Some((pcm, started))
} else {
None
}
} else {
None
};
let gpu_info = gpu::probe_checked(device)?;
gpu::ensure_device(&gpu_info, device)?;
if !gpu_info.toolkit {
return Err(Error::ToolkitMissing);
}
gpu::ensure_vram(&gpu_info, entry.vram_bytes, concurrency)?;
match crate::model::verify(ctx.paths, &entry) {
Ok(_) => {}
Err(
Error::ModelNotFound { .. }
| Error::ModelSizeMismatch { .. }
| Error::ModelDigestMismatch { .. },
) => {
if ctx.offline {
return Err(Error::OfflineMissingModel { name: model_name });
}
let dl = effective.download_knobs();
crate::model::download(ctx.paths, &entry, &dl, ctx.offline)?;
}
Err(other) => return Err(other),
}
crate::engine::silence_native_logs();
let model_path = crate::model::model_path(ctx.paths, &entry);
let deadline = if timeout > 0 {
Some(Instant::now() + Duration::from_secs(timeout))
} else {
None
};
let hallucination_re = if effective.hallucination_filter.unwrap_or(true) {
let custom = effective.hallucination_patterns.clone().unwrap_or_default();
if custom.trim().is_empty() {
Some(Cow::Borrowed(audio::default_hallucination_regex()))
} else {
Some(Cow::Owned(audio::hallucination_regex_from(&[custom])?))
}
} else {
None
};
audio::publish_containers(
effective
.audio_extensions
.clone()
.or(seeds.audio_extensions.clone())
.unwrap_or_default(),
effective
.video_extensions
.clone()
.or(seeds.video_extensions.clone())
.unwrap_or_default(),
);
let vad_settings = audio::VadSettings::from_ms(
effective
.vad_frame_ms
.or(seeds.vad_frame_ms)
.unwrap_or_default(),
effective
.vad_rms_min
.or(seeds.vad_rms_min)
.unwrap_or_default(),
effective
.vad_rms_max
.or(seeds.vad_rms_max)
.unwrap_or_default(),
);
let knobs = ResolvedKnobs {
entry: &entry,
model_path: &model_path,
language: &language,
language_source,
beam,
vad,
device,
max_duration,
timestamps: args.timestamps,
input_format: args.input_format.map(|f| f.as_str()),
deadline,
helper: helper.clone(),
helper_fallback: effective.helper_fallback.unwrap_or(true),
max_memory,
hallucination: hallucination_re.as_deref(),
vad_settings,
};
let ndjson = args.ndjson || targets.len() > 1;
let mut transcript = TranscriptSink::open(args.output.as_deref())?;
if let Some(pcm) = stdin_pcm {
let result = finish_pcm(
ctx,
pcm,
"stdin".to_string(),
source,
&knobs,
Instant::now(),
)?;
transcript.push(&result.text)?;
output::write_json(&result, ctx.surface)?;
return Ok(());
}
let outcomes = run_targets(ctx, &targets, &knobs, source, concurrency, named_pcm);
let mut success = 0u64;
let mut errors = 0u64;
let mut fatal: Option<Error> = None;
for (target, outcome) in targets.iter().zip(outcomes) {
match outcome {
Ok(result) => {
success += 1;
transcript.push(&result.text)?;
output::write_json(&result, ctx.surface)?;
}
Err(e) => {
errors += 1;
if !ndjson {
return Err(e);
}
let resolved = target.display().to_string();
output::write_error(
&e,
ctx.correlation_id,
ctx.surface,
Some(crate::error::TargetRef {
resolved: &resolved,
source,
}),
)?;
if fatal.is_none() && (is_invocation_fatal(&e) || targets.len() == 1) {
fatal = Some(e);
}
}
}
}
if ndjson {
output::write_value(
&json!({
"schema_version": SCHEMA_VERSION,
"correlation_id": ctx.correlation_id,
"summary": true,
"ok": success,
"failed": errors,
"total": targets.len() as u64,
}),
ctx.surface,
)?;
}
match fatal {
Some(e) => {
ctx.error_reported = ndjson;
Err(e)
}
None => Ok(()),
}
}
struct TranscriptSink(Option<std::fs::File>);
impl TranscriptSink {
fn open(path: Option<&Path>) -> Result<Self, Error> {
match path {
None => Ok(Self(None)),
Some(p) => Ok(Self(Some(std::fs::File::create(p).map_err(Error::Io)?))),
}
}
fn push(&mut self, text: &str) -> Result<(), Error> {
let Some(file) = self.0.as_mut() else {
return Ok(());
};
use std::io::Write;
file.write_all(text.as_bytes()).map_err(Error::Io)?;
if !text.ends_with('\n') {
file.write_all(b"\n").map_err(Error::Io)?;
}
file.flush().map_err(Error::Io)
}
}
fn is_invocation_fatal(err: &Error) -> bool {
matches!(
err,
Error::Timeout | Error::Interrupted | Error::Terminated | Error::BrokenPipe
)
}
fn clone_fatal(err: &Error) -> Error {
match err {
Error::Timeout => Error::Timeout,
Error::Interrupted => Error::Interrupted,
Error::BrokenPipe => Error::BrokenPipe,
_ => Error::Terminated,
}
}
struct ResolvedKnobs<'a> {
entry: &'a crate::catalog::ModelEntry,
model_path: &'a Path,
language: &'a str,
language_source: &'static str,
beam: i32,
vad: f32,
device: u32,
max_duration: f64,
timestamps: bool,
input_format: Option<&'static str>,
deadline: Option<Instant>,
helper: String,
helper_fallback: bool,
max_memory: u64,
hallucination: Option<&'a regex::Regex>,
vad_settings: crate::audio::VadSettings,
}
fn helper_retry_allowed(helper: &str, helper_fallback: bool) -> bool {
helper_fallback && !helper.trim().is_empty()
}
fn run_targets(
ctx: &Ctx<'_>,
targets: &[PathBuf],
knobs: &ResolvedKnobs<'_>,
source: &'static str,
concurrency: usize,
pre_decoded: Option<(crate::audio::PcmData, Instant)>,
) -> Vec<Result<TranscriptionResult, Error>> {
if let (Some((pcm, started)), [only]) = (pre_decoded, targets) {
return vec![finish_pcm(
ctx,
pcm,
only.display().to_string(),
source,
knobs,
started,
)];
}
let next = std::sync::atomic::AtomicUsize::new(0);
let slots: Vec<std::sync::Mutex<Option<Result<TranscriptionResult, Error>>>> = (0..targets
.len())
.map(|_| std::sync::Mutex::new(None))
.collect();
let workers = concurrency.max(1).min(targets.len().max(1));
std::thread::scope(|scope| {
for _ in 0..workers {
let next = &next;
let slots = &slots;
scope.spawn(move || loop {
let i = next.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
if i >= targets.len() {
return;
}
let stopped = if knobs.deadline.map(|d| Instant::now() > d).unwrap_or(false) {
Some(Error::Timeout)
} else if crate::signal::is_shutdown_requested() {
Some(crate::signal::shutdown_error().unwrap_or(Error::Interrupted))
} else {
None
};
let outcome = match stopped {
Some(err) => Err(clone_fatal(&err)),
None => transcribe_path(ctx, &targets[i], knobs, source),
};
if let Ok(mut slot) = slots[i].lock() {
*slot = Some(outcome);
}
});
}
});
slots
.into_iter()
.map(|slot| {
slot.into_inner()
.ok()
.flatten()
.unwrap_or_else(|| Err(Error::WhisperInference("worker panicked".into())))
})
.collect()
}
fn resolve_transcribe_targets(
ctx: &Ctx<'_>,
args: &TranscribeArgs,
) -> Result<(Vec<PathBuf>, &'static str), Error> {
if args.use_active {
let marker = ctx.paths.active_target_file();
let raw = std::fs::read_to_string(&marker).map_err(|_| {
Error::Config(format!(
"no active target: pass --file, or write one absolute path into {}",
marker.display()
))
})?;
let path = PathBuf::from(raw.trim());
if !path.exists() {
return Err(Error::InputNotFound {
path: path.display().to_string(),
});
}
return Ok((vec![path], "active"));
}
let argv = args.argv_targets();
if !argv.is_empty() {
if argv.iter().all(|p| !p.exists()) {
return Err(Error::InputNotFound {
path: argv[0].display().to_string(),
});
}
return Ok((argv, "argv"));
}
if args.stdin || !std::io::stdin().is_terminal() {
if ctx.no_input && !args.stdin {
return Err(Error::NoInput);
}
return Ok((Vec::new(), "stdin"));
}
Err(Error::NoInput)
}
fn refuse_over_duration(path: &Path, max_duration: f64) -> Result<(), Error> {
if let Some(seconds) = audio::probe_duration(path) {
if seconds > max_duration {
return Err(Error::DurationCap);
}
}
Ok(())
}
fn transcribe_path(
ctx: &Ctx<'_>,
path: &Path,
knobs: &ResolvedKnobs<'_>,
source: &'static str,
) -> Result<TranscriptionResult, Error> {
let started = Instant::now();
refuse_over_duration(path, knobs.max_duration)?;
let pcm = if audio::is_video_path(path) {
decode_via_helper(ctx.paths, &knobs.helper, path, knobs.deadline)?
} else {
match decode_path_with_hint(path, knobs.input_format) {
Ok(p) => p,
Err(e)
if e.is_decode_fault()
&& helper_retry_allowed(&knobs.helper, knobs.helper_fallback) =>
{
decode_via_helper(ctx.paths, &knobs.helper, path, knobs.deadline).map_err(
|helper_err| {
if is_invocation_fatal(&helper_err) {
helper_err
} else {
e
}
},
)?
}
Err(e) => return Err(e),
}
};
finish_pcm(ctx, pcm, path.display().to_string(), source, knobs, started)
}
fn decode_via_helper(
paths: &AppPaths,
helper: &str,
path: &Path,
deadline: Option<Instant>,
) -> Result<PcmData, Error> {
let work = paths.work_dir().join(Uuid::now_v7().to_string());
crate::signal::register_temp(&work);
let result = std::fs::create_dir_all(&work)
.map_err(Error::Io)
.and_then(|()| crate::media_helper::extract_with_helper(helper, path, &work, deadline))
.and_then(|wav| audio::decode_file(&wav));
let _ = std::fs::remove_dir_all(&work);
crate::signal::release_temp(&work);
result
}
fn decode_path_with_hint(path: &Path, forced: Option<&str>) -> Result<PcmData, Error> {
match forced {
Some(format) => audio::decode_file_with_format(path, format),
None => audio::decode_file(path),
}
}
fn finish_pcm(
ctx: &Ctx<'_>,
pcm: PcmData,
file: String,
source: &'static str,
knobs: &ResolvedKnobs<'_>,
started: Instant,
) -> Result<TranscriptionResult, Error> {
let (language, language_source) = (knobs.language, knobs.language_source);
let (entry, model_path, device) = (knobs.entry, knobs.model_path, knobs.device);
let (beam, vad, deadline) = (knobs.beam, knobs.vad, knobs.deadline);
if pcm.duration_seconds() > knobs.max_duration {
return Err(Error::DurationCap);
}
if let Some(d) = deadline {
if Instant::now() > d {
return Err(Error::Timeout);
}
}
let samples = audio::to_16k_mono(&pcm)?;
gpu::ensure_process_memory(knobs.max_memory)?;
let chunks = audio::vad_chunks(&samples, vad, &knobs.vad_settings);
let second_buffer: u64 = if chunks.is_empty() {
samples.len() as u64 * 4
} else {
chunks
.iter()
.map(|(s, e)| (e.min(&samples.len()).saturating_sub(*s)) as u64 * 4)
.sum()
};
gpu::ensure_headroom(second_buffer)?;
let (used, vad_chunks): (Cow<'_, [f32]>, usize) = if chunks.is_empty() {
(Cow::Borrowed(samples.as_slice()), 0usize)
} else {
let mut joined = Vec::with_capacity(second_buffer as usize / 4);
for (s, e) in &chunks {
let piece = &samples[*s..(*e).min(samples.len())];
let start = joined.len();
joined.extend_from_slice(piece);
crate::audio::ramp_edges(&mut joined[start..]);
}
(Cow::Owned(joined), chunks.len())
};
let out = crate::engine::transcribe(&crate::engine::TranscribeRequest {
model_path,
samples: &used,
language,
beam,
device,
deadline,
})?;
gpu::ensure_process_memory(knobs.max_memory)?;
let filtered = audio::filter_hallucinations(&out.text, knobs.hallucination);
let hallucinations_removed = filtered.removed;
let cleaned = audio::collapse_consecutive_repeats(&filtered.text);
let language_source = if out.language_detected {
"detection"
} else {
language_source
};
Ok(TranscriptionResult {
schema_version: SCHEMA_VERSION,
correlation_id: ctx.correlation_id.to_string(),
target_resolved: file.clone(),
target_source: source.to_string(),
file,
language: out.language,
language_source: language_source.to_string(),
model: entry.name.clone(),
device,
duration_seconds: pcm.duration_seconds(),
text: cleaned,
segments: if knobs.timestamps {
Some(
out.segments
.into_iter()
.map(|s| Segment {
start: audio::source_time(&chunks, samples.len(), s.start),
end: audio::source_time(&chunks, samples.len(), s.end),
text: s.text,
})
.collect(),
)
} else {
None
},
vad_chunks,
hallucinations_removed,
processing_time_ms: started.elapsed().as_millis(),
cold_load: out.cold_load,
})
}
const STDIN_CHUNK: usize = 64 * 1024;
fn read_stdin(no_input: bool, max_duration: f64, forced: Option<&str>) -> Result<Vec<u8>, Error> {
if no_input {
return Err(Error::NoInput);
}
if std::io::stdin().is_terminal() {
return Err(Error::NoInput);
}
let mut buf = Vec::new();
let mut stdin = std::io::stdin().lock();
let mut chunk = [0u8; STDIN_CHUNK];
let mut duration_checked = false;
let read = loop {
if crate::gpu::memory_cap_exceeded() {
return Err(Error::MemoryCap);
}
if !duration_checked && buf.len() >= audio::probe_prefix() {
duration_checked = true;
if let Some(seconds) = audio::probe_duration_bytes(&buf, forced) {
if seconds > max_duration {
return Err(Error::DurationCap);
}
}
}
match std::io::Read::read(&mut stdin, &mut chunk) {
Ok(0) => break Ok(()),
Ok(n) => buf.extend_from_slice(&chunk[..n]),
Err(e) => break Err(e),
}
};
if let Some(err) = crate::signal::shutdown_error() {
return Err(err);
}
read?;
if buf.is_empty() {
return Err(Error::NoInput);
}
Ok(buf)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn invocation_conditions_are_fatal() {
for err in [
Error::Timeout,
Error::Interrupted,
Error::Terminated,
Error::BrokenPipe,
] {
assert!(is_invocation_fatal(&err), "{err} must fail the invocation");
}
}
#[test]
fn per_target_faults_are_not_fatal() {
for err in [
Error::InputNotFound { path: "x".into() },
Error::UnsupportedFormat {
format: "xyz".into(),
},
Error::AudioDecode(anyhow::anyhow!("bad")),
Error::HelperMissing,
] {
assert!(!is_invocation_fatal(&err), "{err} must stay per-target");
}
}
#[test]
fn fatal_clone_preserves_the_exit_code() {
for err in [
Error::Timeout,
Error::Interrupted,
Error::Terminated,
Error::BrokenPipe,
] {
assert_eq!(clone_fatal(&err).exit_code(), err.exit_code());
}
}
#[test]
fn helper_retry_needs_a_configured_helper() {
assert!(!helper_retry_allowed("", true), "no helper means no retry");
assert!(
!helper_retry_allowed(" ", true),
"blank helper means no retry"
);
assert!(
!helper_retry_allowed("/usr/bin/ffmpeg", false),
"opt-in required"
);
assert!(helper_retry_allowed("/usr/bin/ffmpeg", true));
}
#[test]
fn only_a_decode_fault_reaches_the_helper() {
assert!(Error::AudioDecode(anyhow::anyhow!("bad frame")).is_decode_fault());
assert!(Error::UnsupportedFormat {
format: "opus".into()
}
.is_decode_fault());
for err in [
Error::MemoryCap,
Error::DurationCap,
Error::Timeout,
Error::Interrupted,
Error::Terminated,
Error::BrokenPipe,
] {
assert!(
!err.is_decode_fault(),
"{err} is a verdict on the run, not on the container"
);
}
}
}
#[cfg(test)]
mod batch_tests {
use super::*;
#[test]
fn abandoning_a_batch_still_accounts_for_every_target() {
let total = 5usize;
let done = 2usize;
let mut out: Vec<Result<(), Error>> = (0..done).map(|_| Ok(())).collect();
for _ in 0..(total - out.len()) {
out.push(Err(clone_fatal(&Error::Timeout)));
}
assert_eq!(out.len(), total, "every target must be accounted for");
let ok = out.iter().filter(|r| r.is_ok()).count();
let failed = out.iter().filter(|r| r.is_err()).count();
assert_eq!(ok + failed, total, "ok+failed must equal total");
assert_eq!(ok, done);
}
#[test]
fn unclassified_shutdown_still_yields_a_fatal_error() {
let err = crate::signal::shutdown_error().unwrap_or(Error::Interrupted);
assert!(is_invocation_fatal(&err));
assert!(matches!(err.exit_code(), 130 | 143,));
}
}