Table Of Contents

1. Basic execution
2. Options
3. Themes
4. Sub-albums
5. Avoiding Thumbnail Regeneration
6. Cleaning Out The Thumbnails
7. Medium size images
8. Captions
9. EXIF Captions
10. Headers and Footers
11. Hiding Files/Directories
12. Cropping Images
13. Video
14. Burning CDs (using file://)
15. Indexing your entire album
16. Updating Albums With CGI

1:   Basic execution

Create a directory with nothing but images in it.  The album script and
other tools should not go here.  Then run album specifying that directory:

% album /example/path/to/images/

Or, if you're in the /example/path/to directory:

% album images/

When it's done, you'll have a photo album inside that directory starting
with images/index.html.

If that path is in your web server, then you can view it with your
browser.  If you can't find it, talk to your sysadmin.

2:   Options
There are three types of options.  Boolean options, string/num options
and array options.  Boolean options can be turned off by prepending -no_:

% album -no_image_pages

String and number values are specified after a string option:

% album -type gif
% album -columns 5

Array options can be specified two ways, with one argument at a time:

% album -exif hi -exif there

Or multiple arguments using the '--' form:

% album --exif hi there --

3:   Themes

Themes are an essential part of what makes album compelling.
You can customize the look of your photo album by downloading a
theme from MarginalHacks or even writing your own theme to match
your website.

To use a theme, download the theme .tar or .zip and unpack it.

Place the theme somewhere under the top of your web directory, but
don't put it inside your photo album directory.

Then call album with the -theme option:

% album -theme /example/web/path/Themes/Dominatrix6 images/

You can shorten this with the -theme_path option.  If you had a config file:

# My config file
theme_path /example/web/path/Themes/

Then you could just type:

% album -theme Dominatrix6 images/

You can also create your own themes pretty easily, this is covered
in separate documentation.

4:   Sub-albums

Make directories inside your first directory and put images in that.
Run album again, and it will run through all the child directories
and create sub-albums of the first album.

If you make changes to just a sub-album, you can run album on that
and it will keep track of all the parent links.

If you don't want to traverse down the tree of directories, you
can limit it with the depth option.  Example:

% album images/ -depth 1

Will only generate photo albums for the images directory.

If you have many sub-albums, and you want to add a new sub-album
without regenerating all the previous sub-albums, then you can use -add:

% album -add images/new_album/

Which will add the new_album to the HTML for 'images/' and then
generate the thumbs and HTML for everything inside 'images/new_album/'

5:   Avoiding Thumbnail Regeneration

album tries to avoid unnecessary work.  It only creates thumbnails if
they don't exist and haven't changed.  This speeds up successive runs
of album.

This can cause a problem if you change the size or cropping of your
thumbnails, because album won't realize that the thumbnails have changed.
You can use the force option to force album to regenerate thumbnails:

% album -force images/

But you shouldn't need to use -force every time.

6:   Cleaning Out The Thumbnails

If you remove images from an album then you'll have leftover thumbs and HTML.
You can remove them by running album once with the -clean option:

% album -clean images/

7:   Medium size images

When you click on an album thumbnail you're taken to an 'image_page.'
The image_page shows, by default, the full size image (as well as
navigation buttons and captions and such).  When you click on the
image on the image_page, you'll be taken to the URL for just the full
size image.

If you want a medium size image on the image_page, use the -medium
option and specify a geometry for the medium size image.  You can
specify any geometry that ImageMagick can use (see their man page
for more info).  Some examples:

# An image that is half the full size
% album -medium 50%

# An image that fits inside 640x480 (maximum size)
% album -medium 640x480

# An image that is shrunk to fit inside 640x480
# (but won't be enlarged if it's smaller than 640x480)
% album -medium '640x480>'

You need the 'quotes' on the last example with most shells because
of the '>' character.

8:   Captions

Images and thumbnails can have names and captions.  There are a number
of ways to specify/change names and captions in your photo albums.

The name is linked to the image or image_page,
and the caption follows underneath.

The default name is the filename cleaned up:
  "Kodi_Cow.gif"  =>  "Kodi Cow"

One way to specify a caption is in a .txt file
with the same name as the image.  For this example,
"Kodi_Cow.txt" could contain "Kodi takes down a cow!"

You can rename your images and specify captions in bulk
for an album directory with a captions.txt file.

Each line of the file should be an image or directory filename,
followed by a tab, followed by the new name.  You can also 
specify (separated by tabs), an optional caption and then an optional 
image ALT tag.  (To skip a field, use 'tab' 'space' 'tab')

Example:

001.gif	My first photo
002.gif	Mom and Dad My parents in the grand canyon
003.gif	Ani DiFranco	My fiancee	Yowsers!

The images and directories will also be sorted in the order they are found
in the caption file.  You can override this with -date_sort and -name_sort

If your editor doesn't handle tabs very well, then you can separate the
fields by double-colons, but only if the caption line doesn't contain any
tabs at all:

003.gif :: Ani DiFranco :: My fiancee :: Yowsers!

If you only want captions on image pages (not on album pages) use:

% album -no_album_captions

If you want web access to create/edit your captions, look at the
caption_edit.cgi CGI script (but be sure to limit access to the
script or anyone can change your captions!)

9:   EXIF Captions

You can also specify captions that are based off of EXIF information
(Exchangeable Image File Format) which most digital cameras add to images.

First you need 'jhead' installed.  You should be able to run jhead
on a JPG file and see the comments and information.

EXIF captions are added after the normal captions and are specified with -exif:

% album -exif "File: %File name% taken with %Camera make%"

Any %tags% found will be replaced with EXIF information.  If any %tags%
aren't found in the EXIF information, then that EXIF caption string is
thrown out.  Because of this you can specify multiple -exif strings:

% album -exif "File: %File name% " -exif "taken with %Camera make%"

This way if the 'Camera make' isn't found you can still get the 'File name'
caption.

Like any of the array style options you can use --exif as well:

% album --exif "File: %File name% " "taken with %Camera make%" --

To see the possible EXIF tags (Resolution, Date/Time, Aperture, etc..)
run a program like 'jhead' on an digital camera image.

You can also specify EXIF captions only for album or image pages, see
the -exif_album and -exif_image options.

10:  Headers and Footers

In each album directory you can have text files header.txt and footer.txt
These will be copied verbatim into the header and footer of your album (if
it's supported by the theme).

11:  Hiding Files/Directories

Any files that album does not recognize as image types are ignored.
To display these files, use -no_known_images.  (-known_images is default)

You can mark an image as a non-image by creating an empty file with
the same name with .not_img added to the end.

You can ignore a file completely by creating an empty file with
the same name with .no_album on the end.

You can avoid running album on a directory (but still include it in your
list of directories) by creating a file <dir>/.no_album

You can ignore directories completely by creating a file <dir>/.hide_album

The Windows version of album doesn't use dots for no_album and
hide_album because it's difficult to create .files in Windows.

12:  Cropping Images

If your images are of a large variety of aspect ratios (i.e., other than
just landscape/portrait) or if your theme only allows one orientation,
then you can have your thumbnails cropped so they all fit the same geometry:

% album -crop

The default cropping is to crop the image to center.  If you don't 
like the centered-cropping method that the album uses to generate 
thumbnails, you can give directives to album to specify where to crop 
specific images.  Just change the filename of the image so it has a 
cropping directive before the filetype.  You can direct album to crop 
the image at the top, bottom, left or right.  As an example, let's 
say you have a portrait "Kodi.gif" that you want cropped on top for 
the thumbnail.  Rename the file to "Kodi.CROPtop.gif" and this will 
be done for you (you might want to -clean out the old thumbnail).  
The "CROP" string will be removed from the name that is printed in 
the HTML.

The default geometry is 133x133.  This way landscape images will
create 133x100 thumbnails and portrait images will create 100x133
thumbnails.  If you are using cropping and you still want your
thumbnails to have that digital photo aspect ratio, then try 133x100:

% album -crop -geometry 133x100

Remember that if you change the -crop or -geometry settings on a
previously generated album, you will need to specify -force once
to regenerate all your thumbnails.

13:  Video

album can generate snapshot thumbnails of many video formats if you
install ffmpeg

If you are running linux on an x86, then you can just grab the binary,
otherwise get the whole package from ffmpeg.org (it's an easy install).

14:  Burning CDs (using file://)

If you are using album to burn CDs or you want to access your albums with
file://, then you don't want album to assume "index.html" as the default
index page since the browser probably won't.  Simple add the option:

  % album -index index.html ...

You can also look at winopen for windows users, you can have it
automatically launch the album in a browser.

15:  Indexing your entire album
To navigate an entire album on one page use the caption_index tool.
It uses the same options as album (though it ignores many
of them) so you can just replace your call to "album" with "caption_index"

The output is the HTML for a full album index.

See an example index
for one of my example photo albums

16:  Updating Albums With CGI

First you need to be able to upload the photo to the album directory.
I suggest using ftp for this.  You could also write a javascript that
can upload files, if someone could show me how to do this I'd love to know.

Then you need to be able to remotely run album.  To avoid abuse, I
suggest setting up a CGI script that touches a file (or they can just
ftp this file in), and then have a cron job that checks for that
file every few minutes, and if it finds it it removes it and runs album.
[unix only]  (You will probably need to set $PATH or use absolute paths
in the script for convert)

If you want immediate gratification, you can run album from a CGI script
such as this one.

If your photos are not owned by the webserver user, then you
need to run through a setud script which you run from a CGI [unix only].
Put the setuid script in a secure place, change it's ownership to be the
same as the photos, and then run "chmod ug+s" on it.  Here are example
setuid and CGI scripts.  Be sure to edit them.

Also look at caption_edit.cgi which allows you (or others) to edit
captions/names/headers/footers through the web.