use serde::{Deserialize, Serialize};
use crate::align::ALIGNMENT_TOLERANCE_MS;
use crate::words::TimedWord;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Profile {
Standard,
Vertical,
Compact,
}
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct CaptionConfig {
pub max_chars_per_line: usize,
pub max_lines: usize,
pub max_chars_per_second: f64,
pub min_cue_ms: u64,
pub max_cue_ms: u64,
pub max_gap_ms: u64,
}
impl CaptionConfig {
pub fn for_profile(profile: Profile) -> Self {
match profile {
Profile::Standard => Self {
max_chars_per_line: 42,
max_lines: 2,
max_chars_per_second: 21.0,
min_cue_ms: 600,
max_cue_ms: 7000,
max_gap_ms: 700,
},
Profile::Vertical => Self {
max_chars_per_line: 20,
max_lines: 2,
max_chars_per_second: 18.0,
min_cue_ms: 600,
max_cue_ms: 4500,
max_gap_ms: 700,
},
Profile::Compact => Self {
max_chars_per_line: 24,
max_lines: 2,
max_chars_per_second: 18.0,
min_cue_ms: 600,
max_cue_ms: 4500,
max_gap_ms: 700,
},
}
}
}
impl Default for CaptionConfig {
fn default() -> Self {
Self::for_profile(Profile::Standard)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Cue {
pub start_ms: u64,
pub end_ms: u64,
pub lines: Vec<String>,
pub first_word: usize,
pub last_word: usize,
}
impl Cue {
pub fn text(&self) -> String {
self.lines.join("\n")
}
}
fn sentence_end(t: &str) -> bool {
t.ends_with(['.', '?', '!', '\u{2026}'])
}
fn clause_end(t: &str) -> bool {
t.ends_with([',', ';', ':', '\u{2014}', '\u{2013}'])
}
pub fn normalize_words(words: &[TimedWord]) -> Vec<TimedWord> {
let mut out: Vec<TimedWord> = Vec::with_capacity(words.len());
for w in words {
let text = w.text.split_whitespace().collect::<Vec<_>>().join(" ");
if text.is_empty() || w.end_ms <= w.start_ms {
continue;
}
if let Some(prev) = out.last_mut() {
if prev.end_ms > w.start_ms {
prev.end_ms = w.start_ms;
if prev.end_ms <= prev.start_ms {
out.pop();
}
}
}
out.push(TimedWord::new(text, w.start_ms, w.end_ms));
}
out
}
fn chars(s: &str) -> usize {
s.chars().count()
}
fn greedy_wrap(words: &[&str], max: usize) -> Vec<Vec<usize>> {
let mut lines: Vec<Vec<usize>> = Vec::new();
let mut cur: Vec<usize> = Vec::new();
let mut len = 0usize;
for (i, w) in words.iter().enumerate() {
let wl = chars(w);
if cur.is_empty() {
cur.push(i);
len = wl;
} else if len + 1 + wl <= max {
cur.push(i);
len += 1 + wl;
} else {
lines.push(std::mem::take(&mut cur));
cur.push(i);
len = wl;
}
}
if !cur.is_empty() {
lines.push(cur);
}
lines
}
fn line_count(group: &[TimedWord], max: usize) -> usize {
let w: Vec<&str> = group.iter().map(|w| w.text.as_str()).collect();
greedy_wrap(&w, max).len()
}
fn text_chars(group: &[TimedWord]) -> usize {
group
.iter()
.map(|w| chars(&w.text) + 1)
.sum::<usize>()
.saturating_sub(1)
}
fn span(group: &[TimedWord]) -> u64 {
match (group.first(), group.last()) {
(Some(first), Some(last)) => last.end_ms.saturating_sub(first.start_ms),
_ => 0,
}
}
fn needs_split(group: &[TimedWord], cfg: &CaptionConfig) -> bool {
if group.len() <= 1 {
return false;
}
let dur = span(group);
if dur > cfg.max_cue_ms {
return true;
}
if line_count(group, cfg.max_chars_per_line) > cfg.max_lines {
return true;
}
let shown = dur.max(cfg.min_cue_ms) as f64 / 1000.0;
text_chars(group) as f64 > cfg.max_chars_per_second * shown
}
fn split_index(group: &[TimedWord]) -> usize {
let total = text_chars(group) as i64;
let mut best: Option<(i64, i64, usize)> = None; let mut run = 0i64;
for (i, w) in group.iter().enumerate().take(group.len() - 1) {
run += chars(&w.text) as i64 + 1;
let dist = (run - total / 2).abs();
let balanced = run * 4 >= total && (total - run) * 4 >= total;
let rank = if balanced && sentence_end(&w.text) {
0
} else if balanced && clause_end(&w.text) {
1
} else {
2
};
if best.is_none_or(|(r, d, _)| (rank, dist) < (r, d)) {
best = Some((rank, dist, i + 1));
}
}
best.map(|b| b.2).unwrap_or(1).clamp(1, group.len() - 1)
}
fn split_rec(group: Vec<TimedWord>, cfg: &CaptionConfig, out: &mut Vec<Vec<TimedWord>>) {
if group.is_empty() {
return;
}
if !needs_split(&group, cfg) {
out.push(group);
return;
}
let at = split_index(&group);
let mut left = group;
let right = left.split_off(at);
split_rec(left, cfg, out);
split_rec(right, cfg, out);
}
fn phrase_groups(words: &[TimedWord], cfg: &CaptionConfig) -> Vec<Vec<TimedWord>> {
let mut groups: Vec<Vec<TimedWord>> = Vec::new();
for w in words {
let new = match groups.last().and_then(|g| g.last()) {
None => true,
Some(last) => w.start_ms - last.end_ms > cfg.max_gap_ms || sentence_end(&last.text),
};
if new {
groups.push(vec![w.clone()]);
} else {
groups.last_mut().unwrap().push(w.clone());
}
}
groups
}
fn merge_short(groups: Vec<Vec<TimedWord>>, cfg: &CaptionConfig) -> Vec<Vec<TimedWord>> {
let mut out: Vec<Vec<TimedWord>> = Vec::new();
let mut iter = groups.into_iter().peekable();
while let Some(mut cur) = iter.next() {
while span(&cur) < cfg.min_cue_ms {
let Some(next) = iter.peek() else { break };
let gap = next[0].start_ms - cur.last().unwrap().end_ms;
if gap > cfg.max_gap_ms || sentence_end(&cur.last().unwrap().text) {
break;
}
let mut joined = cur.clone();
joined.extend(next.iter().cloned());
if needs_split(&joined, cfg) {
break;
}
cur = joined;
iter.next();
}
if span(&cur) < cfg.min_cue_ms {
if let Some(prev) = out.last_mut() {
let gap = cur[0].start_ms - prev.last().unwrap().end_ms;
if gap <= cfg.max_gap_ms && !sentence_end(&prev.last().unwrap().text) {
let mut joined = prev.clone();
joined.extend(cur.iter().cloned());
if !needs_split(&joined, cfg) {
*prev = joined;
continue;
}
}
}
}
out.push(cur);
}
out
}
fn break_lines(group: &[TimedWord], cfg: &CaptionConfig) -> Vec<String> {
let w: Vec<&str> = group.iter().map(|w| w.text.as_str()).collect();
let greedy = greedy_wrap(&w, cfg.max_chars_per_line);
let join = |r: &[usize]| r.iter().map(|&i| w[i]).collect::<Vec<_>>().join(" ");
if greedy.len() != 2 || cfg.max_lines < 2 {
return greedy.iter().map(|l| join(l)).collect();
}
let all: Vec<usize> = (0..w.len()).collect();
let total: usize = all.iter().map(|&i| chars(w[i]) + 1).sum::<usize>() - 1;
let mut best: Option<((u8, usize), usize)> = None;
for k in 1..w.len() {
let l = join(&all[..k]);
let r = join(&all[k..]);
if chars(&l) > cfg.max_chars_per_line || chars(&r) > cfg.max_chars_per_line {
continue;
}
let diff = chars(&l).abs_diff(chars(&r));
let short = chars(&l).min(chars(&r));
let punct = (sentence_end(w[k - 1]) || clause_end(w[k - 1])) && short * 4 >= total;
let key = (u8::from(!punct), diff);
if best.is_none_or(|(b, _)| key < b) {
best = Some((key, k));
}
}
match best {
Some((_, k)) => vec![join(&all[..k]), join(&all[k..])],
None => greedy.iter().map(|l| join(l)).collect(),
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct GroupRules {
pub max_words: usize,
pub max_span_ms: u64,
pub max_gap_ms: u64,
pub sentence_min_words: usize,
pub min_cue_ms: u64,
}
impl Default for GroupRules {
fn default() -> Self {
Self {
max_words: 12,
max_span_ms: 7_000,
max_gap_ms: 1_000,
sentence_min_words: 3,
min_cue_ms: 80,
}
}
}
fn single_line_cue(
text: &str,
start_ms: u64,
end_ms: u64,
first: usize,
last: usize,
min_cue_ms: u64,
) -> Cue {
Cue {
start_ms,
end_ms: end_ms.max(start_ms + min_cue_ms),
lines: vec![text.trim().to_string()],
first_word: first,
last_word: last,
}
}
pub fn group_words(words: &[TimedWord], rules: &GroupRules) -> Vec<Cue> {
struct Open {
text: String,
start: u64,
end: u64,
first: usize,
last: usize,
count: usize,
}
let close =
|o: &Open| single_line_cue(&o.text, o.start, o.end, o.first, o.last, rules.min_cue_ms);
let open = |i: usize, w: &TimedWord| Open {
text: w.text.clone(),
start: w.start_ms,
end: w.end_ms,
first: i,
last: i,
count: 1,
};
let mut cues = Vec::new();
let mut current: Option<Open> = None;
for (i, word) in words.iter().enumerate() {
match current.as_mut() {
Some(c) => {
let gap_over = word.start_ms > c.end && word.start_ms - c.end > rules.max_gap_ms;
let span = c.end.saturating_sub(c.start);
if gap_over || c.count >= rules.max_words || span >= rules.max_span_ms {
cues.push(close(c));
current = Some(open(i, word));
} else {
c.text.push(' ');
c.text.push_str(&word.text);
c.end = word.end_ms;
c.last = i;
c.count += 1;
}
}
None => current = Some(open(i, word)),
}
if current.as_ref().is_some_and(|c| {
c.text.ends_with(['.', '?', '!']) && c.count >= rules.sentence_min_words
}) {
cues.push(close(¤t.take().expect("cue present")));
}
}
if let Some(c) = current {
cues.push(close(&c));
}
cues
}
pub fn cues_from_spans(spans: &[TimedWord], min_cue_ms: u64) -> Vec<Cue> {
spans
.iter()
.enumerate()
.map(|(i, s)| single_line_cue(&s.text, s.start_ms, s.end_ms, i, i, min_cue_ms))
.collect()
}
pub fn build_cues(words: &[TimedWord], cfg: &CaptionConfig) -> Vec<Cue> {
let words = normalize_words(words);
let mut groups = Vec::new();
for phrase in phrase_groups(&words, cfg) {
split_rec(phrase, cfg, &mut groups);
}
let groups = merge_short(groups, cfg);
let mut cues: Vec<Cue> = Vec::with_capacity(groups.len());
let mut idx = 0usize;
for g in &groups {
let first = idx;
idx += g.len();
cues.push(Cue {
start_ms: g[0].start_ms,
end_ms: g.last().unwrap().end_ms,
lines: break_lines(g, cfg),
first_word: first,
last_word: idx - 1,
});
}
for i in 0..cues.len() {
let next_start = cues.get(i + 1).map(|c| c.start_ms);
let c = &mut cues[i];
if c.end_ms - c.start_ms < cfg.min_cue_ms {
let mut end = (c.start_ms + cfg.min_cue_ms).min(c.end_ms + ALIGNMENT_TOLERANCE_MS);
if let Some(n) = next_start {
end = end.min(n);
}
c.end_ms = end.max(c.end_ms);
}
}
cues
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn group_words_treats_an_inverted_word_as_zero_length() {
let words = [TimedWord::new("a", 500, 100), TimedWord::new("b", 600, 700)];
let cues = group_words(&words, &GroupRules::default());
assert_eq!(cues.len(), 1, "inverted span must not force a split");
assert_eq!(cues[0].start_ms, 500);
assert!(cues[0].end_ms >= cues[0].start_ms);
assert_eq!(cues[0].lines, vec!["a b".to_string()]);
let lone = group_words(&[TimedWord::new("x", 900, 10)], &GroupRules::default());
assert_eq!(lone.len(), 1);
assert_eq!(lone[0].start_ms, 900);
assert_eq!(lone[0].end_ms, 900 + GroupRules::default().min_cue_ms);
}
#[test]
fn span_of_a_reversed_or_empty_group_is_zero_and_never_underflows() {
let reversed = [TimedWord::new("a", 500, 100), TimedWord::new("b", 600, 200)];
assert_eq!(span(&reversed), 0);
let ordered = [TimedWord::new("a", 100, 300), TimedWord::new("b", 320, 900)];
assert_eq!(span(&ordered), 800);
assert_eq!(span(&[]), 0);
}
}