subx_cli/core/formats/
mod.rs

1//! Comprehensive subtitle format handling and conversion system.
2//!
3//! This module provides a unified interface for parsing, converting, and managing
4//! multiple subtitle formats including SRT, ASS/SSA, VTT (WebVTT), and SUB formats.
5//! It handles format detection, parsing, conversion between formats, and preservation
6//! of styling information where supported.
7//!
8//! # Supported Formats
9//!
10//! - **SRT (SubRip)**: The most common subtitle format with simple timing and text
11//! - **ASS/SSA (Advanced SubStation Alpha)**: Advanced format with rich styling support
12//! - **VTT (WebVTT)**: Web-based format with positioning and styling capabilities
13//! - **SUB (MicroDVD)**: Frame-based timing format
14//!
15//! # Architecture
16//!
17//! The format system is built around several key components:
18//!
19//! - **Format Detection**: Automatic detection based on file extension and content analysis
20//! - **Unified Data Model**: Common `Subtitle` and `SubtitleEntry` structures for all formats
21//! - **Format-Specific Parsers**: Dedicated parsing logic for each format
22//! - **Conversion Engine**: Intelligent conversion between formats with feature mapping
23//! - **Styling Preservation**: Maintains formatting information during conversions
24//! - **Encoding Handling**: Automatic encoding detection and conversion
25//!
26//! # Usage Examples
27//!
28//! ## Basic Format Detection and Parsing
29//!
30//! ```rust,ignore
31//! use subx_cli::core::formats::{manager::FormatManager, SubtitleFormatType};
32//! use std::path::Path;
33//!
34//! // Create format manager
35//! let manager = FormatManager::new();
36//!
37//! // Detect format from file
38//! let format = manager.detect_format(Path::new("movie.srt"))?;
39//! println!("Detected format: {}", format);
40//!
41//! // Parse subtitle file
42//! let subtitle = manager.parse_file(Path::new("movie.srt"))?;
43//! println!("Loaded {} entries", subtitle.entries.len());
44//! ```
45//!
46//! ## Format Conversion
47//!
48//! ```rust,ignore
49//! use subx_cli::core::formats::converter::FormatConverter;
50//!
51//! let converter = FormatConverter::new();
52//!
53//! // Convert SRT to ASS format
54//! let ass_content = converter.convert(
55//!     &srt_subtitle,
56//!     SubtitleFormatType::Ass,
57//!     None // Use default conversion options
58//! )?;
59//!
60//! // Save converted content
61//! std::fs::write("movie.ass", ass_content)?;
62//! ```
63//!
64//! ## Working with Styling Information
65//!
66//! ```rust,ignore
67//! use subx_cli::core::formats::{StylingInfo, SubtitleEntry};
68//! use std::time::Duration;
69//!
70//! // Create a styled subtitle entry
71//! let styled_entry = SubtitleEntry {
72//!     index: 1,
73//!     start_time: Duration::from_secs(10),
74//!     end_time: Duration::from_secs(13),
75//!     text: "Styled subtitle text".to_string(),
76//!     styling: Some(StylingInfo {
77//!         font_name: Some("Arial".to_string()),
78//!         font_size: Some(20),
79//!         color: Some("#FFFFFF".to_string()),
80//!         bold: true,
81//!         italic: false,
82//!         underline: false,
83//!     }),
84//! };
85//! ```
86//!
87//! # Format-Specific Features
88//!
89//! ## SRT Format
90//! - Simple timing format (hours:minutes:seconds,milliseconds)
91//! - Basic text formatting with HTML-like tags
92//! - Wide compatibility across media players
93//!
94//! ## ASS/SSA Format
95//! - Advanced styling with fonts, colors, positioning
96//! - Animation and transition effects
97//! - Karaoke timing support
98//! - Multiple style definitions
99//!
100//! ## VTT Format
101//! - Web-optimized format for HTML5 video
102//! - CSS-based styling support
103//! - Positioning and region definitions
104//! - Metadata and chapter support
105//!
106//! ## SUB Format
107//! - Frame-based timing (requires frame rate)
108//! - Simple text format
109//! - Legacy format support
110//!
111//! # Error Handling
112//!
113//! The format system provides comprehensive error handling for:
114//! - Invalid file formats or corrupted content
115//! - Encoding detection and conversion failures
116//! - Timing inconsistencies and overlaps
117//! - Missing or invalid styling information
118//! - File I/O errors during parsing or saving
119//!
120//! # Performance Considerations
121//!
122//! - **Streaming Parsing**: Large files are processed incrementally
123//! - **Memory Efficiency**: Minimal memory footprint for subtitle data
124//! - **Caching**: Format detection results are cached for performance
125//! - **Parallel Processing**: Multiple files can be processed concurrently
126//!
127//! # Thread Safety
128//!
129//! All format operations are thread-safe and can be used in concurrent environments.
130//! The format manager and converters can be safely shared across threads.
131
132#![allow(dead_code)]
133
134pub mod ass;
135pub mod converter;
136pub mod encoding;
137pub(crate) mod line_endings;
138pub mod manager;
139/// SubRip Text (.srt) subtitle format support
140pub mod srt;
141pub mod styling;
142pub mod sub;
143pub mod transformers;
144pub mod vtt;
145
146mod types;
147pub use types::*;
148
149#[cfg(all(test, feature = "slow-tests"))]
150pub(crate) mod tests_support;
subx_cli/core/formats/mod.rs

subx_cli/core/formats/
mod.rs
