stos

stos is a cross-platform utility program to create Anki decks from your favorite TV shows and movies using their subtitles.

Internally stos uses ffmpeg, which means it supports pretty much any subtitle format and video/audio codec that you'd ever want.

This program is based on the well known subs2srs program. But sadly that program is written is C#, which is annoying to use outside of Windows, and also seems to be no longer maintained.

• Usage
  • General options
  • Examples without attached media
  • Examples with attached media
• Contributing

Usage

Usage and options

stos [OPTIONS] <SUBTITLE_FILE>... [-a | -i] [-m MEDIA_FILES...]

General options:

    -h, --help                    Print this help message and exit
    --version                     Print version and exit
    -v                            Increase verbosity of program logs
    -o FILE, --output=FILE        Specify the file to write the anki deck to [default: deck.apkg]
    -s INDEX, --sub-stream=INDEX  Select which stream to use from SUBTITLE_FILE as the subtitle stream
    --sub-lang=LANGUAGE           Select which stream to use form SUBTITLE_FILE as the subtitle stream by language
    --start TIMESTAMP             Specify from when the program should extract subtitles in hh:mm:ss format
    --end TIMESTAMP               Specify until when the program should extract subtitles in hh:mm:ss format
    --ignore-styled               Ignore subtitle texts that have been styled (only for ass format)
    --merge                       Merge nearby subtitles that are the same into one. See `--max-dist`
    --max-dist=MILLISECONDS       Used only with `--merge`. Will not merge subtitles that are more than MILLISECONDS apart [default: 250]
    -a, --audio                   Generate audio snippets for the anki cards
    --audio-stream=INDEX          Select which stream to use to generate the audio snippets
    --audio-lang=LANGUAGE  Select which stream to use to generate the audio snippets by language
    --pad-begin=MILLISECONDS      Pad the start time of each audio clip with MILLISECONDS amount
    --pad-end=MILLISECONDS        Pad the end time of each audio clip with MILLISECONDS amount
    --shift-audio=MILLISECONDS    Shift the audio timings by MILLISECONDS amount
    --join-audio                  Join overlapping audio into one clip
    -j JOBS, --jobs=JOBS          Specify amount of concurrent jobs stos will spawn [default: system logical core count]
    -i, --image                   Generate images for the anki cards
    --video-stream=INDEX          Select which stream to use to generate the images
    -m, --media                   Specify media files from which to generate the audio snippets `-a` and/or images `-i`
    --no-media                    Will not write media files specified by `-a` and/or `-i`
    -b, --blacklist               Do not include subtitles that match this regex (can be used multiple times)
    -w, --whitelist               Only include subtitles that match this regex (can be used multiple times)
    --no-deck                     Do not write an anki deck package
    --id=ID                       Specify the id to give the anki deck [default: random]
    --name=NAME                   Specify the name to give the anki deck [default: Stos Deck]
    --desc=DESC                   Specify the description to give the anki deck [default: A deck generated by stos]

Example without attached media

If you just want to generate anki cards with no audio/images, you can run stos as follows:

stos subtitle.srt

Or if you want to generate in bulk:

stos subtitle1.srt subtitle2.srt

stos is also able to extract subtitles that are embedded into containers (for example mp4 or mkv).

stos media_with_subtitle.mkv

stos will in this case select the first subtitle stream. You can select a specific subtitle stream using the --sub-stream or --sub-lang like this:

stos media_with_subtitle.mkv --sub-stream=1
stos media_with_subtitle.mkv --sub-lang=jpn

Example with attached media

Specifying the -a or --audio flag will extract audio clips and add them to the cards. Specifying the -i or --image flag will extract images and add them to the cards.

All files specified after the -m or --media flag are treated as multimedia files to extract audio/images from. stos will match the first subtitle file with the first multimedia file, the second subtitle file with the second multimedia file and so on:

stos subtitle1.srt subtitle2.srt -a -i -m multimedia1.mkv multimedia2.mkv

You don't have to specify -m or --media if the subtitles are embedded in the media container:

stos media_with_subtitle1.mkv media_with_subtitle2.mkv -a -i

Contributing

This project is pretty much just something to replace the non-working subs2srs on my linux system. So I've currently only implemented the things that I needed. If you're missing a feature, please make an issue for it and I'll see what I can do. Pull requests implementing the missing feature are also welcome!

Reporting a bug

Please submit a report issue over at the issue tab of the repo. Please include in it detailed steps of how to trigger the bug as well as information about your system, ffmpeg version and the used files if possible.