mercredi 1 février 2012

lm (list movies) EN

lm: list movies, a command-line tool

lm: list movies, a command-line tool

*lm* is a command-line tool which lists movies, loosely inspired from ls. Extra features allow you to download subtitles, and interact with the opensubtitles hash database. *lm* is not english oriented, and is able to provide information for all movie files.

lien vers la version Française

DOWNLOAD LM

1 Introduction

1.1 History

The starting point of this little project is here at Goffi’s website. His idea was to build a command-line tool to list/filter/sort movies in current directory, using IMDbPy package to get all metadata information. When I saw the script, few months ago, I just made some modifications I though useful like displaying results in an html page with links to trailers, etc... Little by little, I realized it was a great tool to keep track of files without too much effort.

 

1.2 Brief features overview

Here is a short list of what you can do with *lm*:
  • list all movie files in current directory (recursive search) in your terminal
    • filter by genre, actor, country, file size
    • sort by name, rating
  • export this list to an html view
    • with cover
    • link to trailers and IMDb page
  • download subtitles in any languages (source opensubtitles.org)

 

1.3 Underlying tools

*lm* uses Opensubtitles API through XMLRPC protocol (default python’s module xmlrpclib)  to match movie file hash with their database. If a movie file hash is not know by Opensubtitles, you can send them the information with *lm*, and then participate to this collaborative referencing.
IMDb provides all metadata information (genre, actors, outline, etc...), and is called through imdbpy package.

 

2 Installation

 

IMDbPy (required)

Check the very complete official download page, you will probably see that it’s available in the package repository of your distribution. Some (un)official installers are built for Mac Os X and Windows.
IMDbPY requires *lxml* module to speed up parsing. If it’s not installed, make sure to have BeautifulSoup instead.
Note: If you’d like to install it from sources, you may just stick to the minimal configuration.

 

colorama (optional, for windows users only)

*lm* is mainly designed to return results on a terminal, like *ls* function. To ’map’ terminal coloration on the windows terminal, please install this package.

 

3 Features in details

Let’s suppose we are in a folder with following files:

/films/
    Cinema Paradiso/
        1988.Cinema.Paradiso.mkv
    ATB/
        Attack.the.Block.avi
    dogville/
        DOGVILLE-2003.mkv
        trailer.avi

 

3.1 Options

 

Basic call

xx@xx/films$ ./lm.py  
Attack the Block (Attack.the.Block.avi) 
Dogville (DOGVILLE-2003.mkv) 
Nuovo Cinema Paradiso (1988.Cinema.Paradiso.mkv)

Lists all files in dir and sub dirs, sorted by name with minimal description displayed.

 

Longer description (-l)

xx@xx/films$ ./lm.py -l 
Attack the Block (2011,6.8,4475Mo) [Comedy, Horror, Sci-Fi] 
from Joe Cornish: Attack.the.Block.avi 
Dogville (2003,8.0,3640Mo) [Drama, Mystery, Thriller] from
Lars von Trier: DOGVILLE-2003.mkv 
Nuovo Cinema Paradiso (1988,8.5,8137Mo) [Drama] from Giuseppe Tornatore: 1988.Cinema.Paradiso.mkv  
Displays year, imdb rating, file size, genres and directors.

 

Outline (-o)

[+/-] show/hide this output

>xx@xx/films$ ./lm.py -o
Attack the Block (Attack.the.Block.avi) 
*** A teen gang in South London defend their block from an 
alien invasion. 
Dogville (DOGVILLE-2003.mkv) 
*** A woman on the run from the mob is reluctantly accepted in a small Colorado town. In exchange, 
she agrees to work for them. As a search visits town, she 
finds out that their support has a price. Yet her dangerous
secret is never far away... 
Nuovo Cinema Paradiso (1988.Cinema.Paradiso.mkv) 
*** A filmmaker recalls his childhood, when he fell in love 
with the movies at his village’s theater and formed a deep 
friendship with the theater’s projectionist.

 

Longest description (-L)

xx@xx/films$ ./lm.py -L
Try it! Actors, and long outline are displayed.

 

Open result in an html page (-S)

