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

8 KiB
Raw Blame History

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 -
VTT (.vtt) SRT, VTT, LRC, TXT -
LRC (.lrc) SRT, VTT, LRC, TXT -
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

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

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

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.
  • 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 is used:
    • Start times are taken from proportionally matched 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).

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 is used, similar to SRT synchronization:
    • Start times are taken from proportionally matched 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).

Edge Cases

  • If the source file has no timing information, the target remains unchanged.
  • If source duration calculations result in negative values, a default 3-second duration is applied.
  • 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

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

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.

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

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