doggy8088/caption-convert

Overview

This skill converts subtitle and caption files between .srt, .vtt, and .ass formats using the caption-convert CLI. It relies on filename extensions to detect input and output formats and provides a bundled CLI for use outside the project. Use it to quickly change container formats, normalize headers, and prepare captions for different players or workflows.

How this skill works

The skill runs the caption-convert CLI (either the installed binary or the bundled scripts/cli.mjs) and infers formats strictly from the input and output file extensions. It parses cues, converts timing and basic text content, normalizes headers (for example adding a WEBVTT header for .vtt), and applies fixed ASS headers/styles when producing .ass output. The tool skips unparseable cues and strips ASS override tags while converting line-break markers into real line breaks.

When to use it

• You need to change subtitle files from .srt to .vtt, .vtt to .ass, or any supported pair.
• Preparing captions for a web player that requires WebVTT (adds WEBVTT header).
• Generating an ASS file with a fixed header/style for an editor or player that expects ASS.
• Quick command-line conversion during encoding, publishing, or quality checks.
• When you want a bundled, node-based converter without installing extra packages globally.

Best practices

• Always include the correct file extensions on both source and target paths; the tool uses them to decide formats.
• Spot-check converted files for timing accuracy and header correctness, especially after bulk conversions.
• Keep a copy of the original file; cues with invalid timing are skipped rather than repaired.
• When converting to .ass, expect styling from the source to be lost; plan to reapply styles in an ASS editor if needed.
• Use Node.js 18+ when running the bundled cli.mjs to avoid runtime issues.

Example use cases

• Convert broadcast .srt captions into .vtt for web delivery.
• Create a basic .ass file from .vtt for a player that requires ASS formatting.
• Batch convert a folder of .srt files to .vtt before uploading to a streaming platform.
• Run the bundled scripts/cli.mjs on a machine without the package installed.
• Validate that files include proper headers after automated conversions.