Publish your own packages to the world's most popular software ecosystem with npm Pro.Get started »


2.0.1 • Public • Published

mediascan Build Status codecov Dependency Status License: MIT semantic-release Greenkeeper badge Join the chat at

A scanner for media files that follows a user-provided naming convention

What to do with this library ?

A lot of things :

Don't hesitate to suggest new features : it is always worthy :)


Which naming convention can I use with this lib ?

ANYTHING. All You have to do is to implement a parser function : A function that takes a single string argument fullPathFile (the full path to the file) that returns an object that minimal contains a title string property. For example :

const ptt = require("parse-torrent-title");
const information = ptt.parse("Game.of.Thrones.S01E01.720p.HDTV.x264-CTU");
console.log(information.title);      // Game of Thrones
console.log(information.season);     // 1
console.log(information.episode);    // 1
console.log(information.resolution); // 720p
console.log(information.codec);      // x264
console.log(information.source);     // HDTV
console.log(;      // CTU

This lib was tested with these parsers that follows torrent naming conventions (see their readme for more info) :

How the library detects the category of a media file ?

The default implementation determines it is a tv-show if there is season and episode attributes can be found in the information provided by the parser. Here is a example if you want to implement one :

// Default implementation to know which category is this file
function defaultWhichCategoryFunction(object : MediaScanLib.TPN) : MediaScanLib.Category{
    // workaround : const string enum aren't compiled correctly with Babel
    return (checkProperties(object, ['season', 'episode']))
        ? 'TV_SERIES' as MediaScanLib.Category.TV_SERIES_TYPE : 'MOVIES' as MediaScanLib.Category.MOVIES_TYPE;

Using custom parameters in the lib

Check the constructor for more detail - an illustration :

const MediaScan = require("mediascan");
let libInstance = new MediaScan({
    defaultPath = process.cwd(), // Default path to explore , if paths is empty
    paths = [], // all the paths that will be explored
    allFilesWithCategory = new Map(), // the mapping between file and Category
    movies = new Set(), // Set<ParserResult> (all the movies)
    series = new Map(), // <tvShowName , Set<ParserResult>> (all the tv-series episodes)
}, {
    parser = nameParser, // the explained parser
    whichCategory = defaultWhichCategoryFunction, // the previously explained detection function


For npm users :

$ npm install --save mediascan

for Yarn :

$ yarn add mediascan


npm test

Types definitions

If You want, You can have the types definitions used in this lib :

npm install @types/mediascan


  • If you're unsure if a feature would make a good addition, you can always create an issue first.
  • We aim for 100% test coverage. Please write tests for any new functionality or changes.
  • Any API changes should be fully documented.
  • Make sure your code meets our linting standards. Run npm run lint to check your code.
  • Be mindful of others when making suggestions and/or code reviewing.


npm i mediascan

DownloadsWeekly Downloads






Unpacked Size

168 kB

Total Files


Last publish


  • avatar