ttml_processor 0.4.0

A Rust library for parsing and generating TTML lyrics files, specifically designed for Apple Music and AMLL formats.
Documentation

TTML Processor

A high-performance Rust library for parsing and generating TTML files, specifically tailored for the Apple Music and AMLL formats.

A Note on Specialization

This library is not a general-purpose TTML subtitle parser. It is specifically designed to handle the unique conventions, metadata structures, and extensions (e.g., itunes:* attributes, <iTunesMetadata>) found in TTML files used by Apple Music. Attempting to use it on generic TTML subtitle files may result in errors or incomplete data.

Usage

Add ttml_processor to your Cargo.toml:

[dependencies]
ttml_processor = "0.4.0" # Replace with the latest version

Parsing Example

use ttml_processor::parse_ttml;

fn main() {
    let ttml_content = r#"
    <tt xmlns="http://www.w3.org/ns/ttml" xmlns:itunes="http://music.apple.com/lyric-ttml-internal" itunes:timing="word">
      <body>
        <div>
          <p begin="5.000" end="10.000">
            <span begin="5.100" end="5.500">Hello </span>
            <span begin="5.600" end="6.000">world</span>
          </p>
        </div>
      </body>
    </tt>
    "#;

    let parsed_data = parse_ttml(ttml_content).expect("Failed to parse TTML");

    assert_eq!(parsed_data.lines.len(), 1);
    let first_line = &parsed_data.lines[0];
    assert_eq!(first_line.start_time, 5000);

    let syllables = &first_line
        .words
        .as_ref()
        .expect("Should have syllables in first line");
    assert_eq!(syllables.len(), 2);
    assert_eq!(syllables[0].text, "Hello");
    assert_eq!(syllables[0].start_time, 5100);
    assert_eq!(syllables[0].ends_with_space, Some(true));

    println!("Successfully parsed TTML: {parsed_data:?}");
}

Generation Example

use ttml_processor::{
    GeneratorConfig,
    generate_ttml,
    model::{
        LyricLine,
        Syllable,
        TTMLMetadata,
        TTMLResult,
    },
};

fn main() {
    let mut line = LyricLine {
        start_time: 5000,
        end_time: 10000,
        ..Default::default()
    };
    line.push_word(Syllable {
        text: "Hello".into(),
        start_time: 5100,
        end_time: 5500,
        ends_with_space: Some(true),
        ..Default::default()
    });
    line.push_word(Syllable {
        text: "world".into(),
        start_time: 5600,
        end_time: 6000,
        ..Default::default()
    });
    line.rebuild_text();

    let result = TTMLResult {
        metadata: TTMLMetadata {
            timing_mode: Some("word".into()),
            language: Some("en".into()),
            ..Default::default()
        },
        lines: vec![line],
    };

    let config = GeneratorConfig {
        use_apple_format_rules: false,
        format: true,
        line_timing: false,
    };

    let ttml_string = generate_ttml(&result, &config).expect("Failed to generate TTML");
    println!("{ttml_string}");
}

Generator Options

GeneratorConfig controls the shape of the generated TTML:

  • use_apple_format_rules — write per-line translations/transliterations into <head> and follow Apple Music's background-vocal conventions. When false, per-line translations/transliterations are emitted as inline x-translation / x-roman spans instead. Word-by-word translations/transliterations always go into <head>.
  • format — pretty-print the XML instead of emitting it as a single line.
  • line_timing — generate line-by-line lyrics: itunes:timing="Line", plain text inside each <p> with no per-syllable <span>, word-by-word translations/transliterations flattened to line text (their placement still follows use_apple_format_rules), and background vocals omitted.

[!NOTE] line_timing is the only way to produce line-by-line TTML. Setting the timing_mode metadata to "Line" merely writes that value into the itunes:timing attribute, the per-syllable <span>s are still emitted. Callers usually decide whether to enable line_timing either by checking that every main lyric line has at most one syllable, or — when the input comes from a trustworthy source — by reading the parsed TTMLMetadata.timing_mode or another high-confidence timing-mode signal.

License

This project is licensed under the MIT License. See the LICENSE file for details.