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

# Files

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:

- Have an image already uploaded then upload a video via the upload page. (or vice versa) The video will share the thumbnail of the image.
- FTP upload both the video and (thumbnail or image) then batch-add. If you FTP upload the thumbnail, the thumbnail will be display in the batch add page instead of the default Coppermine thumbnail. If you upload an image it will look like the above screenshot. However, when the both files are added to the database, the thumbnail of the image will be used by the video.

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:

- Create the custom thumbnail on your desktop
  Take a screenshot of the movie using your favorite desktop app that is capable to accomplish this, use a picture that represents the content of your video or doodle something in MS Paint: you have to create the custom thumbnail first on your desktop. We really can't help you with that, since there are so many different desktop apps available.
  Pay attention that the custom thumbnail you come up with has got the same dimensions your other thumbails have (according to the dimensions you have set for your thumbnails in coppermine's config).
  Once you're done with this, you should have a thumbnail file (as a jpg) on your desktop that has the proper dimensions. Don't upload it yet - let's do some checks first.
- Figure out the exact location and name of the video that you're trying to come up with a thumbnail for it
  Now, this can be the most tricky part for newbies: let's assume that the video has already been uploaded to coppermine. If it was you who uploaded the movie using FTP upload plus batch-add in the first place, you should know the exact folder and file name, but for this example let's assume that one of your users has used http uploads to upload the video, so you have no idea where the actual file went to.
  Don't panic, start your browser, go to your gallery and start browsing it. Navigate to the page that embedds the video, so you can see the actual video being played within the Coppermine user interface. Now, do a right-click, show source somewhere inside the browser window. Don't do the right-click on the actual video, but into some blank space next to it. The HTML output of the page you're looking at should show up. Now search the HTML output for the term `class="imageborder"` - this should bring you right in front of the block that we're actually looking for, so carefully scroll down a bit more (4 or 5 lines). We're looking for a block of code that looks like this:

      <param name="src" value="albums/userpics/10235/myvideo.avi" />

  The value that is given for that parameter (`albums/userpics/10235/myvideo.avi` in this example) is what we're looking for. It indicates in which folder the file actually resides (`albums/userpics/10235/` in this example) and what the file name is (`myvideo.avi` in this example). Memorize this piece of information (or just keep the source view window open, with the section we just found out highlighted) - we'll need the information in the next two steps.
- Rename your custom thumbnail on your desktop
  Back to your desktop, we have to name our custom to match the naming conventions. For above example (and assuming that you haven't changed the thumbnail prefix in config), you have to rename the custom thumbnail on your desktop to `thumb_myvideo.jpg`. Keep in mind that capitalization matters!
- Upload the custom thumb
  Finally, the custom thumb is ready to be uploaded - we just have to make sure that it goes into the folder where your original video resides in. In above example, the relative folder (seen from coppermine's root folder) would be `albums/userpics/10235/`.
  Start your favorite FTP application (like Filezilla or similar), connect to your webserver and upload your custom thumbnail from your desktop into the folder that represents the URL `http://yoursite.tld/your_coppermine_folder/albums/userpics/10235/`
- Done
  If everything works as expected, you should be done. Make sure that it does by starting your browser once more, browse your gallery and navigate to the album view that contains the video we just created a custom thumbnail for. You should by now see the custom thumbnail instead of the generic one. If this is not the case for you immediately, make sure that you're not looking at a cached copy of the page - you better force-refresh your browser ([Ctrl]+[F5]) when looking at the thumbail page.
- Things that you should not do
  If a custom thumbnail that corresponds to a video file according to the naming scheme exists within the same folder, it will be used. Therefore, you shouldn't (and mustn't) use the http upload mechanism built into coppermine to upload the custom thumbnail, nor are you supposed to batch-add the custom thumbnail. You just FTP-upload it and that's it! We don't want it to reside in the database.

### Custom thumbnails FAQ

- #### I have a video named `movie.wmv`, when I upload a thumbnail for it `thumb_movie.jpg` it replaces the thumbnails for multiple videos!

  Duhh. `thumb_movie.jpg` is a media-specific thumbnail. Rename the video and the thumbnail with something other than just 'movie'.

- #### I can't find my user's folder!

  From within Coppermine, browse to the user's album. Look in the url of your browser and you should see the folder's name. (See screenshot for an example.)
  Your users can upload their own thumbnails by using this trick: Create an album. Change the permissions on it so no one can view it except that specific user. Then upload the fullsized images of the thumbnails to this folder. Files outside this album will be able to use the thumbnails of these images. (See above for naming.)

- #### How do I stop my users from creating their own custom thumbnails?

  Currently, this is not possible.