304 lines
12 KiB
Markdown
304 lines
12 KiB
Markdown
---
|
|
title: Command Reference
|
|
description: Detailed documentation for all Sub-CLI commands
|
|
---
|
|
|
|
# Command Reference
|
|
|
|
This page provides detailed documentation for all available Sub-CLI commands, their options, and usage.
|
|
|
|
## Global Options
|
|
|
|
These options are available across all Sub-CLI commands:
|
|
|
|
```
|
|
help Display help information for a command
|
|
```
|
|
|
|
## convert
|
|
|
|
The `convert` command transforms subtitle files between different formats, preserving as much information as possible while adapting to the target format's capabilities.
|
|
|
|
### Usage
|
|
|
|
```
|
|
sub-cli convert <source> <target>
|
|
```
|
|
|
|
### Arguments
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `<source>` | Path to the source subtitle file |
|
|
| `<target>` | Path to the target subtitle file to be created |
|
|
|
|
### Supported Format Conversions
|
|
|
|
| Source Format | Target Format | Notes |
|
|
|---------------|---------------|-------|
|
|
| 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
|
|
|
|
The conversion process aims to preserve as many features as possible, but some format-specific features may be lost or adapted:
|
|
|
|
#### SRT Features
|
|
- **Preserved**: Text content, timeline (start and end times), basic styling (bold, italic, underline)
|
|
- **Lost in some formats**: HTML styling tags when converting to formats like LRC or TXT
|
|
|
|
#### VTT Features
|
|
- **Preserved**: Text content, timeline, title, CSS styling (when target supports it)
|
|
- **Lost in some formats**: Positioning, alignment, and advanced styling when converting to SRT or LRC
|
|
|
|
#### LRC Features
|
|
- **Preserved**: Text content, timeline, metadata (title, artist, album)
|
|
- **Structure limitation**: LRC only supports start timestamps (no end timestamps), unlike SRT and VTT
|
|
- **Adapted when converting from LRC**: When converting to SRT/VTT, the single timestamp per line in LRC is converted to start+end time pairs. End times are calculated by:
|
|
- Using the next entry's start time as the current entry's end time
|
|
- 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
|
|
|
|
### Technical Details
|
|
|
|
The converter uses an intermediate representation that attempts to preserve as much format-specific data as possible. The conversion happens in two steps:
|
|
1. Convert source format to intermediate representation
|
|
2. Convert intermediate representation to target format
|
|
|
|
This approach minimizes information loss and ensures the most accurate conversion possible.
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Convert from SRT to WebVTT
|
|
sub-cli convert subtitles.srt subtitles.vtt
|
|
|
|
# Convert from LRC to plain text (strips timing info)
|
|
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
|
|
|
|
The `sync` command applies the timing/timestamps from a source subtitle file to a target subtitle file while preserving the target file's content.
|
|
|
|
### Usage
|
|
|
|
```
|
|
sub-cli sync <source> <target>
|
|
```
|
|
|
|
### Arguments
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `<source>` | Path to the source subtitle file with the reference timeline |
|
|
| `<target>` | Path to the target subtitle file to be synchronized |
|
|
|
|
### Supported Formats
|
|
|
|
Currently, synchronization only works between files of the same format:
|
|
- SRT to SRT
|
|
- LRC to LRC
|
|
- VTT to VTT
|
|
- ASS to ASS
|
|
|
|
### Behavior Details
|
|
|
|
#### For LRC Files:
|
|
|
|
- **When entry counts match**: The source timeline is directly applied to the target content.
|
|
- **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 distribution across varying entry counts
|
|
- **Preserved from target**: All content text and metadata (artist, title, etc.).
|
|
- **Modified in target**: Only timestamps are updated.
|
|
|
|
#### For SRT 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:
|
|
- Start times are calculated using linear interpolation between source entries
|
|
- End times are calculated based on source entry durations
|
|
- 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:
|
|
- Start times are calculated using linear interpolation between source entries
|
|
- End times are calculated based on source entry durations
|
|
- 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
|
|
|
|
The sync command uses linear interpolation to handle different entry counts between source and target files:
|
|
|
|
- **What is linear interpolation?** It's a mathematical technique for estimating values between two known points. For timeline synchronization, it creates a smooth transition between source timestamps when applied to a different number of target entries.
|
|
|
|
- **How it works:**
|
|
1. The algorithm maps each target entry position to a corresponding position in the source timeline
|
|
2. For each target position, it calculates a timestamp by interpolating between the nearest source timestamps
|
|
3. The calculation ensures proportionally distributed timestamps that maintain the rhythm of the original
|
|
|
|
- **Example:** If source file has entries at 1s, 5s, and 9s (3 entries), and target has 5 entries, the interpolated timestamps would be approximately 1s, 3s, 5s, 7s, and 9s, maintaining even spacing.
|
|
|
|
- **Benefits of linear interpolation:**
|
|
- More accurate timing when entry counts differ significantly
|
|
- Preserves the pacing and rhythm of the source timeline
|
|
- Handles both expanding (target has more entries) and contracting (target has fewer entries) scenarios
|
|
|
|
### Edge Cases
|
|
|
|
- If the source file has no timing information, the target remains unchanged.
|
|
- If source duration calculations result in negative values, a default duration of zero is applied (improved from previous 3-second default).
|
|
- The command displays a warning when entry counts differ but proceeds with the scaled synchronization.
|
|
- Format-specific features from the target file (such as styling, alignment, metadata) are preserved. The sync operation only replaces timestamps, not any other formatting or content features.
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Synchronize an SRT file using another SRT file as reference
|
|
sub-cli sync reference.srt target.srt
|
|
|
|
# Synchronize an LRC file using another LRC file as reference
|
|
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
|
|
|
|
The `fmt` command standardizes and formats subtitle files according to their format-specific conventions.
|
|
|
|
### Usage
|
|
|
|
```
|
|
sub-cli fmt <file>
|
|
```
|
|
|
|
### Arguments
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `<file>` | Path to the subtitle file to format |
|
|
|
|
### Supported Formats
|
|
|
|
| Format | Extension | Formatting Actions |
|
|
|--------|-----------|-------------------|
|
|
| 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
|
|
|
|
#### SRT Formatting
|
|
The formatter parses the SRT file, extracts all entries, ensures sequential numbering from 1, and writes the file back with consistent formatting. This preserves all content and timing information while standardizing the structure.
|
|
|
|
#### LRC Formatting
|
|
For LRC files, the formatter preserves all metadata and content but standardizes the format of timestamps and ensures proper alignment. This makes the file easier to read and more compatible with different LRC parsers.
|
|
|
|
#### 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
|
|
# Format an SRT file
|
|
sub-cli fmt subtitles.srt
|
|
|
|
# Format an LRC file
|
|
sub-cli fmt lyrics.lrc
|
|
|
|
# Format a VTT file
|
|
sub-cli fmt subtitles.vtt
|
|
|
|
# Format an ASS file
|
|
sub-cli fmt subtitles.ass
|
|
```
|
|
|
|
## version
|
|
|
|
Displays the current version of Sub-CLI.
|
|
|
|
### Usage
|
|
|
|
```
|
|
sub-cli version
|
|
```
|
|
|
|
## help
|
|
|
|
Displays general help information or help for a specific command.
|
|
|
|
### Usage
|
|
|
|
```
|
|
sub-cli help [command]
|
|
```
|
|
|
|
### Arguments
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `[command]` | (Optional) Specific command to get help for |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Display general help
|
|
sub-cli help
|
|
|
|
# Display help for the convert command
|
|
sub-cli help convert
|
|
```
|