xx@xx/films$ ./lm.py -S
Attack the Block
Comedy, Horror
note: 6.8, votes: 26.0K
size: 4475Mo

ATB-ATTACK-THE-BLOCK
Dogville
Drama, Mystery
note: 8.0, votes: 59.0K
size: 3640Mo

DOGVILLE-2003.mkv
Nuovo Cinema Paradiso
Drama
note: 8.5, votes: 62.0K
size: 8137Mo

1988.Cinema.Paradiso.mkv

This view has direct links to movie trailers (click on covers) and IMDb movie pages (click on title).

 

Open IMDb page (-s)

xx@xx/films$ ./lm.py -s
Will open IMDb pages, pointing on every selected movies. Be careful and don’t use this parameter when too many movie files are selected.

 

Filter files (-f @xx:yy)

You can filter movies with the following syntax: “@keyword:filter,filter,filter@keyword2:filter,filter”. Filter is case insensitive.
xx@xx/films$ ./lm.py -f @genre:drama
...
xx@xx/films$ ./lm.py -f @genre:drama@size:+2000
...
You can filter by genre, country, actors, size (@size:+900 or @size:-400), and by identification confidence (@unsure). Check color interpretation part of this page.

 

3.2 Color interpretation

When displayed in your terminal, titles can have different colors.

MAGENTA

The best! It means that your movie hash matches an Opensubtitles known movie. 95% sure to display the right title.

ORANGE

Not bad. We did’nt find any matches in Opensubtitles, but we looked through IMDb, and are quite confident. 80% chance to display the right title.

ORANGE with /|\ symbols:

We didn’t find anything on Opensubtitles, and we didn’t find any good matches in IMDb results either. We strongly recommend you to manually confirm this movie with the shell interactive command: lm.py YOUR_DIR -f @unsure --confirm.

 

3.3 Actions

 

Download subtitles (--donwload language)

xx@xx/films$ ./lm.py --download eng
Looks for subtitles on Opensubtitles database. By order of preference, *lm* chooses first: perfect file hash match, and if nothing is found, it looks for most downloaded subtitles linked to this imdb id. Subtitles files are downloaded into every movie file directory with the syntax “MOVIEFILENAME_ENG_LM1.srt” (replace ENG with chosen language). Up to 3 subtitles are donwloaded per movie.
limit: Opensubtitles limits downloads to 200 per day, please take this into consideration and don’t overload them!
language: please provide a ISO639 code as described HERE. eng/fre/ger are some examples.
503 Service Unavailable: Sometimes, Opensubtitles server is unreachable. Try again a few minutes/hours later.

 

Manually search/confirm movie (--confirm)

This command will take you through a confirmation process. You may have to provide other information to accurately identify the movies (imdb id, title or year).
[+/-] afficher/cacher cette procédure

>xx@xx/films$ ./lm.py--confirm

*************** File to confirm *************** 
absolute path : ~/films/dogville/DOGVILLE-2003.mkv 
basename : DOGVILLE-2003.mkv

Dogville (2003,8.0,3640Mo) [Drama, Mystery, Thriller] 
from Lars von Trier: DOGVILLE-2003.mkv 

Do you confirm stored info? (y/n):n 
Will you provide an IMDb id? (y/n):n 
please enter movie title: dogville 
please enter year, leave blank if unknown: 2003 

ratio <0.7 & year, we retry on base results 
ratio ==> dogville (for [dogville]) 1.000000 
--> movie found title: Dogville 
--> movie found year: 2003 
Confirm this result? (y/n):y 
movie saved

 

Upload movie hash and imdb id to Opensubtitles (--upload)

Selects all movies whose hash was not found on Opensubtitles but whose title was found on IMDb, and send (hash, imdb id) couple to Opensubtitles database. You will be asked to confirm before processing.

 

Delete files from cache (-d)

Delete selected movies from cache. You will be asked to confirm before processing. To delete all cache call: "./lm.py cache -d"

 

Reset cache (--reset)

Delete every cache file (stored in ~/.lm/ directory). You will be asked to confirm before processing.

 

4 Miscellaneous

 

IMDb downloads are long

Advice: Each time you launch *lm*, it gets metadata for files it doesn’t know, which is really slow. So, make sure to test it on a directory with a few movies.

 

