sub-cli/docs/commands.md

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

```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
```

## 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:
  - 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
- **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 the nearest 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 using linear interpolation is used, similar to SRT synchronization:
  - Start times are calculated using linear interpolation between the nearest 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).

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

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

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

```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
```

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