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 --

You can remove specific array options with -no_<option>
and clear all the array options with -clear_<option>.
To clear out array options (say, from the previous album run):

% album -clear_exif -exif "new exif"

(The -clear_exif will clear any previous exif settings and then the
 following -exif option will add a new exif comment)

And finally, you can remove specific array options with 'no_':

% album -no_exif hi

Which could remove the 'hi' exif value and leave the 'there' value intact.

Also see the section on Saving Options.

To see a brief usage:

% album -h

To see more options:

% album -more

And even more full list of options:

% album -usage=2

You can specify numbers higher than 2 to see even more options (up to about 100)

Plugins can also have options with their own usage.


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.

Themes are found according to the -theme_path setting, which is
a list of places to look for themes.  Those paths need to be somewhere
under the top of your web directory, but not inside a photo album
directory.  It needs to be accessible from a web browser.

You can either move the theme into one of the theme_paths that album
is already using, or make a new one and specify it with the -theme_path
option.  (-theme_path should point to the directory the theme is in,
not the actual theme directory itself)

Then call album with the -theme option, with or without -theme_path:

% album -theme Dominatrix6 my_photos/
% album -theme Dominatrix6 -theme_path /home/httpd/album/Themes/ my_photos/


You can also create your own themes pretty easily, this is covered
later in this 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 '-sort date' and '-sort name'

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 "<br>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 "<br>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 "<br>File: %File name% " "taken with %Camera make%" --

Note that, as above, you can include HTML in your EXIF tags:

% album -exif "<br>Aperture: %Aperture%"

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 .hide_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, hide_album
and not_img 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.  Furthermore, if you use
themes, you must use relative paths.  You can't use -theme_url because
you don't know what the final URL will be.  On Windows the theme path
could end up being "C:/Themes" or on UNIX or OSX it could be something
like "/mnt/cd/Themes" - it all depends on where the CD is mounted.
To deal with this, use the -burn option:

  % album -burn ...

This requires that the paths from the album to the theme don't change.
The best way to do this is take the top directory that you're going to
burn and put the themes and the album in that directory, then specify
the full path to the theme.  For example, create the directories:

  myISO/Photos/
  myISO/Themes/Blue

Then you can run:

  % album -burn -theme myISO/Themes/Blue myISO/Photos

Then you can make a CD image from the myISO directory (or higher).

If you are using 'galbum' (the GUI front end) then you can't specify
the full path to the theme, so you'll need to make sure that the version
of the theme you want to burn is the first one found in the theme_path
(which is likely based off the data_path).  In the above example you
could add 'myISO' to the top of the data_path, and it should
use the 'myISO/Themes/Blue' path for the Blue theme.

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

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.