From MythTV Official Wiki
Revision as of 08:29, 30 June 2016 by Stevegoodey (talk | contribs) (Typos)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Software-update-available.png This page is up-to-date as of MythTV version 0.28, the current release is 31.0


Image Gallery was introduced in core MythTV as of 0.28. It is a replacement for the MythGallery plugin, which is now deprecated.

It enables the organisation and viewing of photographs and videos. An image library is maintained as a directory structure within a storage group, which can be managed using basic cut/paste operations. Images on devices attached to a frontend (cameras, USB sticks, CD's etc) can also be viewed as well as imported and exported to/from the library.

Images are viewed in a thumbnail screen or as slideshows. Metadata from photos (EXIF) and videos (FFMPEG tags) can be displayed.

Image Library

The image library is stored in the Photographs storage group, configured via mythtv-setup, and is available to all frontends and the service API. Images on attached devices are only visible to the local frontend.

The storage group is synchronised to the database and a thumbnail cache (stored on the backend at <backend user>/.mythtv/tmp/Images). For initial setup, the storage group must be manually synchronised by scanning the storage group via the pop-up menu option. Thereafter Gallery will retain synchronisation automatically. If you modify the contents of the storage group manually or by using 3rd-party apps then you will need to re-scan.

The initial scan will take a while for large libraries, but you may exit Gallery to do other things whilst it is going. After the scan finishes, thumbnail generation will keep the backend busy for some time (about 300-500 images/min, much slower for videos), which may affect Gallery responsiveness. Scanning is a low-priority, background task and so shouldn't affect other backend tasks, such as recordings. However it would be wise to perform the initial scan whilst the backend is lightly loaded.

Gallery scans all local devices when it starts. Whilst running, newly inserted devices are detected and scanned automatically, via Myth's media monitor. To be detected, USB devices must be mounted on insertion, either by the OS (auto-mount) or the frontend (if it has privileges). Gallery can be configured to start automatically whenever a device containing images is inserted.

Local device images are synchronised to a temporary database and thumbnail cache (stored on the frontend at <frontend user>/.mythtv/tmp/Images), which persist until the device is ejected or the frontend exits.

For devices that don't provide a USB interface (such as iPhones), a user-defined "Import" command/script can be used to retrieve images by other tools. The command is executed in a new directory (created in system temp) which will be deleted when the frontend exits.

gphoto2 is one useful tool for this: an "Import" command of;-

gphoto2 --get-all-files

will copy/download all images from a wide range of cameras.

File Formats

Gallery recognises all image formats that are supported by Qt. RAW formats are not yet supported.

Supported video formats are those defined by the Video Library. All videos are played using the internal player.

Files of unsupported formats will not be shown, but will never be deleted. If you cannot delete an 'empty' directory, it is likely because it contains unrecognised files.

Scan exclusions

The exclusions are a comma-separated list of simple (glob) regular expressions specifying files to exclude. Files and directories that match any of the expressions will be ignored. Expressions are case-sensitive and you probably don't want any whitespace. Valid wildcards are '*' and '?' for a (single character).

Storage Group Structure

Gallery will merge multiple storage group directories to a single hierarchy. For example, if the storage group comprises 2 directories mediapath1 & mediaPath2 then images in mediaPath1/Holiday/ & mediaPath2/Holiday/ will be amalgamated into a single Gallery directory Photographs/Holiday. (mediaPath1/Holiday/ & mediaPath2/Holiday/ are considered "clone directories"). The info overlay shows the absolute filepath of the selected image/directory. For clone directories it will show the first path with "and others" to indicate there are others.

If an identical filepath exists in clones (for example, mediaPath1/Holiday/photo22.jpg & mediaPath2/Holiday/photo22.jpg) then the first file will be recognised and the second file will be ignored as a duplicate. The UI does not report duplicates; they are only reported in the backend log.

Data Integrity

Gallery only requires read-access to images. By policy it will never write Exif metadata to an image, because of risks associated to Makernotes and issues with timestamps. Effectively this only affects orientation. Setting Exif comments or editing metadata is beyond Gallery's remit as a viewer/organiser controlled by remote.

Write/execute access is assumed for directories to enable copy/move/delete operations.


Gallery reads EXIF metadata from images using libexiv2, and FFmpeg tags from videos using ffprobe. Orientation and image date are used for display and ordering. A caption is read from the EXIF "User Comment" or "Image Description" tags. Other fields are for informational display only.

If metadata is not available the file modification date is used instead. These are always displayed as a date rather than a date/time to enable easy differentiation.

Directories also show file modification date. Devices, including the "Photographs" storage group, show the time they were last scanned.


Although backups should be maintained, identifying missing images in a large library is problematic. Gallery provides an option to disable all functions that modify images and the database. By setting a password, all frontends become viewers (of non-hidden items) only. When the password is entered, edit privileges persist until Gallery exits.

Note the password does not provide security - it is intended as a UI idiot/child-lock only. It is stored in plain text in the settings table ("GalleryPassword") and will not prevent access/modification of images via Services API or the filesystem.

Thumbnail View

The main Gallery screen shows thumbnails of a single directory. The first/top left icon represents the ("parent") directory and is always followed by its sub-directories, then the images (incl videos) within it. Settings allow the sub-directories & images to be ordered separately and display separate caption types (None, Filename, Exif Image/File Date, Exif Comment).

Depending on the theme, the view may be zoomed in/out to vary the size & number of thumbnails displayed.

Selecting an image thumbnail will display it in Slideshow view. Selecting a sub-directory will descend to that directory. Selecting the parent directory (or EXIT) will ascend the tree and eventually exit the Gallery.

The "Gallery" icon is a virtual directory representing the root of the image tree. If the image library/storage group is defined (configured and has been scanned), it will be represented by a (virtual) "Photographs" sub-directory.

Icons for local devices and any defined imports will follow in the order of detection/creation.

If the storage group is not defined, and there are no local devices you will see an empty screen with a message.

If the storage group is defined but there are no local devices or imports, the top level "Gallery"/"Photographs" is skipped for convenience. Gallery will start directly in the "Photographs" directory and exit to main menu from there. However you can still ascend to the top level by selecting the "Photographs" directory rather than using EXIT.


There are 2 menu filters that can hide images from display. Both affect the local frontend only. Slideshows only display images that are currently visible.

One filter will show either pictures only, videos only or both pictures and videos. This filter may cause lots of directories to appear to be empty.

The 2nd filter toggles the display of images and directories that have been marked as hidden. An item's hidden state applies on all frontends. When a password has been set, this filter is disabled to prohibit the display of hidden items.


Directory stats show the number of images / sub-directories in the directory. Only visible, direct children are counted. The Info overlay shows the sub-tree totals.

By default, directories show 4 thumbnails from their contents. They are filled from the first 4 visible images, the first thumbnail of each visible sub-directory, the second thumbnail of each visible sub-directory and so on. The thumbnails may change when sort order or visibility filters change.

A directory can instead display the thumbnail of one of its direct child images/sub-dirs - a 'cover'. This is set by a menu action on the child item and cleared by menu action on the directory. If the cover image becomes invisible the directory will fallback to the default 4 thumbnails until it becomes visible again. To use an image at a deeper level the intervening sub-directory covers must be chained up the tree.


Images with orientation information (Exif.Image.Orientation or FFmpeg rotate) will be auto-rotated. Images may be rotated but the change is only recorded in the database - it will never be written to the image file.

Video thumbnails will also be auto-rotated. Upside-down videos (180° orientation) will be rotated when played. However portrait videos (90° or 270° orientation) cannot yet be rotated when played.


Images and directories may be marked to facilitate actions on groups of items (a form of group selection). When items are marked relevant actions will operate on the group of marked items rather than the single one highlighted. Unmark all items to regain normal operation.

Marked items always exist in the same directory: marking an item clears any previous markings in other directories. Thus there is no danger of performing actions on previously marked items that are not visible. The only exception is copy/move, which will operate on previously marked (off-screen) items to allow transfers between directories.


To copy/move, first mark the candidate items, then highlight the destination directory and select copy/move from the menu. The action will be attempted on every item and the number of failures reported. Failed items will remain marked. When copying directories, unrecognised files will be ignored.

Moves will attempt a filesystem rename where source and destination are on the same host but may fallback to a copy/delete if necessary. This means that moving a directory may fail to move unrecognised files.

Occasionally transfers fail purely because of a latency in the reported filesize of the destination file. Repeating the operation usually succeeds.


When a Settings->Import Command is defined, the root "Gallery" icon will show an Import menu action. The command/script is executed within a newly created temporary directory (in system tmp dir), which may be referenced via the token %TMPDIR%. The directory is considered to be a device that persists until the frontend exits. It may be deleted manually by ejecting the 'device'. An icon for the 'device' (named "Import mm:ss" from its creation time) will appear showing the directory contents.


The information overlay shows some basic file details with a subset of the most useful metadata tags of the selected image. It is not selectable/scrollable in the Thumbnail view. For directories the content count and size is shown. For local devices the free space is also shown.

Slideshow View

Shows images and plays videos full-screen. These images take longer to load from the storage group than the compact thumbnails, so you there may be a delay when displaying an image for the first time. Subsequent viewings will be faster because the frontend caches images. During this delay a "Loading" status is shown. If this irritates then increase the setting that suppresses the status display.


The view uses a buffer (hard-coded to 8 images) to enable accelerated viewing, although the effect is highly dependant on the time it takes your system to load images. When you navigate more quickly than images can load, the requests are buffered so that no images are missed, allowing you to flick through a slideshow quickly. When the buffer fills then subsequent images will be skipped to keep up with your keypresses, enabling you to skip through large collections. Transitions will accelerate to provide feedback.

For example, if you display image 1 and keep RIGHT pressed down, then images 2-9 are guaranteed to appear but will then be followed by (perhaps) image 19, 27, 40, etc.

Browse Mode

Selecting an image thumbnail will display it full-screen and allow you to browse the directory sequentially using LEFT/RIGHT. Videos will not play automatically but are marked so that you can play them with SELECT. By default transitions are used between slides but a setting will disable them for this mode. PLAY switches to an Ordered, Directory slideshow.

When browsing the slide count shows the position of the slide, as per thumbnail view.


A slideshow automatically displays a sequence of images that is determined the moment the slideshow starts. Thus it has a size and you can fast-forward and rewind to repeat earlier slides. Turn repeat on to generate continuous shows.

Shows start from the highlighted Thumbnail image and end at the previous image.

The slide count shows the position of the slide within the slideshow which does not relate to the position in Thumbnail view.

Directory slideshows select from the current directory. Recursive slideshows select from the subtree rooted at the highlighted directory.

Ordered shows slides in the same order as thumbnail view. Recursive shows images from a directory followed by a recursive show of each sub directory, in order.

Shuffled will show every slide once in a random order.

Random selects a random image for each slide. Some images in the set may not appear and some may be shown multiple times, although an image will never be shown adjacent to itself.

Seasonal is a random show that biases the randomised selection towards anniversaries of the current date. For example, at Christmas, images of previous Christmases are much more likely to be selected than June images.

When advancing beyond the end image (either manually or when repeat is on), shuffled and random shows will be regenerated to produce a different order.


Transitions using rotation are only available with the OpenGL painter.


The slideshow information overlay toggles between showing all metadata tags and a subset of the most useful metadata tags of the current image and is scrollable.

Key Bindings

Binding Description Default Key
PLAY Starts Directory Slideshow from Thumbnail view. Starts/stops running slideshows P
RECURSIVESHOW Starts Recursive Slideshow R
MARK Mark image for copy/move T
COVER Use image as directory cover or clear cover of a directory C
ROTRIGHT Rotate image right 90 degrees ],3
ROTLEFT Rotate image left 90 degrees [,1
FLIPHORIZONTAL Flip image horizontally
FLIPVERTICAL Flip image vertically
ZOOMOUT Zoom image out 7
ZOOMIN Zoom image in 9
FULLSIZE Reset zoom 0
SCROLLUP Scroll image up 2
SCROLLLEFT Scroll image left 4
SCROLLRIGHT Scroll image right 6
SCROLLDOWN Scroll image down 8
RECENTER Reset pan 5