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();
}
}
}
let mut word = TimedWord::new(text, w.start_ms, w.end_ms);
word.source_ms = w.source_ms;
out.push(word);
}
out
}
fn chars(s: &str) -> usize {
s.chars().count()
}
#[derive(Clone, Copy)]
pub struct LineMetrics<'a> {
pub measure_width: &'a dyn Fn(&str) -> Result<u64, String>,
pub max_width_px: u64,
pub uppercase: bool,
}
impl std::fmt::Debug for LineMetrics<'_> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("LineMetrics")
.field("max_width_px", &self.max_width_px)
.field("uppercase", &self.uppercase)
.finish_non_exhaustive()
}
}
impl LineMetrics<'_> {
fn width(&self, text: &str) -> Result<u64, String> {
if self.uppercase {
(self.measure_width)(&text.to_uppercase())
} else {
(self.measure_width)(text)
}
}
}
fn fits(text: &str, max: usize, metrics: Option<&LineMetrics<'_>>) -> Result<bool, String> {
let count = if metrics.is_some_and(|m| m.uppercase) {
chars(&text.to_uppercase())
} else {
chars(text)
};
Ok(count <= max
&& match metrics {
Some(m) => m.width(text)? <= m.max_width_px,
None => true,
})
}
pub fn wrap_lines(
text: &str,
max_chars: usize,
metrics: Option<&LineMetrics<'_>>,
) -> Result<Vec<String>, String> {
let mut lines = Vec::new();
let mut cur = String::new();
for word in text.split_whitespace() {
let joined = if cur.is_empty() {
word.to_string()
} else {
format!("{cur} {word}")
};
if fits(&joined, max_chars, metrics)? {
cur = joined;
continue;
}
if !cur.is_empty() {
lines.push(std::mem::take(&mut cur));
}
if metrics.is_none() || fits(word, max_chars, metrics)? {
cur = word.to_string();
continue;
}
for c in word.chars() {
let joined = format!("{cur}{c}");
if !fits(&joined, max_chars, metrics)? {
if cur.is_empty() || !fits(&c.to_string(), max_chars, metrics)? {
return Err(format!("caption glyph {c:?} exceeds the safe line width"));
}
lines.push(std::mem::take(&mut cur));
}
cur.push(c);
}
}
if !cur.is_empty() {
lines.push(cur);
}
Ok(lines)
}
fn line_count(
group: &[TimedWord],
max: usize,
metrics: Option<&LineMetrics<'_>>,
) -> Result<usize, String> {
let text = group
.iter()
.map(|w| w.text.as_str())
.collect::<Vec<_>>()
.join(" ");
Ok(wrap_lines(&text, max, metrics)?.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,
metrics: Option<&LineMetrics<'_>>,
) -> Result<bool, String> {
if group.len() <= 1 {
return Ok(false);
}
let dur = span(group);
if dur > cfg.max_cue_ms {
return Ok(true);
}
if line_count(group, cfg.max_chars_per_line, metrics)? > cfg.max_lines {
return Ok(true);
}
let shown = dur.max(cfg.min_cue_ms) as f64 / 1000.0;
Ok(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,
metrics: Option<&LineMetrics<'_>>,
out: &mut Vec<Vec<TimedWord>>,
) -> Result<(), String> {
if group.is_empty() {
return Ok(());
}
if !needs_split(&group, cfg, metrics)? {
out.push(group);
return Ok(());
}
let at = split_index(&group);
let mut left = group;
let right = left.split_off(at);
split_rec(left, cfg, metrics, out)?;
split_rec(right, cfg, metrics, 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.saturating_sub(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,
metrics: Option<&LineMetrics<'_>>,
) -> Result<Vec<Vec<TimedWord>>, String> {
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.saturating_sub(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, metrics)? {
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.saturating_sub(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, metrics)? {
*prev = joined;
continue;
}
}
}
}
out.push(cur);
}
Ok(out)
}
fn break_lines(
group: &[TimedWord],
cfg: &CaptionConfig,
metrics: Option<&LineMetrics<'_>>,
) -> Result<Vec<String>, String> {
let w: Vec<&str> = group.iter().map(|w| w.text.as_str()).collect();
let greedy = wrap_lines(&w.join(" "), cfg.max_chars_per_line, metrics)?;
let join = |r: &[usize]| r.iter().map(|&i| w[i]).collect::<Vec<_>>().join(" ");
if greedy.len() != 2 || cfg.max_lines < 2 {
return Ok(greedy);
}
let all: Vec<usize> = (0..w.len()).collect();
let mut best: Option<((u8, u64), usize)> = None;
for k in 1..w.len() {
let l = join(&all[..k]);
let r = join(&all[k..]);
if !fits(&l, cfg.max_chars_per_line, metrics)?
|| !fits(&r, cfg.max_chars_per_line, metrics)?
{
continue;
}
let size = |s: &str| match metrics {
Some(m) => m.width(s),
None => Ok(chars(s) as u64),
};
let (left, right) = (size(&l)?, size(&r)?);
let diff = left.abs_diff(right);
let short = left.min(right);
let total = left + right + u64::from(metrics.is_none());
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));
}
}
Ok(match best {
Some((_, k)) => vec![join(&all[..k]), join(&all[k..])],
None => greedy,
})
}
#[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> {
build_cues_with_metrics(words, cfg, None).expect("character-count layout is infallible")
}
pub fn build_cues_with_metrics(
words: &[TimedWord],
cfg: &CaptionConfig,
metrics: Option<&LineMetrics<'_>>,
) -> Result<Vec<Cue>, String> {
let words = normalize_words(words);
let mut groups = Vec::new();
for phrase in phrase_groups(&words, cfg) {
split_rec(phrase, cfg, metrics, &mut groups)?;
}
let groups = merge_short(groups, cfg, metrics)?;
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, metrics)?,
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.saturating_sub(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);
}
}
Ok(cues)
}