<commit_before>===========
 Meliman
===========

-------------------------------------------------------
 A tool for organizing and tagging your media library.
-------------------------------------------------------

    Currently unversioned.
    Meliman is distributed under the BSD license. See LICENSE.txt for more information.


Usage
=====

Managing TV series with Meliman is based on a "watched series" strategy: rather than 
guessing which series a file belongs to, a user first sets up a list of series which 
the program will then watch for.  Typically, operation of Meliman for TV series will 
look something like this::

    # ./meliman.py -s "The Simpsons"
    71663: The Simpsons
    79421: The Simpsons Shorts

    # ./meliman.py -w 71663
    Will now watch series 'The Simpsons'.

    # ./meliman.py -m simpsons_s4e7.avi
    isEpisode : true
    title : Marge Gets A Job
    time : 2008-12-17T10:19:47Z
    description: #7.  The Simpsons' house begins sinking ...
    
    # ./meliman.py -a
    71663: The Simpsons

Here, we first look up series matching the string "The Simpsons", then we tell 
Meliman to watch the series based on its id, then we feed a file to Meliman and 
have it generate metadata, and finally we list the series we are currently watching.  
Note that the -m option just prints the metadata, it doesn't tag the file.

Meliman also supports movies.  Here, because of practicality, we abandon the watch
strategy and do a lookup against IMDb.  Most operations against series are also 
available for movies by just capitalizing the option. Here is what operations for 
movies look like::

    # ./meliman.py -o "The Simpsons"
    96697: The Simpsons (1989)
    462538: The Simpsons Movie (2007)
    296852: The Simpsons (1991)
    1139628: The Simpsons Game (2007)
    ...

    # ./meliman.py -M "The Simpsons Movie (2007).avi"
    isEpisode : false
    title : The Simpsons Movie
    movieYear : 2007
    ...

    # ./meliman.py -F "The Simpsons Movie (2007).avi"
    The Simpsons Movie (2007) [462538].avi

Here, we first search for a movie using some text.  Notice that we get a lot of 
search hits here.  Because we aren't using a watching strategy, we need to be 
very specific with our search text and media file naming.  The best strategy (and
the one we use in the example) is to use the full name of the movie followed by
the year the movie was released in parenthesis.  That way, you can be sure that
meliman matches the exact movie you want.  The second command in this example
generates metadata for the media file and the third generates a library friendly
version of the media file's name.

Once you have started watching some TV series with Meliman, you can use Meliman to
watch an incoming directory and copy/move media files to your library directory, 
tagging the file with metadata in the process.  To make this work, you'll need to 
properly setup entries in your configuration file.  These settings, in particular, 
are important::

    input_path=/src/meliman/tmp/input
    movie_input_path=/src/meliman/tmp/movie_input
    tv_path=/src/meliman/tmp/tv
    movie_path=/src/meliman/tmp/movies
    recent_path=/src/meliman/tmp/recent

Once you are properly configured, you should be able to run meliman in "process mode," 
like this::

    # ./meliman.py -p
    Skipping file '/src/meliman/tmp/input/the_simpsons_s5e8.avi'.  
        A file for that episode already exists in the library.
    Adding file '/src/meliman/tmp/tv/The Simpsons/Season 05/the_simpsons-s05_e009.avi' 
        to the library.
    Removing file '/src/meliman/tmp/recent/2009-02-22_09-48-14_the_simpsons-s05_e008.avi' 
        from recent additions folder.

You can move/edit files in your library, but it may cause meliman to not understand
files it previously moved to the library.  As you can see from the output above,
Meliman tries to keep a neat library, not moving duplicate files to the library,
cleaning up the recent additions folder, etc.  Meliman simply skips files which 
don't match a watched series title or those files which don't match a real episode
of a given series.

More information about running Meliman can be found in the template configuration
file and using meliman's help option::

    # ./meliman.py --help

Features
========

