Installation

Visit the github releases page for binaries

Linux

For debian based systems supper is available as a debian package. The package will install supper and set up a systemd unit for ease of use. Download the debian package from the github releaes page and install with

dpkg -i supper-1.0.0.deb

Windows

Download the .tar.gz file from the github releaes page and extract the contents to a desired location. This could for example be:

C:/Users/<Username>/AppData/Local/Supper

Add the supper.exe executable to your path for ease of use

MacOS

Download the .tar.gz file from the github releases page and extract the contents to a desired location. This could for example be:

/usr/local/opt/supper

Add the supper executable to your path for ease of use

Configuration

Learn how to configure supper

You can specify the configuration of how supper function in a .yaml configuration file. The configuration file can be located in different places according to operating system and precendence. Here is an overview:

• Global configuration
  • Unix: /etc/supper/supper.yaml
  • Windows: %HOMEPATH%\AppData\Roaming\Supper\supper.yaml
• Local configuration
  • .supper.yaml found in current working directory

The local configuration has precendence over the global configuration. If supper is run with the --config argument, then that configuration file is used above all else.

Example

Below the default configuration for supper is shown. Most of the configuration is self-explanatory, however some details will be covered in the following sections.

# Supper configuration file

# Satisfy the following languages when downloading subtitles
languages:
  - en
  - es
  - de

# Path to store application logs
logfile: /var/log/supper/supper.log

# Download only hearing impaired subtitles
impared: false

# Bind web server to port
port: 5670

# Base path for reverse proxy
proxypath: "/"

# Movie collection configuration
movies:
  # Directory to store movie collection
  directory: /media/movies

  # Template to use for renaming movies
  template: >
    {{ .Movie }} ({{ .Year }})/
    {{ .Movie }} ({{ .Year }}) {{ .Quality }}

# TV show collection configuration
tvshows:
  # Directory to store TV shows
  directory: /media/tvshows

  # Template to use for renaming TV shows
  template: >
    {{ .TVShow }}/Season {{ .Season | pad }}/
    {{ .TVShow }} - S{{ .Season | pad }}E{{ .Episode | pad }} - {{ .Name }}

# Plugins are run after downloading a subtitle. The plugin is a simple shell
# command which is given the .srt file path in the SUBTITLE environment variable
plugins:
  # - name: my-plugin-name
  #   exec: echo $SUBTITLE

Templates

Templates are used to rename movie and TV series into folder/file names. The templating scheme uses the golang templating language and is highly customizable. You may define subfolders in your templating scheme using the path seperator /.

Movies

The following directives are available for movie templates:

Example:

{{ .Movie }} ({{ .Year }})/{{ .Movie }} ({{ .Year }}) {{ .Quality }}

TV shows

The following directovies are available for tv show templates:

Example:

{{ .TVShow }}/Season {{ .Season | pad }}/
{{ .TVShow }} - S{{ .Season | pad }}E{{ .Episode | pad }} - {{ .Name }}

Template Functions

You can utilize template functions to manipulate with the data in your templating schemes

pad

Pads the number with zeros to make up exactly two characters total. Useful for padding season and episode numbers.

Example

{{ .Season | pad }}

will output 01 for season one instead of just 1.

Subtitles

How to download subtitles with supper

You can download subtitles with supper for individual files of whole directories easily.

Flags

--lang|-l: Which language(s) subtitles will be downloaded in. Multiple languages can be specified using the flag multiple times. If no languages are specified those is the configuration file will be sued by default.

--modified|-m: Only download subtitles for media modified since the given duration. Durations are specified using numbers and letters (e.g. 2d12h30m)

--score|-s: Specifies a minimum score for any subtitle to be downloaded. If a subtitle is not available satisfying the minimum score, no subtitle will be downloaded. The score of a subtitle is determined by the likelyhood of the subtitle being synchronized to the media according to an internal scoring algorithm. Values are given in percent (withput the percent sign)

--imapired|-i: Only download hearing impaired subtitles. By default Supper will not consider or download hearing impaired subtitles. This flagg reverses this behaviour.

--limit|-l: Limit the number of media to process. A default values is applied as a safeguard agains accidental filepaths. Therefore this flag must be specified for large quantaties of media. Specifying a negative number will disable the limit.

To see all applicable flags see supper sub --help.

Languages:

Here is a list of the supported languages. The language tag specified in the table below can be used as an argument to the --lang|-l flag.

Examples:

Download subtitles for all media in the /media/movies folder in english, german and spanish for files added or modified within the last 24 hours:

supper sub -l en -l de -l es -m 24h /media/movies

Download english subtitles for the file tvshow.mp4 if a subtitle can be found with a score higher or equal to 75%:

supper sub -l en -s 75 tvshow.mp4

Download and overwrite existing english subtitles for all media in /media/tvshows

supper sub -l en --force /media/tvshows

Renaming

How to rename and organize media

You can organize and rename individual files or whole directories with supper

Flags

--action|-a: The action to perform when renaming media. Can be one of move, symlink, hardlink or copy. Default operation is to hardlink files

--extract|-x: Additionally extract media from archives (zip/rar).

--movies'-m: Only rename movies

--subtitles|-s: Only rename subtitles

--tvshows|-t: Only rename tv shows

To see all applicable flags see: supper ren --help

Examples

Rename all media in the /media/downloads folder using hardlink (default action):

supper ren /media/downloads

Rename only movies in the /media/downloads folder using copy:

supper ren --action copy --movies /media/downloads

Rename all media in the /media/downloads folder and extract media from archives (rar/zip):

supper ren --extract /media/downloads