From 6d730fa69bff62da5769041139932c45a592d252 Mon Sep 17 00:00:00 2001 From: cdn0x12 Date: Wed, 23 Apr 2025 19:33:02 +0800 Subject: [PATCH] docs: add ass docs --- docs/commands.md | 67 ++++++++++++++++++++++++++------- docs/getting-started.md | 7 +++- docs/zh-Hans/commands.md | 50 +++++++++++++++++++++--- docs/zh-Hans/getting-started.md | 7 +++- 4 files changed, 109 insertions(+), 22 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index eb2d747..02f94a1 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -36,9 +36,10 @@ sub-cli convert | Source Format | Target Format | Notes | |---------------|---------------|-------| -| SRT (.srt) | SRT, VTT, LRC, TXT | - | -| VTT (.vtt) | SRT, VTT, LRC, TXT | - | -| LRC (.lrc) | SRT, VTT, LRC, TXT | - | +| SRT (.srt) | SRT, VTT, LRC, TXT, ASS | - | +| VTT (.vtt) | SRT, VTT, LRC, TXT, ASS | - | +| LRC (.lrc) | SRT, VTT, LRC, TXT, ASS | - | +| ASS (.ass) | SRT, VTT, LRC, TXT, ASS | - | | TXT (.txt) | — | TXT can only be a target format, not a source format | ### Feature Preservation @@ -61,6 +62,18 @@ The conversion process aims to preserve as many features as possible, but some f - For the last entry, a default duration (typically 3-5 seconds) is added to create an end time - **Lost when converting to LRC**: When other formats are converted to LRC, any end timestamp information is discarded +#### ASS Features +- **Preserved**: Text content, timeline (start and end times), basic styling information +- **Minimalist approach**: Conversion creates a "minimal" ASS file with essential structure +- **When converting to ASS**: + - Basic styles (bold, italic, underline) are converted to ASS styles with default settings + - Default font is Arial, size 20pt with standard colors and margins + - Only "Dialogue" events are created (not "Comment" or other event types) +- **When converting from ASS**: + - Only "Dialogue" events are converted, "Comment" events are ignored + - Style information is preserved where the target format supports it + - ASS-specific attributes (Layer, MarginL/R/V, etc.) are stored as metadata when possible + #### TXT Features - **Output only**: Plain text format contains only the text content without any timing or styling @@ -83,6 +96,12 @@ sub-cli convert lyrics.lrc transcript.txt # Convert from WebVTT to SRT sub-cli convert subtitles.vtt subtitles.srt + +# Convert from SRT to ASS +sub-cli convert subtitles.srt subtitles.ass + +# Convert from ASS to SRT +sub-cli convert subtitles.ass subtitles.srt ``` ## sync @@ -108,6 +127,7 @@ Currently, synchronization only works between files of the same format: - SRT to SRT - LRC to LRC - VTT to VTT +- ASS to ASS ### Behavior Details @@ -117,7 +137,7 @@ Currently, synchronization only works between files of the same format: - **When entry counts differ**: The source timeline is scaled to match the target content using linear interpolation: - For each target entry position, a corresponding position in the source timeline is calculated - Times are linearly interpolated between the nearest source entries - - This ensures smooth and proportional timing across entries of different counts + - This ensures smooth and proportional timing distribution across varying entry counts - **Preserved from target**: All content text and metadata (artist, title, etc.). - **Modified in target**: Only timestamps are updated. @@ -125,21 +145,31 @@ Currently, synchronization only works between files of the same format: - **When entry counts match**: Both start and end times from the source are directly applied to the target entries. - **When entry counts differ**: A scaled approach using linear interpolation is used: - - Start times are calculated using linear interpolation between the nearest source entries + - Start times are calculated using linear interpolation between source entries - End times are calculated based on source entry durations - - The timing relationship between entries is preserved -- **Preserved from target**: All subtitle text content. -- **Modified in target**: Timestamps are updated and entry numbers are standardized (sequential from 1). + - The time relationships between entries are preserved +- **Preserved from target**: All content text. +- **Modified in target**: Timestamps are updated and cue identifiers are standardized (sequential from 1). #### For VTT Files: - **When entry counts match**: Both start and end times from the source are directly applied to the target entries. -- **When entry counts differ**: A scaled approach using linear interpolation is used, similar to SRT synchronization: - - Start times are calculated using linear interpolation between the nearest source entries +- **When entry counts differ**: A scaled approach using linear interpolation is used: + - Start times are calculated using linear interpolation between source entries - End times are calculated based on source entry durations - - The timing relationship between entries is preserved -- **Preserved from target**: All subtitle text content, formatting, cue settings, and styling. -- **Modified in target**: Timestamps are updated and cue identifiers are standardized (sequential from 1). + - The time relationships between entries are preserved +- **Preserved from target**: All subtitle text content and styling information. +- **Modified in target**: Timestamps are updated and cue identifiers are standardized. + +#### For ASS Files: + +- **When entry counts match**: The source timeline (start and end times) is directly applied to the target events. +- **When entry counts differ**: A scaled approach using linear interpolation is used: + - Start times are calculated using linear interpolation between source events + - End times are calculated based on source event durations + - The time relationships between events are preserved +- **Preserved from target**: All event text content, style references, and other attributes like Layer, MarginL/R/V. +- **Modified in target**: Only the timestamps (Start and End) are updated. ### Timeline Interpolation Details @@ -177,6 +207,9 @@ sub-cli sync reference.lrc target.lrc # Synchronize a VTT file using another VTT file as reference sub-cli sync reference.vtt target.vtt + +# Synchronize an ASS file using another ASS file as reference +sub-cli sync reference.ass target.ass ``` ## fmt @@ -202,6 +235,7 @@ sub-cli fmt | SRT | `.srt` | Standardizes entry numbering (sequential from 1)
Formats timestamps in `00:00:00,000` format
Ensures proper spacing between entries | | LRC | `.lrc` | Organizes metadata tags
Standardizes timestamp format `[mm:ss.xx]`
Ensures proper content alignment | | VTT | `.vtt` | Validates WEBVTT header
Standardizes cue identifiers
Formats timestamps in `00:00:00.000` format
Organizes styling information | +| ASS | `.ass` | Standardizes section order ([Script Info], [V4+ Styles], [Events])
Formats timestamps in `h:mm:ss.cc` format
Preserves all script info, styles and event data | ### Format-Specific Details @@ -214,6 +248,9 @@ For LRC files, the formatter preserves all metadata and content but standardizes #### VTT Formatting When formatting WebVTT files, the command ensures proper header format, sequential cue identifiers, and standard timestamp formatting. All VTT-specific features like styling, positioning, and comments are preserved. +#### ASS Formatting +The formatter reads and parses the ASS file, then regenerates it with standardized structure. It maintains all original content, including script information, styles, and events. The standard section order ([Script Info], [V4+ Styles], [Events]) is enforced, and timestamps are formatted in the standard `h:mm:ss.cc` format. + ### Examples ```bash @@ -225,6 +262,9 @@ sub-cli fmt lyrics.lrc # Format a VTT file sub-cli fmt subtitles.vtt + +# Format an ASS file +sub-cli fmt subtitles.ass ``` ## version @@ -261,3 +301,4 @@ sub-cli help # Display help for the convert command sub-cli help convert +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index 449e2c4..c1d43f5 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -15,13 +15,13 @@ Sub-CLI is a command-line tool designed for subtitle manipulation and generation ## What Can Sub-CLI Do? -- **Convert** between various subtitle formats (SRT, VTT, LRC, TXT) +- **Convert** between various subtitle formats (SRT, VTT, LRC, ASS, TXT) - **Synchronize** timelines between subtitle files - **Format** subtitle files to ensure consistent styling ## Key Features -- **Format Flexibility**: Support for multiple subtitle formats including SRT, VTT, LRC, and plain text +- **Format Flexibility**: Support for multiple subtitle formats including SRT, VTT, LRC, ASS, and plain text - **Timeline Synchronization**: Easily align subtitles with audio/video content - **Format-Specific Feature Preservation**: Maintains format-specific features during conversion - **Clean Command Interface**: Simple, intuitive commands for efficient workflow @@ -48,6 +48,9 @@ sub-cli sync source.srt target.srt # Format a subtitle file sub-cli fmt subtitle.srt + +# Convert to ASS format +sub-cli convert input.srt output.ass ``` Check out the [Command Examples](/examples) page for more detailed usage scenarios. diff --git a/docs/zh-Hans/commands.md b/docs/zh-Hans/commands.md index 18ed86b..79d0142 100644 --- a/docs/zh-Hans/commands.md +++ b/docs/zh-Hans/commands.md @@ -36,9 +36,10 @@ sub-cli convert <源文件> <目标文件> | 源格式 | 目标格式 | 注意 | |---------------|---------------|-------| -| SRT (.srt) | SRT, VTT, LRC, TXT | - | -| VTT (.vtt) | SRT, VTT, LRC, TXT | - | -| LRC (.lrc) | SRT, VTT, LRC, TXT | - | +| SRT (.srt) | SRT, VTT, LRC, TXT, ASS | - | +| VTT (.vtt) | SRT, VTT, LRC, TXT, ASS | - | +| LRC (.lrc) | SRT, VTT, LRC, TXT, ASS | - | +| ASS (.ass) | SRT, VTT, LRC, TXT, ASS | - | | TXT (.txt) | — | TXT只能作为目标格式，不能作为源格式 | ### 功能保留 @@ -61,6 +62,18 @@ sub-cli convert <源文件> <目标文件> - 对于最后一个条目，添加默认时长（通常3-5秒）来创建结束时间 - **转换为LRC时丢失**: 当其他格式转换为LRC时，任何结束时间戳信息都会被丢弃 +#### ASS功能 +- **保留**: 文本内容、时间线（开始和结束时间）、基本样式信息 +- **仅有基本支持**: 转换创建一个具有基本结构的"最小"ASS文件 +- **转换为ASS时**: + - 基本样式（粗体、斜体、下划线）会转换为具有默认设置的ASS样式 + - 默认字体为Arial，大小20pt，具有标准颜色和边距 + - 只创建"Dialogue"（对话）类型的事件（不创建"Comment"或其他事件类型） +- **从ASS转换时**: + - 只转换类型为"Dialogue"的事件，忽略"Comment"事件 + - 在目标格式支持的情况下保留样式信息 + - ASS特有的属性（如Layer、MarginL/R/V等）在可能的情况下存储为元数据 + #### TXT功能 - **仅输出**: 纯文本格式只包含没有任何时间或样式的文本内容 @@ -83,6 +96,12 @@ sub-cli convert lyrics.lrc transcript.txt # 从WebVTT转换为SRT sub-cli convert subtitles.vtt subtitles.srt + +# 从SRT转换为ASS +sub-cli convert subtitles.srt subtitles.ass + +# 从ASS转换为SRT +sub-cli convert subtitles.ass subtitles.srt ``` ## sync @@ -108,6 +127,7 @@ sub-cli sync <源文件> <目标文件> - SRT到SRT - LRC到LRC - VTT到VTT +- ASS到ASS ### 行为详情 @@ -128,19 +148,29 @@ sub-cli sync <源文件> <目标文件> - 开始时间使用源条目之间的线性插值计算 - 结束时间根据源条目时长计算 - 保持条目之间的时间关系 -- **从目标保留**: 所有字幕文本内容。 +- **从目标保留**: 所有内容文本。 - **在目标中修改**: 更新时间戳并标准化条目编号（从1开始顺序编号）。 #### 对于VTT文件： - **当条目数匹配时**: 源的开始和结束时间直接应用于目标条目。 -- **当条目数不同时**: 使用基于线性插值的缩放方法，类似于SRT同步： +- **当条目数不同时**: 使用基于线性插值的缩放方法： - 开始时间使用源条目之间的线性插值计算 - 结束时间根据源条目时长计算 - 保持条目之间的时间关系 - **从目标保留**: 所有字幕文本内容和样式信息。 - **在目标中修改**: 更新时间戳并标准化提示标识符。 +#### 对于ASS文件： + +- **当条目数匹配时**: 源时间线（开始和结束时间）直接应用于目标事件。 +- **当条目数不同时**: 使用基于线性插值的缩放方法： + - 开始时间使用源事件之间的线性插值计算 + - 结束时间根据源事件时长计算 + - 保持事件之间的时间关系 +- **从目标保留**: 所有事件文本内容、样式引用和其他属性（如Layer、MarginL/R/V）。 +- **在目标中修改**: 只更新时间戳（Start和End）。 + ### 时间线插值详情 同步命令使用线性插值来处理源文件和目标文件之间不同的条目数量： @@ -177,6 +207,9 @@ sub-cli sync reference.lrc target.lrc # 使用另一个VTT文件作为参考来同步VTT文件 sub-cli sync reference.vtt target.vtt + +# 使用另一个ASS文件作为参考来同步ASS文件 +sub-cli sync reference.ass target.ass ``` ## fmt @@ -202,6 +235,7 @@ sub-cli fmt <文件> | SRT | `.srt` | 标准化条目编号（从1开始顺序）
格式化时间戳为`00:00:00,000`格式
确保条目之间适当的间距 | | LRC | `.lrc` | 组织元数据标签
标准化时间戳格式`[mm:ss.xx]`
确保正确的内容对齐 | | VTT | `.vtt` | 验证WEBVTT头
标准化提示标识符
格式化时间戳为`00:00:00.000`格式
组织样式信息 | +| ASS | `.ass` | 标准化部分顺序（[Script Info], [V4+ Styles], [Events]）
格式化时间戳为`h:mm:ss.cc`格式
保留所有脚本信息、样式和事件数据 | ### 格式特定详情 @@ -214,6 +248,9 @@ sub-cli fmt <文件> #### VTT格式化 格式化WebVTT文件时，命令确保适当的头格式、顺序提示标识符和标准时间戳格式。所有VTT特定功能（如样式、定位和注释）都被保留。 +#### ASS格式化 +格式化器读取并解析ASS文件，然后以标准化结构重新生成它。它保持所有原始内容，包括脚本信息、样式和事件。强制执行标准部分顺序（[Script Info], [V4+ Styles], [Events]），并以标准的`h:mm:ss.cc`格式格式化时间戳。 + ### 示例 ```bash @@ -225,6 +262,9 @@ sub-cli fmt lyrics.lrc # 格式化VTT文件 sub-cli fmt subtitles.vtt + +# 格式化ASS文件 +sub-cli fmt subtitles.ass ``` ## version diff --git a/docs/zh-Hans/getting-started.md b/docs/zh-Hans/getting-started.md index 7f2657a..a3c77d3 100644 --- a/docs/zh-Hans/getting-started.md +++ b/docs/zh-Hans/getting-started.md @@ -15,13 +15,13 @@ Sub-CLI 是一款专为字幕处理和生成设计的命令行工具。无论您 ## Sub-CLI 能做什么？ -- **转换**：在多种字幕格式之间转换（SRT、VTT、LRC、TXT） +- **转换**：在多种字幕格式之间转换（SRT、VTT、LRC、ASS、TXT） - **同步**：字幕文件之间的时间轴同步 - **格式化**：确保字幕文件具有一致的样式 ## 主要特点 -- **格式灵活性**：支持多种字幕格式，包括 SRT、VTT、LRC 和纯文本 +- **格式灵活性**：支持多种字幕格式，包括 SRT、VTT、LRC、ASS 和纯文本 - **时间轴同步**：轻松将字幕与音频/视频内容对齐 - **格式特定功能保留**：在转换过程中保持格式特定的功能 - **简洁的命令界面**：简单、直观的命令，提高工作效率 @@ -48,6 +48,9 @@ sub-cli sync source.srt target.srt # 格式化字幕文件 sub-cli fmt subtitle.srt + +# 转换为ASS格式 +sub-cli convert input.srt output.ass ``` 查看[命令示例](/zh-Hans/examples)页面获取更多详细使用场景。