sub-cli/docs/commands.md

title	description
Command Reference	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

# 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

# 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) 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

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

# 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

# Display general help
sub-cli help

# Display help for the convert command
sub-cli help convert