Mechanisms

 

Hidden files

Basically, all metadata (text data, not pictures) are stored with cPickle in the hidden directory ~/.lm/.

 

Movie search

Here are the imdb searching steps:
  1. Build hash for file 
  2. Call Opensubtitles through XMLRPC protocol.
  3. Do they know this hash? If yes => perfect, we get an imdb_id and exit
  4. Otherwise, try to guess movie title/year from the filename (omit some stop words and look for a potential year in the movie filename)
  5. Send guessed title to IMDB, get the list of results
  6. If we guessed a year (at step 4), limit results to movies released this year
  7. Find the best match on all results, for ALL AKAS (non original titles)
  8. If the best match isn’t good enough, and if we filtered results at step 6, GOTO 7 with non-filtered imdb results.
Note: *lm* is not english oriented at all. Example "sexcrimes.avi" will match "wild things" its original title.

lm (list movies) FR

lm: list movies, a command-line tool

lm: list movies, un outil en ligne de commande

*lm* est un outil en ligne de commande (à la manière de ls?) permettant de lister les films présents dans le répertoire. Mais il permet aussi de télécharger les sous-titres correspondants et d’interagir avec la base de films d'Opensubtitles. A noter: *lm* ne se limite pas aux fichiers à titres anglais.

for English version click here

TELECHARGER LM

1 Introduction

 

1.1 Histoire

Le point de départ de ce modeste projet se trouve ICI sur le site de Goffi. Son idée était de construire un outil en ligne de commande qui servirait à lister/filter/trier les films du répertoire en utilisant le package IMDbPy pour récupérer toutes les métadonnées. Quand j'ai découvert ce script, il y a quelques mois, j'y ai juste apporté quelques modifications qui semblaient utiles, comme l'affichage du résultat dans une page html avec des liens vers les bandes annonces, etc... Et petit à petit, j'ai réalisé que *lm* était un outil fort pratique pour garder la trace de ses films.

 

1.2 Petit tour rapide des fonctionnalités

Voici une liste des utilisations principales de *lm*:
  • lister les films d'un répertoire (recherche récursive) dans son terminal
    • filtrer par genre, acteurs, pays, taille de fichier
    • trier par nom ou par note IMDb
  • exporter ces résultat dans une page html avec:
    • les affiches des films
    • des liens vers les bandes annonces et les pages imdb
  • télécharger les sous-titres dans n'importe quelle langue (source Opensubtitles.org)

 

1.3 Les outils utilisés

*lm* utilise l'API d'Opensubtitles via le protocole XMLRPC (module python de la librairie standard: xmlrpclib) pour déterminer l'id IMDb du film à partir du hash du fichier. Si le film n'y est pas connu, *lm* pourra par la suite envoyer ces informations à Opensubtitles et ainsi participer à étoffer cette base de films.
IMDb fournit toutes les métadonnées des films. La base est interrogée grâce au module imdbpy.

 

2 Installation

 

IMDbPy (requis)

Faites un tour sur la page de téléchargement très complete. Vous y verrez sûrement que ce package est disponible sur le repo de votre distribution. Sinon, quelques installeurs (non)officiels sont disponibles pour  Mac Os X et Windows.
IMDbPY requiert le module *lxml* module pour accélérer le parsing. Si vous ne pouvez pas l'installer, assurez vous d'avoir BeautifulSoup à la place.
Note: Si vous souhaitez installer le package depuis les sources, vous pouvez vous contentez de la configuration minimale.

colorama (optionnel, pour les utilisateurs windows seulement)

*lm* est principalement déstiné à afficher ses résultats dans le terminal. Pour colorer le "terminal" windows , installez ce package.

 

3 lm en détails

Supposons l'arborescence de répertoires/fichiers suivante:

/films/
    Cinema Paradiso/
        1988.Cinema.Paradiso.mkv
    ATB/
        Attack.the.Block.avi
    dogville/
        DOGVILLE-2003.mkv
        trailer.avi

 

3.1 Options

 

Appel simple

xx@xx/films$ ./lm.py  
Attack the Block (Attack.the.Block.avi) 
Dogville (DOGVILLE-2003.mkv) 
Nuovo Cinema Paradiso (1988.Cinema.Paradiso.mkv)

