Repository files navigation

A command-line utility to batch-add subtitles, attachments, chapters and more to media files

Explore the docs »

Bug Report ·Request a Feature ·Fork Repo

• Index
• About the project
• Terminology
  • Extra file vs Media file
  • Source Directory vs Root Directory
  • Wrap-up
• Installation
  • Compiling from source
• Setup
• Documentation
  • Syntax
• Flags
  • Boolean Flags
    • Log
    • Test
    • Version
    • Direct
    • Summary
  • Miscellaneous Flags
    • Root
    • Language
    • Subtitle
    • FFmpeg
    • FFprobe
    • Exclude
    • RExclude
    • Summary
• Advanced Usage
  • Recognized Extensions
    • MediaFiles
    • Subtitles
    • Attachments
    • Chapters
  • Examples
• Roadmap
• Forks
  • Deploying a fork
• Acknowledgments
• License
• Just some fun

Auto-sub is simply a command line tool to batch add subtitles, chapters, attachments to media files usingFFmpeg.

The final result will be in a matroska (.mkv) container containing the original media file, along with subtitles, attachments, chapters, tags, etc.

This section defines the basic terms used in the rest of the project.

Media file is the central video file to which the subtitles, attachments, chapters will be attached. Each source directory should containexactly one media file - the program will throw an error if no media file is found in a directory, or if multiple media files are found!

On the other hand,extra file could refer to any other files present in the source directory apart from the media file - this could be a file containing subtitles, attachments, chapters, tags, etc.

Any directory containing exactlyone media file, andone or more extra files is asource directory. At the most basic level,auto-sub acts upon source directories, locating the media file and extra file(s) present in each source directory, and merging them to make a single file in a matroska container.

Root directory, refers to a parent directory containing multiple source directories. Remember how a source directory can have onlyone media file? In order to work upon multiple media files, make a root directory that contains multiple source directories, with each source directory containing a media file and extra file(s). This parent directory becomes theroot directory.

As an example;

  /home/User/Movies    ├── Dir 01    │   ├── subtitles.ass    │   ├── Movie 01.mkv    │   ├── chapters.xml    │   └── tags.xml    ├── Dir 02    │   ├── Subtitles.ass    │   ├── Movie 02.mkv    │   ├── chapters.xml    │   └── tags.xml

In the example above, `/home/User/Movies` acts as theroot directory, this root directory contains twosource directories inside it; namely, `Dir 01` and `Dir 02`. Each of these source directories further contains a media file (Movie XX.mkv), a subtitle file, and accompanying chapters and tags.

P.S: Internally,auto-sub differentiates (and recognizes) files from their extensions. Head over tothis section for a list of accepted file extensions.

A simple summary for this section;

• A source directory should haveexactly one media file andat least one extra file
• Any directory containingexactly one media file, andone or more extra file(s) is asource directory
• The parent directory containingone or more source directories is theroot directory

Auto-Sub is a Go program, it can be used directly as a portable binary or executable file.

• Download the relevant binary for your system.
• Extractauto-sub orauto-sub.exe file from the archive
• Runauto-sub -v to test

Check out thedocumentation for more info on how to use auto-sub.

Note: These instructions are to generate an executable from the source-code by yourself. If you want an easier solution, follow the instructions above to download a pre-compiled executable.

Make sure you haveGo installed.Download Go for your system if required.

git clone https://github.com/demon-rem/auto-subcd ./auto-subgo build./auto-sub -v

The steps above will generate a binary/executable file namedauto-sub orauto-sub.exe in the same directory.

Auto-sub uses FFmpeg in the backend. Make sure you have FFmpeg and FFprobe installed before usingauto-sub. To install FFmpeg or FFprobe, follow the instructions listedhere.

Once done, move over to testing your setup withauto-sub;

auto-sub --test

If everything is in place,auto-sub should be able to list out the versions of FFmpeg and FFprobe installed in your system. The output should look something like;

