[![GitHub Issues](]( [![npm version](]( [![dependencies

Usage no npm install needed!

<script type="module">
  import mediaOrganize from '';



GitHub Issues npm version dependencies devDependencies license

A CLI utility for organizing your media collections via symbolic links.

✅ Auto-detect 📺 Series, 🐙 Anime and 🎬 Movies
✅ No dependencies on external web services!
✅ Extract Season/Episode Numbers
✅ File Watcher 👀 links new files
✅ Unlinks ❌ deleted files
✅ Customizable Naming Format
✅ Powerful Nunjucks Templating
✅ Multiple Directory Support
✅ Logging & File Rotation

This plugin will never move or delete your media files, because that's your (or your torrent client's) job!



  • NodeJS 12+

Install from NPM

npm i -g media-organize

Install from Source

git clone
cd media-organize
npm install -g .



run media organization

  orgMedia run    run media organization                               [default]
  orgMedia watch  start media watchers                              [aliases: w]

      --help     Show help                                             [boolean]
      --version  Show version number                                   [boolean]
  -d, --data     app data directory            [string] [default: "~/.orgMedia"]
  -l, --log      enable logging to data directory      [boolean] [default: true]
  -q, --quiet    hide console log output              [boolean] [default: false]

Automatic Methods

CRON (Regular Runs)

Watcher/Screen (creates a screen named media_watcher watching your media)
screen -S media_watcher -dm orgMedia watch


Config file is config.json and has the following mandatory properties:

Option Purpose Example
directories Array of directories to scan ["../series"]
targetPath Target directory for sorted files ../sorted
targetFormat Naming format of the output links See below for details

And the following non-mandatory options:

Option Default Purpose
enabled true
allowedExtensions * Array Extension to allow, (empty or omitted for all)
ignoredExtensions None Array Extensions to ignore
linkSubtitles false Should subtitle files be copied alongside media files?
subtitleExtensions None Extensions to link with media
useHighestQuality false Should a higher-quality release replace a lower one?
strictType None Whether this config block should only accept movies or series
allowedSize None Array Minimum and Maximum (if required) file sizes, in MB. [50, 5000]

You can also specify an array of config objects if you have different file types/directories to scan.

See config.example.json for further example configurations.

targetFormat usable variables

This is a list of the basic metadata that should be available on each media item.

Variable Value Example
{{name}} Series/Show/Movie Name Name
{{season}} Season Integer 10
{{episode}} Episode Integer 34
{{year}} Year Integer 2021
{{extension}} File Extension .mkv
{{classifier}} [Meta] The classifier used to detect the media type.

caseFormat filter

This filter will automatically use the Case library to format a string.

{{ name | caseFormat('capital') }}

{{ 'foo_v_bar' | caseFormat('capital') }} -> 'Foo V Bar'

appendYear filter

This filter will automatically append the year (in brackets) at the end of the given string.

Note: Always use appendYear after caseFormat (or other filters that modify the title) so that you don't modify the year.

{{ name | appendYear }}

{{ 'name' | appendYear }} -> 'name (2021)'

normal filter

This filter will automatically strip non-filename-safe characters.

Specifically: ``#%&{}/<>^*?$!'":+|@=`