EmbedSubs CLI Documentation
EmbedSubs is an interactive developer tool that muxes multiple selectable subtitle tracks into a video without re-encoding its video or audio streams. It guides you through selecting media files, labeling languages according to ISO standards, selecting a default track, and generating an MP4 or MKV output.
Subtitles are packaged as independent tracks that can be enabled, disabled, or switched in VLC, QuickTime, mpv, or smart TVs.
Video and audio streams are copied bit-for-bit without decompression, preserving 100% of your camera sharpness, color grade, and bitrate.
System Requirements
Before running EmbedSubs, confirm your environment meets the following verified dependencies:
Node.js >= 22.13.0
Node 24 LTS strongly recommended.
FFmpeg & FFprobe
Must be installed & accessible in system PATH.
Hard Links Supported
NTFS, APFS, or ext4 required for output destination.
Installation & Setup
Follow the platform instructions below to set up FFmpeg and install the EmbedSubs CLI on your system:
CLI Installation Options
Version 0.1.0 is prepared for local use and review. Choose your preferred setup:
Prerequisite: FFmpeg & FFprobe Setup
EmbedSubs requires native ffmpeg and ffprobe available in your system PATH.
Quick Start Interactive Workflow
Launch the tool directly in your interactive terminal:
The 7-Step Interactive Prompt Walkthrough:
- 1. Video Path:
Enter the absolute path to your source video file. Paths with spaces can be wrapped in double quotes:
"C:\Users\John\Videos\Feature Film 4K.mp4" - 2. Subtitle Paths:
Enter one or more subtitle paths separated by commas. If a file or directory contains commas, quote that path:
"./subs/Movie, Part 1.en.srt", ./subs/Movie.si.srt, ./subs/Movie.es.vtt - 3. Language Configuration:
EmbedSubs detects language hints from filenames (e.g. .en.srt → English) and validates against ISO 639-3 data. Review or adjust each language tag.
- 4. Track Titles & Labels:
Assign user-visible track titles (e.g. "English (Full)" or "Director Commentary Subtitles").
- 5. Default Subtitle Selection:
Select which subtitle track should activate by default on playback, or choose "None" for an all-disabled initial state.
- 6. Output Container:
Choose MP4 (standard device playback) or MKV (unrestricted subtitle styling & font attachments).
- 7. Execution & Verification:
Review the plan summary and confirm. EmbedSubs executes FFmpeg with stream copying, runs a structural FFprobe verification on the output, and links the finished media to your disk.
Supported Formats & Codec Compatibility
EmbedSubs supports external subtitle inputs in .srt, .vtt, .ass, and .ssa formats. Each input is verified using FFprobe structural stream analysis.
| Track / Format | MP4 Output Behavior | MKV Output Behavior | Technical Details |
|---|---|---|---|
| SRT / SubRip (.srt) | Convert to mov_text | Copy directly (Bit-exact) | Most popular format. UTF-8 encoded files strongly recommended. |
| WebVTT (.vtt) | Convert to mov_text | Copy directly | HTML5 web standard subtitle tracks mapped cleanly. |
| ASS / SSA (.ass, .ssa) | Convert to mov_text (styling simplified) | Copy directly (Preserves styles & fonts) | Choose MKV if complex typography, positioning, or animations matter. |
| Existing mov_text | Stream copy | Convert to SRT | Preserves existing MP4 subtitle tracks without quality loss. |
| Existing plain text subtitles | Convert to mov_text | Convert to SRT | Normalized to container standards. |
| Existing PGS, DVD, DVB image subtitles | Rejected (Incompatible) | Copy when accepted by Matroska muxer | Bitmap/image subtitle formats are supported in MKV, but rejected in MP4. |
| Single-Sample tmcd timecode track | Reconstruct with write_tmcd & verify | Rejected (Conversion unsupported) | Common in DaVinci Resolve / NLE exports. Verified for sample rate & value. |
| Unknown / Incompatible Data Streams | Rejected (Safe failure) | Rejected (Safe failure) | EmbedSubs rejects rather than silently discarding unknown tracks. |
Language Configuration & Metadata
Accurate language metadata ensures modern media players (Apple TV, VLC, Plex, iOS) display recognizable language labels in their audio/subtitle menus:
Filenames such as movie.en.srt, movie.sinhala.vtt, or movie.ja.ass automatically trigger language suggestions. This is a filename heuristic—always review the detected tag during interactive prompts.
Both 2-letter (ISO 639-1) and 3-letter codes are validated and normalized against the official ISO 639-3 standard (e.g. en → eng, es → spa, si → sin). Use und for undetermined languages.
In MP4 containers, human-readable track titles are stored in the handler_name atom. In MKV containers, titles are stored in the title tag. EmbedSubs maps these accurately according to container specifications.
Stream Preservation & NLE Timecodes
EmbedSubs enforces a zero-reencode policy. All primary audio and video streams use stream copy (-c:v copy -c:a copy).
Existing chapters, timings, and compatible metadata are mapped into the destination container. Post-mux FFprobe checks verify chapter counts and timestamps to ensure bookmark navigation remains unaffected.
Professional video editors (such as DaVinci Resolve) often output MP4 files with an unknown-codec tmcd timecode track. Normally, FFmpeg stream copying crashes on this track.
EmbedSubs detects single-sample timecode tracks matching video duration, excludes them from direct copying, and rebuilds the timecode track using FFmpeg's write_tmcd option. Verification audits the reconstructed timecode value, sample count, and frame rate.
Output Safety & Verification
Media corruption and accidental file overwrites are unacceptable in production workflows. EmbedSubs protects your media through a 3-tier safety design:
Jobs execute in a unique .embedsubs-* directory beside the destination. No partial media is ever written directly to your destination path.
Before finalization, FFprobe inspects stream counts, codecs, language tags, track titles, and chapter timings. If verification fails, the job aborts safely without touching the destination.
The verified output is committed via an atomic, exclusive hard link. If a destination filename already exists, the process halts safely without overwriting.
Troubleshooting & Known Edge Cases
If you encounter an error or unexpected output behavior, consult the diagnostics table below:
EmbedSubs checks for both native binaries before initiating prompts. If either is missing, it exits immediately.
Install FFmpeg using your package manager, verify with 'ffmpeg -version', and restart your terminal session.
# Windows
winget install Gyan.FFmpeg
# macOS
brew install ffmpeg
# Linux
sudo apt install ffmpegFrequently Asked Questions
Answers to common questions regarding soft subtitle multiplexing, video integrity, and container differences:
EmbedSubs Web Application
Don't have terminal access or need to quickly add a subtitle track on a mobile device or Chromebook? Try the EmbedSubs browser application. Media is processed locally in-memory inside your browser tab without uploading video to any cloud server.