ass-core

High-performance ASS (Advanced SubStation Alpha) subtitle format parser and analyzer for Rust.

Features

• Zero-copy parsing: Efficient lifetime-generic AST with minimal allocations
• Full ASS v4+ support: Complete compatibility with libass and Aegisub
• Advanced analysis: Script linting, style resolution, and performance optimization
• SIMD acceleration: Optional SIMD-optimized parsing for maximum performance
• nostd compatible: Works in embedded and WASM environments
• Streaming support: Parse large files incrementally with bounded memory

Performance Targets

• Parse speed: <5ms for typical 1KB scripts
• Memory usage: <1.1x input size via zero-copy design
• Peak memory: <10MB for large subtitle files
• Incremental parsing: <5ms for typical edit operations (infrastructure ready)

Quick Start

Add to your Cargo.toml:

[dependencies]
ass-core = { version = "0.1", features = ["analysis"] }

Basic usage:

use ass_core::parser::Script;

let script_text = r#"
[Script Info]
Title: Example
ScriptType: v4.00+

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:05.00,Default,,0,0,0,,Hello World!
"#;

let script = Script::parse(script_text)?;
println!("Parsed {} sections", script.sections().len());

Advanced Usage

Script Analysis

use ass_core::analysis::ScriptAnalysis;

let analysis = ScriptAnalysis::analyze(&script)?;
println!("Found {} dialogue events", analysis.dialogue_info().len());

Linting

use ass_core::analysis::linting::{lint_script, LintConfig};

let config = LintConfig::default();
let issues = lint_script(&script, &config)?;
for issue in issues {
    println!("{}: {}", issue.severity(), issue.message());
}

Streaming Parser

use ass_core::parser::streaming::StreamingParser;

let mut parser = StreamingParser::new();
for chunk in file_chunks {
    parser.feed_chunk(chunk)?;
}
let result = parser.finalize()?;

Feature Flags

• std (default): Standard library support
• nostd: nostd compatibility
• analysis: Enable script analysis and linting
• plugins: Extension registry support
• simd: SIMD-accelerated parsing
• arena: Arena allocation for improved performance
• stream: Streaming/chunked input support
• serde: Serialization support
• benches: Enable benchmarking infrastructure

Architecture

The crate is organized into several modules:

• parser: Core ASS parsing with zero-copy AST
• analysis: Deep script analysis and optimization detection
• linting: Comprehensive rule-based script validation
• utils: Common utilities and error types

Benchmarking

Performance benchmarks can be run with:

# Run all benchmarks
cargo bench --features=benches

# Run specific benchmarks
cargo bench --features=benches parser_benchmarks
cargo bench --features=benches incremental_benchmarks

The benchmarking suite includes:

• Parser benchmarks: Full parsing performance across complexity levels
• Incremental benchmarks: Infrastructure for validating incremental parsing
• Real-world scenarios: Testing against realistic subtitle patterns (anime, movies, karaoke, signs, educational content)
• Large-scale anime: Benchmarks for 30-50MB+ files with 10k-100k events (BD releases, complex OVAs)
• Editor simulation: Realistic editing patterns (typing, backspace, copy-paste)
• Memory benchmarks: Zero-copy efficiency and memory ratio validation
• Memory profiling: Simple tool to measure actual memory usage

Memory Profiling

To analyze memory usage without external tools:

# Run memory benchmarks
cargo bench --features=benches memory_benchmarks

# Run simple memory profiler
cargo run --features=benches --bin memory-profile

The memory profiler shows:

• Input size vs actual memory usage
• Memory ratio (target: <1.1x)
• Parse time and section counts
• Pass/fail status for memory targets

Benchmark Configuration

For faster benchmark runs (e.g., in CI):

# Quick mode - fewer samples, shorter measurement time
QUICK_BENCH=1 cargo bench --features=benches

# Run specific benchmark group
cargo bench --features=benches incremental_parsing

# Increase time limit for complex benchmarks
cargo bench --features=benches -- --measurement-time 15

If you see warnings about unable to complete samples:

• This is normal for complex benchmarks
• The results are still valid
• Use QUICK_BENCH=1 for faster iteration
• Or increase measurement time as suggested

Compatibility

• ASS v4.00+: Full support including advanced features
• SSA v4: Legacy compatibility mode
• libass extensions: Support for renderer-specific features
• Aegisub compatibility: Full support for Aegisub-specific features

License

Licensed under the MIT license.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.