aviManager - Manual

0.9rc2

Copyright Notice

     This manual is licensed under the terms of the GNU FDL (Free
     Documentation License).  It has been written in the hope that it will
     be useful to the community but it comes with no warranty; use it at
     your own risk.

     /doc/README - TEXT VERSION, /doc/html/index.html - HTML VERSION

Introduction 1.1. Copyright 1.2. About the Script 1.3. System Requirements 1.4. Warnings 1.5. Known Bugs & Limitations 1.6. About Versions
Installation
Customizing
Problems
Hints 5.1. Searching 5.2. Voting 5.3. Find Movie 5.4. Add Movie 5.5. Burning Movies to CDROM/DVD 5.6. Different formats for movie lists 5.7. Update Votes 5.8. Playing movies in browser
Importing Data
FAQ
Revision History
Credits

1. Introduction

1.1. Copyright

     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or (at
     your option) any later version.

     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
     USA.

     Send bug-reports, comments to <mriester@gmx.de>

     Icons are taken from KDE (http://www.kde.org) and GNOME
     (http://www.gnome.org).

     Bar (and code for displaying it) is taken from Web-APP
     (http://www.web-app.org/cgi-bin/index.cgi)

     Default theme for the 0.9pre-series is taken from plone
     (http://www.plone.org)

1.2. About the Script

     This script helps you to manage your (large) movie (DVD,DivX)
     collection.  It ships with an intelligent voting system for many
     users.  aviManager attempts to find the best movie to watch.  You will
     be surprised how good it works.  There is also a nice imdb grabber for
     fast movie adding.

     Main features (if you find a free movie database with more features,
     let me know ;-) ):

        * IMDb Grabber (including DVD-Cover, plot, ...)

        * Search IMDb Database and add movies with one click

        * Voting System: user can vote movies, add movie to a wishlist (-4
          = I don't wanna see this movie, 5 = I want to see this movie very
          soon) and can say how often he has seen the movie.

        * Great search (optional fuzzy search for typos, Regular
          Expressions) and ranking possibilites

        * low system requirements (you don't have to setup something like
          MySQL-which is great, but not necessary for a small database like
          this).

        * subtitle upload

        * different owners

        * export moviedatabase to readerfriendly format (templates
          available for HTML,LateX,Ascii)

        * statistics

        * Multilanguage support (English, Danish, French, German, Greek,
          Hungarian, Polish, Swedish, Spanish, Russian and Norwegian
          available)

        * single user mode: for people who don't want this voting stuff for
          many users and who just need a little movie database.  You can
          safely switch between modes, if you find friends who are willing
          to vote.

        * users can add comments to every movie

        * last seen list

        * lent list: set status to lent and aviManager will remind you who
          borrowed which movie

        * Movie of the moment (or minute, hour, day, ...)

        * Requests: Put movies you want to have on this list

1.3. System Requirements

A working copy of Perl 5 (tested with 5.6.1 and 5.8).
A basic understanding of both Perl and CGI.

     This program has been tested on the following plattforms: Linux 2.4
     under Debian Woody and Red Hat 7.x, NetBSD 1.6.  Linux 2.6 under
     Debian Sarge, Mac OSX and Windows There are known Problems with Red
     Hat 8 (you have to downgrade to Apache 1.x or try to change in
     aviman.pl, first line "!/usr/bin/perl -w" to "!/usr/bin/perl -X")
     and Solaris (turn off file locking).

1.4. Warnings

     aviManager needs a lot of CPU time.  It is very comfortable and
     generates everything on the fly.  This could be a problem if you don't
     have your own webserver.  IT IS POSSIBLE THAT YOUR WEBHOSTER DOES NOT
     LIKE AVIMANAGER AND WILL FORCE YOU TO REMOVE AVIMANAGER OR EVEN CLOSES
     YOUR ACCOUNT.  READ GPL.  USE AVIMANAGER AT YOUR OWN RISK.  YOU HAVE
     BEEN WARNED.  SEE WARNING BELOW FOR ANOTHER GOOD REASON NOT TO PUT
     AVIMANAGER ON A PUBLIC SERVER!

     It is not legal to use the IMDb grabber.  See
     http://www.imdb.com/help/show_leaf?usedatasoftware for details.  The
     IMDb grabber in aviManager is only an example implementation.  Use
     this as a template for websites where this way of information
     gathering is legal.  We are working on getting the IMDb data out of
     their flat files, which would be 100% legal for personal AND
     non-commercial usage.  DON'T PROVIDE ANY IMDB DATA TO THE PUBLIC.

1.5. Known Bugs & Limitations

     There is one nasty bug in the actors index.  Links to actors will
     sometimes not return all actors.  Maybe this is fixed in pre6?

     There are a few limitations:

        * You cannot add duplicates (if you have different versions of this
          movie).  If you need this feature, use the comment-field until
          this is possible.

        * You cannot add non imdb-movies.  If you have some, use Add movie
          offline and a fake IMDB ID until this is possible

        * You cannot set user permissions for different features (for
          example add movies, but delete/change only his, ...).  No good
          solution at the moment.  Trust your friends or give them only an
          [VIP] account.

     These limitations will be fixed for 1.0 (hopefully mid of 2005).
     Please check development of Aviman:Core for details.

1.6. About Versions

     Versions 0.x.x are always well tested and contain no known bugs.
     Other versions are developer versions (CVS-snapshots) that seem to be
     stable on our machines but contain new (not thoroughly tested)
     features.

2. Installation

     Please open the file UPGRADE instead if you upgrade from a previous
     version of aviManager!.  Mac OSX Users should read Edwin's README.OSX
     instead (I don't know if this is true for the 0.9pre-series)!

     WARNING The install script is only tested on a few machines!

     WARNING 2: Most work at the moment is done in the Perl modules
     Aviman::Core.  There will be only critical bugfix releases until the
     modules are finished (mid 2005).

     Version 0.9pre9 comes with an install script.  You can use this if you
     install aviman on your local machine or if you have ssh access to your
     server (once again, don't install aviManager on a public server!).

     Run the script with

     perl install.pl

     The script tries to guess your system.  If everything looks ok, start
     installation with

     perl install.pl -i

     If not, specify the paths and the apache user with the corresponding
     command line arguments (see output of the script).

     For people who can't use the installer, here the detailed installation
     instructions.  Steps marked with [X] are necessary even with the
     installer (AFTER you run the script).

     1.   [X] Make sure that you have installed Apache, Perl and following
          Perl Modules: LWP Module, CGI:Session, HTML::Template and
          Config::IniFiles

          Most Linux distributions package LWP under the filename
          libwww-perl (Debian: apt-get install libwww-perl
          libhtml-template-perl libcgi-session-perl
          libconfig-inifiles-perl)

     2.   Unzip the distribution.  Upload all files in cgi-bin in ASCII
          mode to a directory on your server that can run cgi.  For
          example, I recommend creating a directory called aviman off your
          cgi-bin.

          Make sure these files are transferred in ASCII mode!!

          Upload the files in avimanager/pages to a directory outside
          cgi-bin.

          On your server, you should now have two directories with
          following structure

                  cgi-bin/aviman/
                  cgi-bin/aviman/Aviman/
                  cgi-bin/aviman/Aviman/CGI
                  cgi-bin/aviman/data
                  cgi-bin/aviman/data/db
                  cgi-bin/aviman/data/db/backup
                  cgi-bin/aviman/data/db/comment
                  cgi-bin/aviman/data/db/plots
                  cgi-bin/aviman/data/movielist
                  cgi-bin/aviman/data/tmp
                  cgi-bin/aviman/data/votes
                  cgi-bin/aviman/language
               
                  aviman/pages/
                  aviman/pages/images
                  aviman/pages/images/cover
                  aviman/pages/images/headshots
                  aviman/pages/subtitles
                  aviman/pages/themes
                  aviman/pages/themes/default
                  aviman/pages/themes/default/images
                  aviman/pages/themes/default/templates

     3.   [X] Double-check that the Path to perl in aviman.pl and all other
          *.pl files is correct.

                       #!/usr/bin/perl

     4.   Set permissions:

             * chmod 755 (-rwxr-xr-x) on the *.pl files and aviman.cfg file
               in cgi-bin/aviman/

             * 777 (drwxrwxrwx) on the cgi-bin/aviman/data directory and
               its subdirectories

             * 777 (drwxrwxrwx) on the pages/images directory and its
               subdirectories

     5.   [X] Open aviman.cfg with your favorite editor and answer the
          configuration questions.  The most confusing step here for many
          new users is the owners feature.  If you want to manage your
          movie collection with your roommate for example, you have to add
          your username and your roommates username here.

          `@owners = ("me", "roommate");'

          Yes, this is a hack and there is not yet an interface for adding
          or removing owners.  Removing owners is probably not yet possible
          without some textfile hacking, so you should only delete the
          accounts (that means, they can't login anymore)!

     6.   Open Aviman/CGI/aviman_cgi.ini with your favorite editor and set
          paths and urls

     7.   [X] Go to: http://yourserver.com/cgi-bin/aviman/aviman.pl or
          wherever you set up aviman.pl, Login as user: admin, password:
          admin, and you should see the search screen.

          Now try following features:

          1.   Add a new super user account [SU] (e.g.  "me" and "roommate"
               in the example above).

          2.   Logout and login as "me"

          3.   Add a movie.

          4.   Search for a movie.

          5.   Vote for a movie

          6.   add comments

          7.   upload file (if you have activated subtitle upload in
               aviman.cfg)

          8.   delete user "admin"

          If everything goes ok, you should be all done!

     8.   [X] Customize look.  Edit htm-files in aviman directory and
          db.css.  Of course, all changes in aviman.pl will be lost if you
          upgrade to a newer version of aviManager.  This will change in
          future versions due enhanced template support.  WARNING:
          themes-format is still beta and is likly to change until 0.9
          final.

     9.   [X] Maybe you want to translate aviManager to your native
          language?  Cool!  Open aviman.de in cgi-bin/aviman/language as
          template, translate the I: lines and save it as aviman.xx, where
          xx is an abbrevition for you language (en - english, fr - french,
          ...) and send it to mriester@gmx.de.  Oh, and tell me the name of
          your language in your language (German - Deutsch, ...).

     10.  [X] Optional but highly recommended: Install String::Approx
          (http://search.cpan.org/search?dist=String-Approx)

          Debian: apt-get install libstring-approx-perl

     11.  [X] If you have problems, please use our help-forum
          (http://sourceforge.net/forum/forum.php?forum_id=183397) at
          sourceforge.

     12.  [X] If you miss some fields (Quality, md5sums, ...), it is now
          the best moment to add them, because it is much more difficult
          with an existing database.  Please read comments in aviman.cfg,
          Preference Questions and read the FAQ in this manual.

3. Customizing

     aviManager is highly configurable!  See aviman.cfg for details.  For
     example, you can easily add fields (like the often requested Quality
     Field).  TODO: explain field adding better, present cool optional
     features

4. Problems

5. Hints

     Many things are obvious, but aviManager has some great "hidden"
     features:

5.1. Searching

Regular Expressions in search. Keywords between two slashes (/keyword/) are treated as regular expressions. The last slash is not required (/keyword works,too) Examples:
Problem: If you search for "foobar", fuzzy search finds too much. Solution: use simple regex /foobar instead

                        foobar gets foobaa, fooba, ...
                        /foobar gets only foobar

        * List all movies start with letter X (search is not case
          sensitive) type /^x and select movielist in combobox so that
          Xander Berkeley will be ignored

        * List all movies from 1966

               /\t1966

          (\t is tab and standard sepearator in movies.txt, /1966 will list
          also movies with 1966 in imdb number)

        * List all movies better than imdb-rating 9 (10.0 will be ignored)

               /\t9\..*

5.2. Voting

Fast Voting (just 3 clicks per movie) with this features:

aviManager sets "seen" to 1 if you vote (rating) for a movie and current value for seen is 0.
Next/Prev not yet voted for links in detailpage.

5.3. Find Movie

aviManager displays movies (not in single_user_mode) in find results with different back- ground colors. The darker, the more other people want to see this movie. Great with many users.
Maybe you want to turn "Check wishlist" off if you watch a movie with friends that have not yet voted. Then, only your seen and (imdb-)rating will count, not your wishes.

5.4. Add Movie

There are four methods of adding movies:

Search IMDb: Simply type the movie title in the search field of this box. If there are more than one results, click on the movie you want to add and avimanager grabs the data immediately
Add by directory name: If you have an DivX movie which follows "The DivX Releasing Standards 2002", you can simply add this movie by cnp the directoryname in this box. This feature is still beta, please send me directory names where this does not work!!!
Add by IMDb number: cnp the IMDb number in the corresponding field in the "Add Movie" Box
Add Movie (Offline): This allows you to add movies without the IMDB-grabber

5.5. Burning Movies to CDROM/DVD

     When you add a movie, aviManager sets status to "not burned".  If you
     have burned some movies on a DVD, you can go to the "not burned" page
     (first link in the admin box), select them and add a description for
     that DVD.  You can create hierarchies with slashes, e.g.  a
     description DVD/2005/001 will create a tree DVD->2005->001 in the "All
     Media" page.

5.6. Different formats for movie lists

     If you have many movies, you don't want this colourful default movie
     list with plot and cover.  Set $use_wn_format = 0; in aviman.cfg and
     you get a table with need much less space.

5.7. Update Votes

     With the cgi-script update_votes.pl, you can update imdb votes and
     rating.  Goto
     http://your.server.com/cgi-bin/aviman/update_votes.pl?plot=1 to grab
     all votes, ratings and plots.

5.8. Playing movies in browser

     If you copy your movie files in /apache_document_root/aviman/media and
     if you add this path in the Medium field of the movie, then aviManager
     generates a link to that file.

     You don't have to add the full path in the Medium field:
     /var/www/aviman/media/ or media/ are both ok.

6. Importing Data

     AviManager stores data in a file called movie.db.  Please open this
     file now if you want to import data.  You need to get your old
     database into this format (see aviman.cfg, Preference Question 7 for
     details).  You probably have no IMDb numbers, so you must get them.
     Please contact me, and I will help you...

     Ok, now you think you have a valid movies.db?  Please check this with
     the script show_db.pl (in tools/cgi)!

     Now you get an html-table with the database.  If everything looks
     good, it is time to get the IMDb data like plots, cover, actors,
     genre, year and runtime.  The script update_votes.pl can do this.  To
     test it with 5 movies, start the script with following parameters:
     `http://www.yourserver.com/cgi-bin/aviman/update_votes.pl?start_number=1&count=5&actors=1&cover=1&plot=1&genre=1&year=1&runtime=1'.
     Start aviman.pl and go to one of these movies.  Everthing ok?  Then
     start the script without start_number and count!

     Please help to improve this HOWTO/Importing!

7. FAQ

Feel free to email me if your question is not mentioned here

Q:Is it possible to add field 'foobar'?
A:Yes, version 0.5 comes with a new database structure that makes this possible. Read comments in aviman.cfg.
[ If you have an existing database, you have to convert movies.txt with the script convert_db.pl or change every movie manually ]
Examples
1. A normal STRING field (like Name, Comment, ...), for example Ripper: open aviman.cfg and add following line in database definition %db:
  `Ripper => [11, 'STRING', 0, 0, 0, 30, 75, 0, '', ''],'
  Last column is a regex (for INTEGER fields etc.)
2. An SELECT field (like Status), for example Type: add an hash somewhere BEFORE database definition
  `%type = ('1'=>'DivX','2'=>'DVD','3'=>'SVCD','4'=>'MPEG','5'=>'VHS');'
  and add line in %db:
  `Type => [12, 'SELECT', 0, 1, 1, 20, 25, 1, '1', \%type],'
Q:Field 'foobar' is too short/big, where can I change it?
A:Like everything else, in aviman.cfg. Open it with your favorite editor, goto preference questions, question 5. There you can see the datafield definition. Column six is form length and column seven is maximum field length. See comments in aviman.cfg.
Q:I can't login. Whats f***ed up?
A:See chapter "Problems" for details
Q:I don't want/can't use .htaccess. Do I really need it? (obsolet)
A:Yes, if you want more than one user (hey, this is our main feature). AviManager uses .htaccess to know, who's the current user. If you need just a little database for your seventeen movies, set $single_user_mode = 1. Then you have only one user ($single_user_name) and all multiuser features will be hidden (version 0.5pre4 or higher). But if you know a secure alternative for .htaccess (Session ID, cookies), let me know ...
Q:There is no movie of the moment!
A:You have less than 50 movies
Q:I don't like this stupid copyright at the bottom of every page. Can I remove it?
A:Yes.
Q:I like aviManager and want to help! What can I do?
A:Cool! Unfortunatly, the aviManager source code is not very beautiful and needs a lot of work, so programming jobs are no fun I think. But there are a lot of other jobs to do, for example:
1. Translations
2. A nice, classical aviman-logo for the new theme. the plain AVIMANAGER at the top looks not very good
3. Header for new versions: Write me an email with your favorite actor and if I like her/him, be creative ;-)
4. Documentation: I'm not a native english speaker and I am the author of this software...Two reasons why this documation is not as good as it should be. The source-code of this document is available from cvs. Type:
  `cvs -d:pserver:anonymous@cvs.avimanager.sourceforge.net:/cvsroot/avimanager login'
  When prompted for a password for anonymous, simply press the Enter key. Then type
  `cvs -z3 -d:pserver:anonymous@cvs.avimanager.sourceforge.net:/cvsroot/avimanager co manual'
  Edit it and send it to mriester@gmx.de!
5. Templates (HTML, LaTeX) for movielists
No MySQL? This sucks! Maybe, yes. The first reason is: the time I wrote this, there was no SQLite database. I wanted to keep the system requirements as low as possible. The second: the time I wrote this, I had no idea about Perl and SQL ;).

8. Revision History

The aviManager-Evolution:

?: _0.9 aka "?"_
Installer script. Better support for multiple owners. XHTML 1.0. Login with sessions instead of .htaccess. New translations (greek, russian, polish, danish). Many minor bugfixes. The most stable aviManager every!
10.01.2003: _0.8 aka "BERGMAN II"_
Many cool features like IMDb search, lent list and sorting. New translations (french, norwegian, spanish) and performance and usability enhancements.
01.11.2002: _0.7 aka "BERGMAN"_
New clean directory structure, bugfixes, documentation and again a lot of polishing
01.09.2002: _0.6 aka "HEPBURN"_
New, clean standard design, welcome page, templates for export movielist ... in one word: polished
04.08.2002: _0.5 aka "MONROE"_
Multilanguage support, new great database structure, update votes, grab imdb plot and title, comments and many minor enhacements
01.07.2002: _0.4 aka "WORLDCHAMPION"_
fast actors-format, statistics, new search, ... a must!
01.06.2002: _0.3 aka "SCHEISSEMANN"_
owner, subtitles ...
02.03.2002: _0.2_
more features, faster (actors still slow)
24.02.2002: _0.1_
basic features, BAD performance, many bugs

see CHANGELOG

9. Credits

     A big "thank you" goes to thrawn and ronin for their bugreports,
     graphics and patches, all people who sent bugreports, hints and
     feature requests and of course www.imdb.com for their great database!

     _Translations_

        * Juan Jose Gutierrez de Quevedo: Spanish

        * Robert: Norwegian

        * Ashar Voultoiz: French

        * Juho Vahakangas: Finnish

        * Matte: Swedish

        * Lorro: Hungarian

        * Petar Benke: Serbian

        * Flavio Cardone: Polish

        * Reloaded: Danish

        * Terzi Athanasia: Greek

aviManager - Manual

Markus Riester <mriester@gmx.de>

0.9rc2