Skip to content

Tools for managing subtitle files in the command line.

Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



14 Commits

Repository files navigation

Subtitle Tools

Tools for managing subtitle files in command line.


  1. Install using npm install -g subtitle-tools
  2. Run commands using subtitle-tools [command...]



Merge two or more subtitle files. Set output using --output or -o.

# Example:
> subtitle-tools merge ep01.ass op.ass ed.ass -o ep01-final.ass

Those are the line collision handling modes:

  • Overlap (default) just disables checking, leave the renderer to handle it.
  • KeepFirst keep lines from first files on collisions, remove the rest.
  • ChangeAlignment move overlapping lines above, remove if they were already there.
  • ChangeStyle changes style to ${style}_overlap on collisions, remove if the style does not exist.

Those are the style collision handling modes:

  • Rename (default) renames styles on collisions
  • KeepFirst keep the first style on collisions.
  • KeepLast keep the last style on collisions

Those are the layer handling modes:

  • Unchanged (default) layers are not changed on collisions.
  • FirstAbove keep the first line above on collisions.
  • LastAbove keep the last line above on collisions.

Metadata sections such as Script Info and Aegisub Project Garbage are not merged by default. You can enable it with --merge-metadata.

If subtitle files have different resolutions all subtitles will be resampled to use the first subtitle resolution.


List fonts and their variants used in one or more files.

# Example:
> subtitle-tools list-fonts op.ass ep01.ass ed.ass
Font A
Font A:bold
Font B
Font B:italic
Font C:bold:italic


  • Only ASS v4.00+ files are supported, as it uses ass-parser.
  • You can use --help do get more info about each command arguments.
  • For programmatic use check functions defined in lib/utils.js.
  • Subtitle resampling code was loosely translated from C++ using arch1t3cht/Aegisub's code as reference.


Tools for managing subtitle files in the command line.