Feature list:
    * Lookup series from thetvdb.com based on a search string
    * Lookup episodes from thetvdb.com based on a search string
    * Lookup movies from imdb.com based on a search string
    * Caches movies, series and episode data locally to prevent frequent network access
    * Generates cleaned-up file names for media files based on metadata
    * Generates metadata for media files
    * Manages a library directory structured by series name, seasons and episode numbers
    * Generates Genre folders for series and movies 
    * Watches an incoming directory for new media files and copies those files to 
      the library, properly tagging and naming those files
    * Maintains a list of recently added media files in the library

Planned improvements:
    * Arbitrary media file tagging (not using -p or the generate options)
    * Support more metadata formats (like mp4 file tagging for AppleTV)
    * Ability to run meliman as a server
    * A web-based GUI


Requirements 
============

    * Python 2.5 or greater (http://www.python.org)
        Python 3000 will almost surely *not* work.
    * imdbpy (http://imdbpy.sourceforge.net/)
        The easiest way to get imdbpy is probably through setup tools/easy_install.  
        Get setup tools here: http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
        Once you've installed easy_install, install imdbpy using: easy_install imdbpy
        You may need to run this with sudo or otherwise escalate your priviledges.
    * A unix-like OS
        While some effort was made to make meliman cross-platform, it has never
        been tested on Windows.  It should run fine on Linux and Mac OS X and
        has been tested on these systems.  Any help in ensuring meliman is truly
        cross platform would be appreciated.


Installation
============ 

First, put the Meliman folder wherever you like on your computer (referred to from
here on as INSTALL_PATH).

Next, create a db file for local caching::

    cd INSTALL_PATH; 
    python ./scripts/syncdb.py -t HEAD /path/to/new/or/existing/db/file

Now create a config file for the application::

    cp INSTALL_PATH/Meliman.conf.dist INSTALL_PATH/Meliman.conf

Finally, edit the config file to point to your db file and the various directories you 
want to use on your computer.  The example config file is well documented to help you 
make sensible settings.

Once you have installed the application, you can immediately use the meliman.py 
script to operate the program.  Execute the follwing for more information::

    INSTALL_PATH/meliman.py --help


<commit_msg>Made some formatting changes to the README.<commit_after>===========
 Meliman
===========

-------------------------------------------------------
 A tool for organizing and tagging your media library.
-------------------------------------------------------

    Currently unversioned.
    Meliman is distributed under the BSD license. See LICENSE.txt for more information.


Usage
=====

Managing TV series with Meliman is based on a "watched series" strategy: rather than 
guessing which series a file belongs to, a user first sets up a list of series which 
the program will then watch for.  Typically, operation of Meliman for TV series will 
look something like this::

    # ./meliman.py -s "The Simpsons"
    71663: The Simpsons
    79421: The Simpsons Shorts

    # ./meliman.py -w 71663
    Will now watch series 'The Simpsons'.

    # ./meliman.py -m simpsons_s4e7.avi
    isEpisode : true
    title : Marge Gets A Job
    time : 2008-12-17T10:19:47Z
    description: #7.  The Simpsons' house begins sinking ...
    
    # ./meliman.py -a
    71663: The Simpsons

Here, we first look up series matching the string "The Simpsons", then we tell 
Meliman to watch the series based on its id, then we feed a file to Meliman and 
have it generate metadata, and finally we list the series we are currently watching.  
Note that the -m option just prints the metadata, it doesn't tag the file.

Meliman also supports movies.  Here, because of practicality, we abandon the watch
strategy and do a lookup against IMDb.  Most operations against series are also 
available for movies by just capitalizing the option. Here is what operations for 
movies look like::

    # ./meliman.py -o "The Simpsons"
    96697: The Simpsons (1989)
    462538: The Simpsons Movie (2007)
    296852: The Simpsons (1991)
    1139628: The Simpsons Game (2007)
    ...

    # ./meliman.py -M "The Simpsons Movie (2007).avi"
    isEpisode : false
    title : The Simpsons Movie
    movieYear : 2007
    ...

    # ./meliman.py -F "The Simpsons Movie (2007).avi"
    The Simpsons Movie (2007) [462538].avi

Here, we first search for a movie using some text.  Notice that we get a lot of 
search hits here.  Because we aren't using a watching strategy, we need to be 
very specific with our search text and media file naming.  The best strategy (and
the one we use in the example) is to use the full name of the movie followed by
the year the movie was released in parenthesis.  That way, you can be sure that
meliman matches the exact movie you want.  The second command in this example
generates metadata for the media file and the third generates a library friendly
version of the media file's name.

Once you have started watching some TV series with Meliman, you can use Meliman to
watch an incoming directory and copy/move media files to your library directory, 
tagging the file with metadata in the process.  To make this work, you'll need to 
properly setup entries in your configuration file.  These settings, in particular, 
are important::

    input_path=/src/meliman/tmp/input
    movie_input_path=/src/meliman/tmp/movie_input
    tv_path=/src/meliman/tmp/tv
    movie_path=/src/meliman/tmp/movies
    recent_path=/src/meliman/tmp/recent

Once you are properly configured, you should be able to run meliman in "process mode," 
like this::

    # ./meliman.py -p
    Skipping file '/src/meliman/tmp/input/the_simpsons_s5e8.avi'.  
        A file for that episode already exists in the library.
    Adding file '/src/meliman/tmp/tv/The Simpsons/Season 05/the_simpsons-s05_e009.avi' 
        to the library.
    Removing file '/src/meliman/tmp/recent/2009-02-22_09-48-14_the_simpsons-s05_e008.avi' 
        from recent additions folder.

You can move/edit files in your library, but it may cause meliman to not understand
files it previously moved to the library.  As you can see from the output above,
Meliman tries to keep a neat library, not moving duplicate files to the library,
cleaning up the recent additions folder, etc.  Meliman simply skips files which 
don't match a watched series title or those files which don't match a real episode
of a given series.

More information about running Meliman can be found in the template configuration
file and using meliman's help option::

    # ./meliman.py --help

Features
========

Feature list:
    * Lookup series from thetvdb.com based on a search string
    * Lookup episodes from thetvdb.com based on a search string
    * Lookup movies from imdb.com based on a search string
    * Caches movies, series and episode data locally to prevent frequent network access
    * Generates cleaned-up file names for media files based on metadata
    * Generates metadata for media files
    * Manages a library directory structured by series name, seasons and episode numbers
    * Generates Genre folders for series and movies 
    * Watches an incoming directory for new media files and copies those files to 
      the library, properly tagging and naming those files
    * Maintains a list of recently added media files in the library

Planned improvements:
    * Arbitrary media file tagging (not using -p or the generate options)
    * Support more metadata formats (like mp4 file tagging for AppleTV)
    * Ability to run meliman as a server
    * A web-based GUI


Requirements 
============

* Python 2.5 or greater (http://www.python.org)
        Python 3000 will almost surely *not* work.
* imdbpy (http://imdbpy.sourceforge.net/)
        The easiest way to get imdbpy is probably through setup tools/easy_install.  
        Get setup tools here: http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
        Once you've installed easy_install, install imdbpy using: easy_install imdbpy
        You may need to run this with sudo or otherwise escalate your priviledges.
* A unix-like OS
        While some effort was made to make meliman cross-platform, it has never
        been tested on Windows.  It should run fine on Linux and Mac OS X and
        has been tested on these systems.  Any help in ensuring meliman is truly
        cross platform would be appreciated.


Installation
============ 

First, put the Meliman folder wherever you like on your computer (referred to from
here on as INSTALL_PATH).

Next, create a db file for local caching::

    cd INSTALL_PATH; 
    python ./scripts/syncdb.py -t HEAD /path/to/new/or/existing/db/file

Now create a config file for the application::

    cp INSTALL_PATH/Meliman.conf.dist INSTALL_PATH/Meliman.conf

Finally, edit the config file to point to your db file and the various directories you 
want to use on your computer.  The example config file is well documented to help you 
make sensible settings.

Once you have installed the application, you can immediately use the meliman.py 
script to operate the program.  Execute the follwing for more information::

    INSTALL_PATH/meliman.py --help



{'fraction_non_alphanumeric': 0.07621730963733564, 'fraction_numerical': 0.019361363964744978, 'mean_word_length': 3.097986974541149, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '699302', 'n_tokens_mistral': 4033, 'n_tokens_neox': 3710, 'n_words': 1856}