2016-11-04 00:31:35 +00:00
# thumbsup
2014-04-17 11:26:18 +00:00
2018-05-15 06:25:43 +00:00
<!-- Project info -->
2014-08-05 03:24:14 +00:00
[](https://npmjs.org/package/thumbsup)
2017-03-08 10:47:06 +00:00
[](https://github.com/thumbsup/thumbsup)
2018-05-15 06:25:43 +00:00
[](http://standardjs.com/)
<!-- Build status and code analysis -->
2021-01-12 23:10:44 +00:00
2017-03-08 10:47:06 +00:00
[](https://travis-ci.org/thumbsup/thumbsup)
2018-05-15 06:25:43 +00:00
[](https://hub.docker.com/r/thumbsupgallery/thumbsup)
2017-03-08 10:47:06 +00:00
[](https://david-dm.org/thumbsup/thumbsup)
[](https://david-dm.org/thumbsup/thumbsup?type=dev)
2016-11-04 00:31:35 +00:00
2018-05-15 06:25:43 +00:00
<!-- Social sharing -->
2018-05-14 18:30:06 +00:00
[](https://twitter.com/intent/tweet?text=Need%20static%20photo%20and%20video%20galleries?%20Check%20out%20Thumbsup%20on%20Github& url=https://github.com/thumbsup/thumbsup& hashtags=selfhosted,static,gallery)
[](https://www.linkedin.com/shareArticle?mini=true& url=https://github.com/thumbsup/thumbsup& title=Static%20gallery%20generator& summary=Thumbsup%20is%20a%20command-line%20friendly%20static%20gallery%20generator%20for%20all%20your%20photos%20and%20videos& source=Github)
[](https://www.facebook.com/sharer.php?u=https://github.com/thumbsup/thumbsup)
2018-06-08 22:28:27 +00:00
---
< p align = "center" > https://thumbsup.github.io< / p >
< img align = "center" src = "docs/banner.jpg" alt = "Banner" / >
---
2014-08-05 03:24:14 +00:00
2016-11-04 00:31:35 +00:00
Turn any folder with photos & videos into a web gallery.
2014-04-17 11:26:18 +00:00
2014-06-10 02:53:06 +00:00
- thumbnails & multiple resolutions for fast previews
2016-10-16 06:09:42 +00:00
- mobile friendly website with customisable themes
2014-04-21 09:39:48 +00:00
- only rebuilds changed files: it's fast!
2014-04-17 11:26:18 +00:00
- uses relative paths so you can deploy the pages anywhere
- works great with Amazon S3 for static hosting
2016-11-04 00:31:35 +00:00
## Quick start
2014-04-17 11:26:18 +00:00
2016-11-04 00:31:35 +00:00
Simply point `thumbsup` to a folder with photos & videos. All nested folders become separate albums.
2016-09-27 08:37:07 +00:00
```bash
2017-03-01 10:57:55 +00:00
npm install -g thumbsup
2017-11-25 11:29:21 +00:00
thumbsup --input ./photos --output ./gallery
2014-04-17 11:26:18 +00:00
```
2017-11-24 10:52:10 +00:00
2017-08-15 08:48:37 +00:00
2017-11-25 11:29:21 +00:00
There are many command line arguments to customise the output.
2016-11-04 00:31:35 +00:00
See the website for the full documentation: https://thumbsup.github.io.
2016-10-16 06:09:42 +00:00
2019-06-12 19:29:36 +00:00
## Sample gallery
See a sample gallery online at https://thumbsup.github.io/demos/themes/mosaic/
2017-08-15 08:48:37 +00:00
## Requirements
2017-09-12 02:36:27 +00:00
2017-08-15 08:48:37 +00:00
Thumbsup requires the following dependencies:
2018-06-07 22:49:03 +00:00
- [Node.js ](http://nodejs.org/ ): `brew install node`
2017-09-12 02:36:27 +00:00
- [exiftool ](http://www.sno.phy.queensu.ca/~phil/exiftool/ ): `brew install exiftool`
- [GraphicsMagick ](http://www.graphicsmagick.org/ ): `brew install graphicsmagick`
2018-06-07 22:49:03 +00:00
And optionally:
- [FFmpeg ](http://www.ffmpeg.org/ ) to process videos: `brew install ffmpeg`
- [Gifsicle ](http://www.lcdf.org/gifsicle/ ) to process animated GIFs: `brew install gifsicle`
2019-01-08 20:45:02 +00:00
- [dcraw ](https://www.cybercom.net/~dcoffin/dcraw/ ) to process RAW photos: `brew install dcraw`
2019-06-12 19:27:39 +00:00
- [ImageMagick ](https://imagemagick.org/ ) for HEIC support (needs to be compiled with `--with-heic` )
2018-06-07 22:49:03 +00:00
You can run thumbsup as a Docker container ([thumbsupgallery/thumbsup](https://hub.docker.com/r/thumbsupgallery/thumbsup/)) which pre-packages all the dependencies above. Read the [thumbsup on Docker ](https://thumbsup.github.io/docs/2-installation/docker/ ) documentation for more detail.
```bash
docker run -v `pwd` :/work thumbsupgallery/thumbsup [...]
```
2017-09-12 02:36:27 +00:00
2016-11-04 00:31:35 +00:00
## Command line arguments
2014-04-17 11:26:18 +00:00
2016-11-11 20:38:27 +00:00
This reflects the CLI for the latest code on `master` .
2016-11-04 00:31:35 +00:00
For the latest published version please refer to the [docs on the website ](https://thumbsup.github.io ).
2014-04-21 09:39:48 +00:00
2016-11-04 00:31:35 +00:00
<!-- START cli -->
2014-04-21 09:39:48 +00:00
```
2016-10-13 12:13:04 +00:00
2018-05-14 20:09:40 +00:00
Usages:
thumbsup [required] [options]
thumbsup --config config.json
2016-11-04 00:31:35 +00:00
Required:
--input Path to the folder with all photos/videos [string] [required]
--output Output path for the static website [string] [required]
2019-01-08 20:45:02 +00:00
Input options:
--include-photos Include photos in the gallery [boolean] [default: true]
--include-videos Include videos in the gallery [boolean] [default: true]
--include-raw-photos Include raw photos in the gallery [boolean] [default: false]
2019-01-23 21:52:30 +00:00
--include Glob pattern of files to include [array]
--exclude Glob pattern of files to exclude [array]
2019-01-08 20:45:02 +00:00
2017-03-08 11:18:05 +00:00
Output options:
2019-02-07 21:08:38 +00:00
--thumb-size Pixel size of the square thumbnails [number] [default: 120]
2020-10-22 11:35:07 +00:00
--small-size Pixel height of the small photos [number] [default: 300]
2019-02-07 21:08:38 +00:00
--large-size Pixel height of the fullscreen photos [number] [default: 1000]
--photo-quality Quality of the resized/converted photos [number] [default: 90]
--video-quality Quality of the converted video (percent) [number] [default: 75]
--video-bitrate Bitrate of the converted videos (e.g. 120k) [string] [default: null]
--video-format Video output format [choices: "mp4", "webm"] [default: "mp4"]
2020-11-02 22:29:38 +00:00
--video-stills Where the video still frame is taken [choices: "seek", "middle"] [default: "seek"]
--video-stills-seek Number of seconds where the still frame is taken [number] [default: 1]
2019-02-07 21:08:38 +00:00
--photo-preview How lightbox photos are generated [choices: "resize", "copy", "symlink", "link"] [default: "resize"]
--video-preview How lightbox videos are generated [choices: "resize", "copy", "symlink", "link"] [default: "resize"]
--photo-download How downloadable photos are generated [choices: "resize", "copy", "symlink", "link"] [default: "resize"]
--video-download How downloadable videos are generated [choices: "resize", "copy", "symlink", "link"] [default: "resize"]
--link-prefix Path or URL prefix for "linked" photos and videos [string]
--cleanup Remove any output file that's no longer needed [boolean] [default: false]
--concurrency Number of parallel parsing/processing operations [number] [default: 4]
2019-02-15 06:58:52 +00:00
--output-structure File and folder structure for output media [choices: "folders", "suffix"] [default: "folders"]
2019-02-07 21:08:38 +00:00
--gm-args Custom image processing arguments for GraphicsMagick [array]
--watermark Path to a transparent PNG to be overlaid on all images [string]
--watermark-position Position of the watermark [choices: "Repeat", "Center", "NorthWest", "North", "NorthEast", "West", "East", "SouthWest", "South", "SouthEast"]
2017-03-08 11:18:05 +00:00
Album options:
2018-05-14 20:09:40 +00:00
--albums-from How files are grouped into albums [array] [default: ["%path"]]
2017-02-05 07:36:03 +00:00
--sort-albums-by How to sort albums [choices: "title", "start-date", "end-date"] [default: "start-date"]
2016-11-04 00:31:35 +00:00
--sort-albums-direction Album sorting direction [choices: "asc", "desc"] [default: "asc"]
--sort-media-by How to sort photos and videos [choices: "filename", "date"] [default: "date"]
--sort-media-direction Media sorting direction [choices: "asc", "desc"] [default: "asc"]
2019-07-08 18:57:29 +00:00
--home-album-name Name of the top-level album [string] [default: "Home"]
2020-11-02 22:46:11 +00:00
--album-page-size Max number of files displayed on a page [number] [default: null]
2019-06-05 20:45:02 +00:00
--album-zip-files Create a ZIP file per album [boolean] [default: false]
2021-01-12 22:41:58 +00:00
--include-keywords Keywords to include in %keywords [array]
--exclude-keywords Keywords to exclude from %keywords [array]
--include-people Names to include in %people [array]
--exclude-people Names to exclude from %people [array]
2020-12-30 15:53:15 +00:00
--album-previews How previews are selected [choices: "first", "spread", "random"] [default: "first"]
2017-03-08 11:18:05 +00:00
Website options:
2019-07-08 18:57:29 +00:00
--index Filename of the home page [string] [default: "index.html"]
--albums-output-folder Output subfolder for HTML albums (default: website root) [string] [default: "."]
2019-04-29 17:28:25 +00:00
--theme Name of a built-in gallery theme [choices: "classic", "cards", "mosaic", "flow"] [default: "classic"]
2018-06-03 07:18:10 +00:00
--theme-path Path to a custom theme [string]
2018-05-15 18:32:42 +00:00
--theme-style Path to a custom LESS/CSS file for additional styles [string]
2019-06-05 20:45:02 +00:00
--theme-settings Path to a JSON file with theme settings [string]
2019-07-08 18:57:29 +00:00
--title Website title [string] [default: "Photo album"]
--footer Text or HTML footer [string] [default: null]
2017-03-08 11:18:05 +00:00
--google-analytics Code for Google Analytics tracking [string]
2019-01-07 20:48:44 +00:00
--embed-exif Embed the exif metadata for each image into the gallery page [boolean] [default: false]
2019-07-08 18:56:16 +00:00
--locale Locale for regional settings like dates [string] [default: "en"]
2020-11-02 22:29:38 +00:00
--seo-location Location where the site will be hosted. If provided, sitemap.xml and robots.txt will be created. [string] [default: null]
2017-03-08 11:18:05 +00:00
2019-01-08 20:45:02 +00:00
Misc options:
2020-12-30 15:53:15 +00:00
--config JSON config file (one key per argument) [string]
--database-file Path to the database file [string]
--log-file Path to the log file [string]
--log Print a detailed text log [choices: "default", "info", "debug", "trace"] [default: "default"]
--usage-stats Enable anonymous usage statistics [boolean] [default: true]
--dry-run Update the index, but don't create the media files / website [boolean] [default: false]
2019-01-08 20:45:02 +00:00
2017-05-25 11:43:03 +00:00
Deprecated:
2019-02-07 21:08:38 +00:00
--original-photos Copy and allow download of full-size photos [boolean]
--original-videos Copy and allow download of full-size videos [boolean]
2019-02-15 06:58:52 +00:00
--albums-date-format How albums are named in < date > mode [moment.js pattern]
2019-02-07 21:08:38 +00:00
--css Path to a custom provided CSS/LESS file for styling [string]
--download-photos Target of the photo download links [choices: "large", "copy", "symlink", "link"]
--download-videos Target of the video download links [choices: "large", "copy", "symlink", "link"]
--download-link-prefix Path or URL prefix for linked downloads [string]
2017-05-25 11:43:03 +00:00
2017-03-08 11:18:05 +00:00
Options:
2019-01-08 20:45:02 +00:00
--version Show version number [boolean]
--help Show help [boolean]
2018-05-14 20:09:40 +00:00
2016-11-04 00:31:35 +00:00
2018-05-14 20:09:40 +00:00
The optional JSON config should contain a single object with one key
per argument, not including the leading "--". For example:
{ "sort-albums-by": "start-date" }
2016-10-13 12:13:04 +00:00
```
2016-11-04 00:31:35 +00:00
<!-- END cli -->
2014-04-17 11:26:18 +00:00
2016-11-04 00:31:35 +00:00
## Contributing
2014-04-17 11:26:18 +00:00
2017-03-08 10:47:06 +00:00
We welcome all [issues ](https://github.com/thumbsup/thumbsup/issues )
and [pull requests ](https://github.com/thumbsup/thumbsup/pulls )!
2017-02-28 07:07:25 +00:00
2017-08-15 08:48:37 +00:00
If you are facing any issues or getting crashes, please try the following options to help troubleshoot:
2017-02-28 07:07:25 +00:00
```bash
2018-05-15 06:29:07 +00:00
thumbsup [options] --log debug
2017-08-15 08:48:37 +00:00
# [16:04:56] media/thumbs/photo-1446822622709-e1c7ad6e82d52.jpg [started]
# [16:04:57] media/thumbs/photo-1446822622709-e1c7ad6e82d52.jpg [completed]
2018-05-15 06:29:07 +00:00
thumbsup [options] --log trace
2017-08-15 08:48:37 +00:00
# [16:04:56] media/thumbs/photo-1446822622709-e1c7ad6e82d52.jpg [started]
# gm "identify" "-ping" "-format" "%[EXIF:Orientation]" [...]
# gm "convert" "-quality" "90" "-resize" "x400>" "+profile" [...]
# [16:04:57] media/thumbs/photo-1446822622709-e1c7ad6e82d52.jpg [completed]
2017-02-28 07:07:25 +00:00
```
2017-11-25 11:29:21 +00:00
If you want to contribute some code, please check out the [contributing guidelines ](.github/CONTRIBUTING.md )
for an overview of the design and a run-through of the different automated/manual tests.
