Coppermine Photo Gallery v1.5.x: Documentation and Manual

Table of Contents


In Coppermine, uploaded files go into albums. Albums can contain files, but not sub-albums. Albums can go into categories. Categories can contain sub-categories and albums, but they can not contain files.

Coppermine (in version 1.0) was designed in the first place to display images. Later in the development process came multimedia files (audio and video files as well as documents), that's why the term "images" was dropped in favor of "files". In some places (e.g. in table names or some places of the documentation), the term "image" might shine through through although "files" are actually meant.

You might be tempted to believe that Coppermine was actually a file editor because it has the capabilities to edit (resize) and create images. However, that is only the case to a limited extent: Coppermine is not an image editor and can't be used as a replacement for such a desktop app. Instead, it's a web gallery that works good to display your files on the www.

Editing files

Use this link to modify your file's title, description, keywords, and custom fields (if they are used).

Use the album drop down menu in the panel to move the file between albums. Use keywords to link files to other albums (see description in the albums section above).

Editing videos

Here, you can modify the title, description, keywords, and custom fields (if they are used) of your video files.

Use the album drop down menu to move the video to another album.

Use the height and width fields to set the size of the video.

Video uploads are possible beginning with cpg1.3.0 (or latter) and are included as part of the distribution package.

Custom Thumbnails

Order of thumbnails

Thumbnails are defined by different levels (these are: user-defined, theme-defined, global) then in the order of their type (file-specific, extension-specific, media-specific).

User-defined thumbnails are stored in the folder where the parent file is located. Theme-defined thumbnails are stored in the themes 'images' folder. Global thumbnails are stored within the 'images' folder of the Coppermine root.

Thumbnails can be one of the following file types: 'gif', 'png', or 'jpg'.

Types of thumbnails

File-specific thumbnails must have the same base name as the file.

Using the above screenshot of a video file as an example, the thumbnails for this file could be 'thumb_thailand_waterfall.gif', 'thumb_thailand_waterfall.png', or 'thumb_thailand_waterfall.jpg', and searched for by cpg in that order.

Extension-specific thumbnails are named after the extension of the file. (Examples: 'thumb_wmv.jpg', 'thumb_wav.jpg'.)

The base name for media-specific thumbnails are 'thumb_movie', 'thumb_document', and 'thumb_audio'. Images use file-specific thumbnails by default.

Uploading custom thumbs

There are 2 ways to upload custom thumbnails:

Note: If the first method is used and the image later deleted, the thumbnail will also be deleted and the default Coppermine thumbnails will be displayed, instead.

If a previously uploaded video is to be uploaded again, via FTP, the accompanying thumbnail must also be uploaded, via FTP, to the same folder.

Using the above instructions, a custom thumbnail can be applied to any file, not just videos.

How it works

As suggested above, there are different types of thumbnails. Most users don't care for the generic thumbnail that represents a particular file type (like movies with the extension .mov) - they don't want to see that generic thumbnail at all, but just a nicely looking thumbnail that blends into the generated ones for image uploads. To understand how this works, you just have to take a look at how coppermine works: file uploads go into particular folders. Coppermine "looks" into the folder where your file actually is stored in to see if there is a thumbnail that "fits" to the file, respecting the naming scheme. If it finds such a thumbnail, it will use it. If it doesn't, it will use the generic one that was designed to represent the media type.

Naming scheme

The naming scheme is pretty straightforward: you can specify a prefix for the thumbnails in coppermine's config. Out of the box, this prefix is set to thumbs_, and that's fine - don't change that setting unless you really, really know what you're doing. So for now, let's assume that you haven't changed it, it is the default prefix thumbs_.

Now, let's assume that you're trying to create a custom thumbnail for the file myvideo.avi that resides in the folder /albums/userpics/10235/. Subsequently, coppermine would look into that folder and see if there is a file named thumb_myvideo.jpg. If this thumbnail file exists, it will be used as a thumbnail to represent the video. If it doesn't exist, Coppermine would use the generic one.

Therefore, the naming scheme is the thumbnail prefix plus the file name of the video (without the extension) plus a dot (to separate the actual filename from the extension) plus the extension jpg.

Capitalization matters: many users are not aware that there is a difference on Unix/Linux-driven computers between lower case and upper case, simply because on Windows there is no such difference. You have to keep this aspect in mind: since most webservers are Unix/Linux-driven, capitalization matters! That's why thumb_myvideo.jpg and thumb_myvideo.JPG are two entirely different animals. It does matter how you name your custom thumbnail. If the file you're trying to represent with a custom thumbnail is named myVideo.avi, the custom thumbnail needs to be named thumb_myVideo.jpg! Other variants with different capitalization (like thumb_myVideo.JPG, thumb_myvideo.jpg, Thumb_myVideo.jpg, thumb_myVideo.Jpg or similar) will not work as expected!

Why can't coppermine create thumbnails for my videos?

All this custom thumbnail business might appear very complicated to newbies, and in fact you're right: this is a complicated process. Therefore, many users ask why this has to be so complicated. Coppermine can create thumbnails for images, so why can't it create thumbnails for videos? The reason is pretty simple: because the image libraries that Coppermine is relying on (GD or ImageMagick, see "Minimum requirements") to create thumbnails from images don't support videos. It's not that the Coppermine developers have been reluctant to come up with code that auto-creates thumbnails for videos - it's just that they can't because the technology that is available on your webserver can't.

Step-by-step instructions

Here is a step-by-step tutorial to get you going:

Custom thumbnails FAQ