[demon-rem@albedo ~]$ auto-sub --testFFmpeg version found: n4.3.1FFprobe version found: n4.3.1

Ifauto-sub is unable to locate either FFmpeg or FFprobe, an error message will appear instead, or you'll be asked to manually enter path to FFmpeg/FFprobe executables. See the section onmiscellaneous flags to manually set the path to FFmpeg/FFprobe executables.

Advanced Setup

This section explains how to setupauto-sub to run it directly from the command prompt (without having to change directories).

• Windows users can add path to the executable as anenvironment variable

• Linux or Mac users can move the binary to/usr/local/bin (or/usr/bin) to achieve the same result.

Auto-sub is simply a wrapper over FFmpeg, its syntax is like this;

auto-sub ["/path/to/root"] [flags]

Note: While usingauto-sub, the only input required is the path to the root (or source) directory. This path can be provided as an argument,or through theroot flag.

Flags can help you fine-tune the workings ofauto-sub to match your needs, for example,ignoring a particular file, orignoring any file that meets a regex pattern, and more.

This section contains a comprehensive list of valid flags forauto-sub, their usage, default values, and expected input. Some flags may have a shorthand version in addition to the normal flag - both of these versions can be used interchangeably. Head over to theexamples section to take a look at how to use these flags.

Note thatall of these flags are optional - as such,auto-sub can work perfectly fine even without them!

All boolean flags are disabled by default, using a boolean flag in the command while runningauto-sub will enable it.

Enables logging, generates a log report for the run. Log files will be helpful to get crash reports, and/or filing an issue for a bug. The log file will be stored in the current working directory, named "[auto-sub] logs.txt" (runcwd in Windows, orpwd in Linux/Mac to get the working directory)

Test flag exists to explicitly test your setup, this includes attempting to locate FFmpeg and FFprobe executables implicitly, and fetching their versions (if found). Once the test completes,auto-sub will exit by default, as such, the test flag can't be used outside running the initial test.

Returns the current version ofauto-sub present in your system.

By default, the path entered is assumed to belong to a root directory (which will internally contain one or more source directories). In case you want to runauto-sub for an individualsource directory, using this flag ensures that the path will be treated as a source directory. For more details, take a look atsource directory vs root directory

Unlike the boolean flags that can be simply added to the command, these flags require a value. Do note thatauto-sub may forcibly stop if the value entered through these flags is invalid/unexpected.

Path toroot directory. Note that path to root directory can also be passed in as an argument. Passing path to the root directory as an argumentmay be deprecated/modified in the future, if you're making a bash/batch script wrapper aroundauto-sub, you may want to use this flag instead of the argument.

Note: This flag has higher precedence than the path provided through argument. As such, if the path to root directory is passed in as an argument, as well as through this flag, the value obtained through this flag will be used, and the argument will be discarded.

Dictates the language code for subtitle files. Among other things, this will be used by media players to select/ignore a subtitle stream based on user preferences. The default value for this flag is "eng" (language code for English).Here is a comprehensive list of language codes.

Note: The same language code will be applied to all subtitle streams.

Sets the title for the subtitle stream. If a value for this flag is not provided, the filename of the subtitle file (minus the file extension) will be used by default.

Note: The same title will be applied to all subtitle streams, for all source directories.

Path to FFmpeg executable. This will be a binary file for Linux, and.exe file for Windows users. For most users,auto-sub should be able to implicitly fill this value during runtime. This flag can be used to modify the default value, or to manually enter the path to FFmpeg in caseauto-sub is unable to locate it.

Similar to theffmpeg flag, this flag sets the path to the FFprobe executable. Again, for most users,auto-sub should be able to implicitly populate this value during runtime.

Explicitly mark out files to be ignored using their names - note that files withunrecognized extensions are always ignored. If the name of a file (inclusive of extension), matches a value present in this list, the file will be ignored byauto-sub.

