wholetrans/sub-cli
1
0
Fork 0
Code Issues Pull requests Projects Releases 4 Packages Wiki Activity Actions

docs: add ass docs

Browse source
This commit is contained in:
CDN 2025-04-23 19:33:02 +08:00
parent 76e1298ded
commit 6d730fa69b
Signed by: CDN
GPG key ID: 0C656827F9F80080
4 changed files with 109 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

67
docs/commands.md
View file

@ -36,9 +36,10 @@ sub-cli convert <source> <target>
| 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 <file>
| SRT | `.srt` | Standardizes entry numbering (sequential from 1)<br>Formats timestamps in `00:00:00,000` format<br>Ensures proper spacing between entries |
| LRC | `.lrc` | Organizes metadata tags<br>Standardizes timestamp format `[mm:ss.xx]`<br>Ensures proper content alignment |
| VTT | `.vtt` | Validates WEBVTT header<br>Standardizes cue identifiers<br>Formats timestamps in `00:00:00.000` format<br>Organizes styling information |
| ASS | `.ass` | Standardizes section order ([Script Info], [V4+ Styles], [Events])<br>Formats timestamps in `h:mm:ss.cc` format<br>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
```