GuessIt
*******

[image: Latest Version][image][image: LGPLv3 License][image][image:
Build Status][image][image: Coveralls][image]

GuessIt is a python library that extracts as much information as
possible from a video filename.

It has a very powerful matcher that allows to guess properties from a
video using its filename only. This matcher works with both movies and
tv shows episodes.

For example, GuessIt can do the following:

   $ guessit "Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi"
   For: Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi
   GuessIt found: {
       "title": "Treme",
       "season": 1,
       "episode": 3,
       "episode_title": "Right Place, Wrong Time",
       "source": "HDTV",
       "video_codec": "XviD",
       "release_group": "NoTV",
       "container": "avi",
       "mimetype": "video/x-msvideo",
       "type": "episode"
   }


Migration note
==============

In GuessIt 3, some properties and values were renamed in order to keep
consistency and to be more intuitive.

To migrate from guessit "2.x" to guessit "3.x", please read the
migration page. To migrate from guessit "0.x" or "1.x" to guessit
"2.x", please read the migration page.


Install
=======

Installing GuessIt is simple with pip:

   $ pip install guessit

You can also install from sources.


Usage
=====

GuessIt can be used from command line:

   $ guessit
   usage: guessit [-h] [-t TYPE] [-n] [-Y] [-D] [-L ALLOWED_LANGUAGES]
                  [-C ALLOWED_COUNTRIES] [-E] [-T EXPECTED_TITLE]
                  [-G EXPECTED_GROUP] [--includes INCLUDES]
                  [--excludes EXCLUDES] [-f INPUT_FILE] [-v]
                  [-P SHOW_PROPERTY] [-a] [-s] [-l] [-j] [-y] [-c CONFIG]
                  [--no-user-config] [--no-default-config] [-p] [-V]
                  [--version]
                  [filename [filename ...]]

   positional arguments:
     filename              Filename or release name to guess

   optional arguments:
     -h, --help            show this help message and exit

   Naming:
     -t TYPE, --type TYPE  The suggested file type: movie, episode. If undefined,
                           type will be guessed.
     -n, --name-only       Parse files as name only, considering "/" and "\" like
                           other separators.
     -Y, --date-year-first
                           If short date is found, consider the first digits as
                           the year.
     -D, --date-day-first  If short date is found, consider the second digits as
                           the day.
     -L ALLOWED_LANGUAGES, --allowed-languages ALLOWED_LANGUAGES
                           Allowed language (can be used multiple times)
     -C ALLOWED_COUNTRIES, --allowed-countries ALLOWED_COUNTRIES
                           Allowed country (can be used multiple times)
     -E, --episode-prefer-number
                           Guess "serie.213.avi" as the episode 213. Without this
                           option, it will be guessed as season 2, episode 13
     -T EXPECTED_TITLE, --expected-title EXPECTED_TITLE
                           Expected title to parse (can be used multiple times)
     -G EXPECTED_GROUP, --expected-group EXPECTED_GROUP
                           Expected release group (can be used multiple times)
     --includes INCLUDES   List of properties to be detected
     --excludes EXCLUDES   List of properties to be ignored

   Input:
     -f INPUT_FILE, --input-file INPUT_FILE
                           Read filenames from an input text file. File should
                           use UTF-8 charset.

   Output:
     -v, --verbose         Display debug output
     -P SHOW_PROPERTY, --show-property SHOW_PROPERTY
                           Display the value of a single property (title, series,
                           video_codec, year, ...)
     -a, --advanced        Display advanced information for filename guesses, as
                           json output
     -s, --single-value    Keep only first value found for each property
     -l, --enforce-list    Wrap each found value in a list even when property has
                           a single value
     -j, --json            Display information for filename guesses as json
                           output
     -y, --yaml            Display information for filename guesses as yaml
                           output

   Configuration:
     -c CONFIG, --config CONFIG
                           Filepath to configuration file. Configuration file
                           contains the same options as those from command line
                           options, but option names have "-" characters replaced
                           with "_". This configuration will be merged with
                           default and user configuration files.
     --no-user-config      Disable user configuration. If not defined, guessit
                           tries to read configuration files at
                           ~/.guessit/options.(json|yml|yaml) and
                           ~/.config/guessit/options.(json|yml|yaml)
     --no-default-config   Disable default configuration. This should be done
                           only if you are providing a full configuration through
                           user configuration or --config option.

   Information:
     -p, --properties      Display properties that can be guessed.
     -V, --values          Display property values that can be guessed.
     --version             Display the guessit version.

It can also be used as a python module:

   >>> from guessit import guessit
   >>> guessit('Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi')  
   MatchesDict([('title', 'Treme'), ('season', 1), ('episode', 3), ('episode_title', 'Right Place, Wrong Time'), ('source', 'HDTV'), ('video_codec', 'XviD'), ('release_group', 'NoTV'), ('container', 'avi'), ('mimetype', 'video/x-msvideo'), ('type', 'episode')])

"MatchesDict" is a dict that keeps matches ordering.

Command line options can be given as dict or string to the second
argument.


Configuration
=============

Find more about Guessit configuration at configuration page.


REST API
========

A REST API will be available soon ...

Sources are available in a dedicated guessit-rest repository.


Support
=======

This project is hosted on GitHub. Feel free to open an issue if you
think you have found a bug or something is missing in guessit.

GuessIt relies on Rebulk project for pattern and rules registration.


License
=======

GuessIt is licensed under the LGPLv3 license.