Note: Multiple ignore rules separated by a comma can be added to this flag. This flag can also be used multiple times in the same command.

Short for regex-Exclude, this flag ignores any file that matches a regular expression. The regex syntax needs to be in accordance withRE2. For a simple cheatsheet for RE2 regex syntax, you may want to take a lookhere.

Internally, auto-sub differentiates between file types using their extensions. This section contains a comprehensive list of file extensions recognized by auto-sub, and the category these files are recognized as.

Files with unrecognized extensions will beignored by auto-sub. Alternatively, select files can be deliberately ignored due to ignore rules (ignore rules can be set usingflags)

Supported file extensions;

• .mkv
• .mp4
• .webm
• .m2ts

Supported file extensions;

• .srt
• .ass
• .sup
• .pgs
• .vtt

Supported file extensions;

• .ttf
• .otf

Supported file extensions;

• .xml

Some example commands to demonstrate how to use the flags/arguments withauto-sub

• Testing the setup with custom FFmpeg and FFprobe path(s)

Usesffmpeg flag andffprobe flag. Note that the path to root directory isn't required with the test flag.

auto-sub --test --ffmpeg="/path/to/ffmpeg" --ffprobe="/path/to/ffprobe"

• Runningauto-sub with logging enabled

Useslog flag. Once the command completes execution, usecwd orpwd to get the path to directory containing the log file

auto-sub"/path/to/root/directory" --log

• Excluding any file with.mp4 extension

Usesroot flag andregex-Exclude flag. The path to root directory can also be provided as an argument instead of using the root flag.

auto-sub --root="/path/to/root/directory" --rexclude=".*\.mp4$"

• Excluding specific files

Uses theExclude flag. Note that only files with complete matches (inclusive of extensions) will be ignored, i.e. adding an ignore rule for "word" will not result inauto-sub ignoring a file named "word.txt". The Exclude flag can be used multiple times, all the ignore rules will be added together.

auto-sub --root="/path/to/root" --Exclude="test, test.mp4" --Exclude="another ignore rule.txt" --Exclude="source.mkv"

• Working on a source directory instead of root directory

Using thedirect flag ensures thatauto-sub identifies the path to lead to a source directory (instead of a root directory)

auto-sub --root="/path/to/source/directory" --direct

• Passing paths through the argument and flag

auto-sub"/path/to/dir01" --root="/path/to/dir02"

The path obtained using the flag has a higher prefrence, as such, the path used in this case will be "path/to/dir02"

The main aim for this project is to act as a wrapper over FFmpeg - allowing users to soft sub (even multiple) files at once, without having to trudge through pages of documentation to learn the basics of FFmpeg.

A large part of this functionality is already present inauto-sub, nevertheless, this section attempts to list out features thatmay be added in the future. Note that none of these features are intended to break/modify the existing functionality of auto-sub, rather add to what already exists, and simplify where possible.

List of possible improvements;

• Silent mode
• Interactive mode
• Config file (no gurantees)
• Force flag (overwrite existing files - if any)
• Custom naming for output files

Have a suggestion/feature that isn't listed here? Feel free tofile an issue :)

Custom forks of this project arenot supported. While anyone is free to fork the project, issues pertaining to custom forks will not be supported on this repository - essentially, once you fork the project, you are on your own.

While deploying a fork on Github, make sure to generate a Codecov token, and add it as a secret namedCODECOV_TOKEN to your forked repository.

Alternatively, you may remove Codecov action from.github/workflows/testing.yml file to disable Codecov reports for your fork.

Further Reading;

• Creating Github Secrets
• Generating Codecov Token

A list of resources, repositories, blogs, articles that I used while creating this project. Note that this isn't a comprehensive list by any measure,

• CLIG: A guide elaborating principles to design/develop command-line based applications
• Goland: Official documentation for Go
• FFmpeg Project: Duh!
• Cobra: The main framework used to design the CLI interface

Distributed under the MIT License. SeeLICENSE for details.