Crate ass_editor

Expand description

High-performance, ergonomic editor layer for ASS subtitles

ass-editor provides an interactive editing interface built on top of ass-core, featuring zero-copy efficiency, incremental updates, and multi-document support. Designed for building subtitle editors, conversion tools, and automation scripts.

§Key Features

§📝 Interactive Editing

Undo/redo: Full history management with configurable depth
Multi-document sessions: Manage multiple files with shared resources
Incremental parsing: <1ms edits, <5ms re-parses via ass-core’s streaming parser
Fluent APIs: Ergonomic builders and method chaining for all operations

§⚡ High Performance

Zero-copy editing: Direct manipulation of ass-core’s zero-copy spans
Memory efficient: ~1.2x input size including undo history with arena pooling
SIMD acceleration: Optional SIMD features for parsing performance
Thread-safe: Optional multi-threading support with Arc/Mutex

§🔍 Advanced Features

Search indexing: FST-based trie indexing for fast regex queries across large scripts
Plugin system: Extensible architecture with syntax highlighting and auto-completion
Format support: Import/export SRT, WebVTT with configurable conversion options
Karaoke support: Generate, split, adjust, and apply karaoke timing with syllable detection

§Quick Start

use ass_editor::{EditorDocument, Position, Range};

// Create a new document with ASS content
let mut doc = EditorDocument::from_content(r#"
[Script Info]
Title: My Subtitle

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,0,2,10,10,10,1

[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
"#).unwrap();

// Basic text editing with position-based operations
let pos = Position::new(doc.text().len() - 11); // Before "Hello World"
doc.insert(pos, "Welcome! ").unwrap();

// Range-based operations
let range = Range::new(Position::new(pos.offset), Position::new(pos.offset + 8));
doc.replace(range, "Hi").unwrap();

// Undo/redo support
assert!(doc.can_undo());
doc.undo().unwrap();
assert!(doc.can_redo());
doc.redo().unwrap();

println!("Final text contains: {}", doc.text().contains("Hi World"));

§Advanced Usage Examples

§Style Management

let mut doc = EditorDocument::new();

// Create styles with builder pattern
let style = StyleBuilder::new()
    .font("Arial")
    .size(24)
    .color("&H00FFFFFF")
    .bold(true);

// Apply styles to document
doc.styles().create("Title", style).unwrap();

§Karaoke Timing

let mut doc = EditorDocument::from_content("Karaoke text here").unwrap();
let range = Range::new(Position::new(0), Position::new(17));

// Generate karaoke with automatic syllable detection
doc.karaoke()
    .in_range(range)
    .generate(50) // 50 centiseconds per syllable
    .karaoke_type(KaraokeType::Fill)
    .execute()
    .unwrap();

// Adjust timing
doc.karaoke()
    .in_range(range)
    .adjust()
    .scale(1.5) // Make 50% longer
    .unwrap();

§Multi-Document Sessions

let mut manager = EditorSessionManager::new();

manager.create_session("subtitle1.ass".to_string()).unwrap();
manager.create_session("subtitle2.ass".to_string()).unwrap();

// Switch between sessions with <100µs overhead
manager.switch_session("subtitle1.ass").unwrap();
// Edit session1...

manager.switch_session("subtitle2.ass").unwrap();
// Edit session2 with shared plugins and memory pools...

§Feature Flags

ass-editor uses a two-tier feature system for maximum flexibility:

§Main Flavors

default: Enables full for complete desktop functionality
minimal: Core editing features - no_std compatible with alloc
full: All features including std, analysis, plugins, formats, search, concurrency

§Optional Features

simd: SIMD acceleration for parsing performance
nostd: No-standard library support for embedded/WASM
dev-benches: Development benchmarking

§Usage Examples

# Full-featured desktop editor (default)
ass-editor = "0.1"

# Minimal editor for lightweight integrations
ass-editor = { version = "0.1", default-features = false, features = ["minimal"] }

# Maximum performance with SIMD
ass-editor = { version = "0.1", features = ["full", "simd"] }

# WASM/embedded build
ass-editor = { version = "0.1", default-features = false, features = ["minimal", "nostd"] }

Re-exports§

pub use commands::BatchCommand;
pub use commands::CommandResult;
pub use commands::DeleteTextCommand;
pub use commands::DocumentCommandExt;
pub use commands::EditorCommand;
pub use commands::InsertTextCommand;
pub use commands::ReplaceTextCommand;
pub use commands::TextCommand;
pub use core::DocumentPosition;
pub use core::EditorDocument;
pub use core::EditorError;
pub use core::EventAccessor;
pub use core::EventBuilder;
pub use core::EventInfo;
pub use core::EventQuery;
pub use core::EventSortCriteria;
pub use core::EventSortOptions;
pub use core::HistoryEntry;
pub use core::HistoryStats;
pub use core::OwnedEvent;
pub use core::Position;
pub use core::PositionBuilder;
pub use core::Range;
pub use core::Result;
pub use core::Selection;
pub use core::StyleBuilder;
pub use core::UndoManager;
pub use core::UndoStack;
pub use core::UndoStackConfig;
pub use core::fluent::EventFilter;
pub use events::DocumentEvent;
pub use events::EventChannel;
pub use events::EventChannelConfig;
pub use events::EventFilter as DocumentEventFilter;
pub use events::EventHandler;
pub use events::EventStats;
pub use extensions::EditorContext;
pub use extensions::EditorExtension;
pub use extensions::ExtensionCapability;
pub use extensions::ExtensionCommand;
pub use extensions::ExtensionContext;
pub use extensions::ExtensionInfo;
pub use extensions::ExtensionManager;
pub use extensions::ExtensionResult;
pub use extensions::ExtensionState;
pub use extensions::MessageLevel;
pub use utils::LazyValidator;
pub use utils::ValidationIssue;
pub use utils::ValidationResult;
pub use utils::ValidationSeverity;
pub use utils::ValidatorConfig;
pub use sessions::EditorSession;
pub use sessions::EditorSessionManager;
pub use sessions::SessionConfig;
pub use sessions::SessionStats;
pub use formats::Format;
pub use formats::FormatExporter;
pub use formats::FormatImporter;
pub use formats::FormatInfo;
pub use formats::FormatOptions;
pub use formats::FormatRegistry;
pub use formats::FormatResult;

Modules§

commands: Command system for editor operations
core: Core types and structures for the ass-editor
events: Event system for document changes and editor notifications
extensions: Extension system for editor functionality
formats: Format import/export functionality for subtitle files.
sessions: Session management for multi-document editing
utils: Utility modules for the ass-editor

Macros§

add_event: Macro for quickly adding events
at_pos: Fluent API macro for position operations
edit_event: Macro for editing events with multiple field updates
edit_style: Macro for editing styles
script_info: Macro for script info field updates

Structs§

Event: Event from [Events\] section (dialogue, comments, etc.)
Script: Main ASS script container with zero-copy lifetime-generic design
ScriptInfo: Script Info section containing metadata and headers
Span: Represents a span in the source text with position information
Style: Style definition from [V4+ Styles] section

Enums§

EventType: Event type discriminant for different kinds of timeline events
Section: Top-level section in an ASS script
SectionType: Section type discriminant for efficient lookup and filtering

Crate ass_editorCopy item path