Liste tous les films des répertoires et sous répertoires, triés par noms, avec un minimum d'informations affichées.

 

Description plus longue (-l)

xx@xx/films$ ./lm.py -l 
Attack the Block (2011,6.8,4475Mo) [Comedy, Horror, Sci-Fi] 
from Joe Cornish: Attack.the.Block.avi 
Dogville (2003,8.0,3640Mo) [Drama, Mystery, Thriller] from 
Lars von Trier: DOGVILLE-2003.mkv 
Nuovo Cinema Paradiso (1988,8.5,8137Mo) [Drama] from 
Giuseppe Tornatore: 1988.Cinema.Paradiso.mkv

Affiche l'année, la note, la taille du fichier, le genre du film ainsi que le réalisateur. 

 

Outline (-o)

[+/-] afficher/cacher le résultat

>xx@xx/films$ ./lm.py -o
Attack the Block (Attack.the.Block.avi) 
*** A teen gang in South London defend their block from an 
alien invasion. 
Dogville (DOGVILLE-2003.mkv) 
*** A woman on the run from the mob is reluctantly accepted in a small Colorado town. In exchange, 
she agrees to work for them. As a search visits town, she 
finds out that their support has a price. Yet her dangerous
secret is never far away... 
Nuovo Cinema Paradiso (1988.Cinema.Paradiso.mkv) 
*** A filmmaker recalls his childhood, when he fell in love 
with the movies at his village’s theater and formed a deep 
friendship with the theater’s projectionist.

 

La plus longue description (-L)

xx@xx/films$ ./lm.py -L
Essayez! Les acteurs, ainsi qu'un résumé détaillé sont affichés.

 

Afficher les résultats dans une page html (-S)

xx@xx/films$ ./lm.py -S
Attack the Block
Comedy, Horror
note: 6.8, votes: 26.0K
size: 4475Mo

ATB-ATTACK-THE-BLOCK
Dogville
Drama, Mystery
note: 8.0, votes: 59.0K
size: 3640Mo

DOGVILLE-2003.mkv
Nuovo Cinema Paradiso
Drama
note: 8.5, votes: 62.0K
size: 8137Mo

1988.Cinema.Paradiso.mkv


Cette vue à des liens vers les bandes annonces (cliquez sur l'affiche) et les pages imdb (cliquez sur les titres des films).

 

Ouvrir la page imdb (-s)



Ouvre directement les pages IMDb des films sélectionnés. Soyez prudents, et n'utilisez pas ce paramètre si trop d'éléments risquent d'être affichés.

 

Filtrer les films (-f @xx:yy)

Syntaxe: “@keyword:filter,filter,filter@keyword2:filter,filter” (n'est pas sensible à la casse).
xx@xx/films$ ./lm.py -f @genre:drama
...
xx@xx/films$ ./lm.py -f @genre:drama@size:+2000
...
Vous pouvez filtrer par genre, acteurs, parys, taille de fichier (ex: @size:+900 ou @size:-400), mais aussi par pertinence de la reconnaissance du titre (@unsure). Lisez la partie suivante sur les couleurs utilisées pour en savoir plus sur les erreurs d'identification.

 

3.2 Interprétation des couleurs affichées

Quand les films s'affichent dans le terminal, les titres peuvent prendre plusieurs couleurs.

 

MAGENTA

Le top! Le hash du film a été trouvé dans la base Opensubtitles. 95% de chances de pointer le bon titre.

 

ORANGE

Pas si mal. *lm* n'a pas trouvé le hash du fichier, mais la recherche directe sur IMDb a donné un bon résultat, *lm* est assez confiant. 80% de chance d'afficher le bon titre.

 

ORANGE avec des symboles /|\ :

Aïe! Le hash n'a rien donné sur Opensubtitles, et la recherche directe par IMDb n'a pas donné de résultat satisfaisant non plus. Il y a des chances que le titre indiqué ne soit pas bon. Il est conseillé de lancer une confirmation manuelle de l'ensemble de ces titres avec la commande "lm.py YOUR_DIR -f @unsure --confirm".

 

3.3 Actions

 

Télécharger les sous-titres (--donwload language)

xx@xx/films$ ./lm.py --download eng
Recherche les sous-titres sur la base Opensubtitles. Par ordre de préférence seront téléchargés, les sous-titres pointant vers les hashs exacts des fichiers détenus, puis les sous-titres les plus téléchargés parmi ceux associés aux bons id IMDb. Les sous-titres sont téléchargés dans les répertoires de chaque film avec la syntaxe “MOVIEFILENAME_ENG_LM1.srt” (replacer ENG par la langue choisie). Au plus 3 sous-titres seront téléchargés par film.
limite: Opensubtitles limite à 200 téléchargements par jour. Merci de prendre cette limite en considération et d'éviter de saturer leur serveur!
langue: Fournir un code ISO639 comme décrit ICI. eng/fre/ger en sont des exemples.
503 Service Unavailable: Il arrive parfois que le serveur Opensubtitles soit saturé. Ré-essayez quelques minutes/heures plus tard.

 

Recherche/confirmation manuelle (--confirm)

Cette commande lance une procédure qui vous accompagne dans la recherche ou confirmation des films sélectionnés. Si le titre associé ne vous correspond pas, vous pourrez fournir des information supplémentaires pour l'identifier (titre, année, IMDb id).
[+/-] afficher/cacher cette procédure

>xx@xx/films$ ./lm.py--confirm

*************** File to confirm *************** 
absolute path : ~/films/dogville/DOGVILLE-2003.mkv 
basename : DOGVILLE-2003.mkv

Dogville (2003,8.0,3640Mo) [Drama, Mystery, Thriller] 
from Lars von Trier: DOGVILLE-2003.mkv 

Do you confirm stored info? (y/n):n 
Will you provide an IMDb id? (y/n):n 
please enter movie title: dogville 
please enter year, leave blank if unknown: 2003 

ratio <0.7 & year, we retry on base results 
ratio ==> dogville (for [dogville]) 1.000000 
--> movie found title: Dogville 
--> movie found year: 2003 
Confirm this result? (y/n):y 
movie saved

 

Uploader la paire (hash, id) à Opensubtitles (--upload)

Sélectionne les films dont les hashs n'ont pas été trouvés sur Opensubtitles pour lesquels la recherche sur IMDb à fourni de bons résultats, et envoie la correspondance hash -> imdb_id à la base Opensubtitles. Une confirmation vous sera demandée avant tout effet.

 

Supprimer des fichiers du cache (-d)

Supprime du cache les fichiers sélectionnés. Une confirmation vous sera demandée avant tout effet. Pour supprimer tous les fichiers du cache "./lm.py cache -d"

 

Remettre le cache à zéro (--reset)

Supprime directement tous les fichiers de cache stockés dans le répertoire ~/.lm.  Une confirmation vous sera demandée avant tout effet.

 

Divers

 

Les appels à IMDb sont longs

Conseil: quand *lm* est appelé sur des fichiers qu'il ne connaît pas, il requête IMDb pour tous les fichiers inconnus, et c'est ... lent. Pour tester le script, assurez vous de pointer un répertoire ne contenant que quelques films.

 

Fichiers cachés

Tout est stocké dans le répertoire ~/.lm/.

 

Recherche de l'id IMDb

Voici les principales étapes:
  1. Construire le hash du film 
  2. Questionner Opensubtitles via leur api XMLRPC.
  3. Reconnaît-il ce hash? Si oui => parfait, travail terminé, exit!
  4. Sinon, on essaye de deviner le titre et l'année de sortie du film à partir du nom du fichier (mots interdit, regexp, ...)
  5. On questionne IMDb pour le titre deviné. On récupère les résultats
  6. Si nous pensions avoir détecter une année de sortie, les résultats sont filtrés pour ne conserver que les films de l'année en question.
  7. Recherche de la meilleure correspondance entre les titres (devinés et résultats), sur les titres du films dans tous les pays disponibles
  8. Si le meilleur résultat n'est pas satisfaisant, et si nous avions deviné une année à l'étape 6, on repasse à 7 avec les résultats initiaux (non filtrés) d'IMDb.