Skip to main content

Gallery

The Gallery page manages photo collections used for screensavers, digital photo frames, and background images in GEM user interfaces. Gallery photos can be displayed when UIs are idle or as decorative backgrounds.

Overview​

Gallery features include:

  • Photo Upload: Upload multiple images at once
  • UI-Specific Galleries: Different photo collections per UI
  • Path Configuration: Specify local or network photo directories
  • Batch Management: Select and delete multiple photos
  • Preview: Full-screen photo preview
  • Screensaver Integration: Automatic slideshow on idle timeout

Interface Layout​

The Gallery page includes:

Header Section:

  • UI selector
  • Gallery path configuration
  • Screen timeout action configuration

Toolbar:

  • Upload controls
  • Selection controls
  • Delete button
  • Status indicators

Gallery Grid:

  • Thumbnail display of all photos
  • Checkbox selection
  • Click to preview

Configuration​

UI Selector​

Select which UI to manage gallery for:

  • Each UI can have its own gallery path
  • Photos are UI-specific
  • Change UI to manage different galleries
  • An open link beside the picker opens the selected UI's record in a modal — useful for adjusting its timeout attributes without leaving the gallery or losing a pending upload

Example:

Kitchen Panel: Family photos
Living Room Panel: Vacation photos
Guest Room Panel: Landscape photos

Directory containing gallery photos. Left empty, it is the gallery folder in the GEM install root, which is where uploads land by default.

Path Input:

  • A relative path resolves against the GEM install root — photos means <install>/photos
  • An absolute path is used as-is, for a NAS mount or an existing photo library
  • Must be accessible to the GEM server

Save Button:

  • Click to save path for selected UI
  • Path stored as UI attribute: gallery_photo_path

Examples:

Install-relative (recommended):

gallery
photos/family

Absolute / network share:

/mnt/nas/photos/living_room
/media/photos/screensaver

Requirements:

  • Directory must exist, or will be created on first upload
  • GEM must have read permissions
  • Supported image formats: JPG, PNG, GIF, WEBP
danger
Never point the gallery inside static/

Everything under static/ is served by the web server without authentication — that is correct for theme artwork and icons, but it would make personal photographs readable by anyone who can reach the controller, signed in or not.

Gallery photos are deliberately kept outside the web root and delivered to clients over the authenticated connection instead. Keep them there.

How photos reach the screen​

Photos are read by an authenticated request scoped to the configured gallery directory — a client can only ever fetch a photo that is directly inside that folder. Subdirectories are not traversed, and paths that resolve outside the folder are refused.

This is why the gallery does not use the ordinary image proxy: that proxy is restricted to static/, and the gallery lives outside it on purpose.

Screen Timeout Action​

Configure what happens when UI is idle:

Options:

  • not_set - No action on timeout
  • gallery - Show photo gallery slideshow
  • blackout - Turn off the screen
  • none - Keep the current page displayed

How It Works:

  1. User idle for configured timeout period (set in UI attributes: screen_timeout)
  2. Selected action executes automatically
  3. Gallery action:
    • Starts photo slideshow
    • Shows photos from gallery path
    • Cycles through photos at configured interval
    • Touch/click to exit back to normal UI

Save Button:

  • Click to save timeout action for selected UI

Uploading Photos​

Upload Interface​

File Input:

  • Supports multiple file selection
  • Hold Ctrl/Cmd to select multiple files
  • Or drag-and-drop (if supported by browser)

Upload Button:

  • Click to upload selected files
  • Progress indicator shows upload status
  • Success/error messages for each file

Upload Process​

  1. Select UI to upload to
  2. Verify Gallery Path is set
  3. Click file input or drag files
  4. Select photos
  5. Click Upload button
  6. Photos upload to configured gallery path
  7. Gallery refreshes showing new photos

Uploading requires an admin sign-in, and photos can only be written into a gallery directory that is actually configured on a UI — the folder in the Gallery Path field of some UI, or the default gallery folder in the install root. Any other destination is refused, so a gallery has to be configured before it can be filled.

Supported Formats:

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • GIF (.gif)
  • WEBP (.webp)

File Size Recommendations:

  • Max: 5MB per photo
  • Recommended: 1-2MB (good quality, reasonable size)
  • For large displays: 1920x1080 or higher resolution
  • For tablets: 1280x720 adequate

Batch Upload​

Upload multiple photos at once:

  1. Select 10, 20, or 100+ photos
  2. Click Upload
  3. All photos upload sequentially
  4. Success message shows count uploaded

Managing Photos​

Photos display in a responsive grid:

  • Thumbnails show image preview
  • Checkbox in top-left corner
  • Click thumbnail to full-screen preview
  • Hover effects indicate interactivity

Selecting Photos​

Individual Selection:

  • Click checkbox on each photo
  • Selected photos highlighted

Select All:

  • Click Select All button
  • All photos selected

Deselect All:

  • Click Deselect All button
  • All selections cleared

Selection Count:

  • Toolbar shows count: "X selected"

Previewing Photos​

Click any photo thumbnail to:

  • Open full-screen preview
  • View photo at full resolution
  • Click anywhere to close preview

Deleting Photos​

  1. Select photos with checkboxes
  2. Click Delete Selected button
  3. Confirm deletion
  4. Selected photos permanently deleted from gallery path

Deleting requires an admin sign-in, and only removes files from inside the configured gallery directory. The toast reports how many were actually removed — if any fail, it says so and names the first reason rather than reporting a clean sweep.

Warning: Deletion is permanent. Consider backing up photos before deleting.

When screen timeout action is set to "gallery":

Slideshow Behavior​

Activation:

  • User idle for timeout period (e.g., 5 minutes)
  • Gallery slideshow starts automatically

Display:

  • Photos shown full-screen
  • Transitions between photos (fade, slide, etc.)
  • Photo changes every 5-15 seconds (configurable)
  • Random or sequential order

Controls:

  • Touch/click anywhere to exit
  • Returns to previous UI page
  • Resets idle timeout

Configuration​

Set in UI attributes:

// Timeout before screensaver starts
screen_timeout: 300  // 5 minutes in seconds

// What to do on timeout
screen_timeout_action: "gallery"

// Gallery slideshow settings
gallery_interval: 10  // Seconds per photo
gallery_transition: "fade"  // Transition effect
gallery_shuffle: true  // Random order

Common Workflows​

Setting Up Screensaver​

For a wall-mounted tablet:

  1. Select UI: Wall Panel
  2. Set Gallery Path: /mnt/photos/family
  3. Click Save next to gallery path
  4. Set Screen Timeout Action: gallery
  5. Click Save next to timeout action
  6. Upload photos to gallery
  7. Configure timeout in UI attributes: screen_timeout: 180 (3 minutes)

Result: After 3 minutes of inactivity, family photos display as slideshow.

Creating Digital Photo Frame​

For dedicated photo frame display:

  1. Create UI: photo_frame
  2. Set minimal navigation (or none)
  3. Set gallery path to photo collection
  4. Upload photos
  5. Set screen timeout to very short (30-60 seconds)
  6. Set timeout action to gallery
  7. Set timeout action to gallery
  8. Assign to dedicated tablet/display

Result: Display shows photos almost constantly, with brief UI access if touched.

For different rooms with different photo sets:

Living Room:

UI: living_room_panel
Gallery Path: /mnt/photos/family

Guest Room:

UI: guest_room_panel
Gallery Path: /mnt/photos/landscapes

Master Bedroom:

UI: master_bedroom_panel
Gallery Path: /mnt/photos/memories

Each room shows appropriate photo collection.

  1. Create seasonal photo directories:

    /mnt/photos/spring
    /mnt/photos/summer
    /mnt/photos/fall
    /mnt/photos/winter

  2. Update gallery path seasonally:

    • March: /mnt/photos/spring
    • June: /mnt/photos/summer
    • September: /mnt/photos/fall
    • December: /mnt/photos/winter

  3. Or create macro to switch paths automatically

Photo Sources​

Local Storage​

Photos stored on GEM server:

Advantages:

  • Fast loading
  • No network dependency
  • Full control

Disadvantages:

  • Limited by server disk space
  • Manual upload required

Setup:

  1. Create directory on server
  2. Upload photos via Gallery page
  3. Or copy photos directly to server filesystem

Network Storage (NAS)​

Photos stored on network-attached storage:

Advantages:

  • Large capacity
  • Centralized storage
  • Easy management from computer
  • Can update photos without accessing GEM

Disadvantages:

  • Network dependency
  • Slower than local
  • Requires NAS configuration

Setup:

  1. Mount NAS share on GEM server:

    sudo mkdir /mnt/nas_photos
    sudo mount -t cifs //nas.local/photos /mnt/nas_photos -o username=user,password=pass

  2. Set gallery path: /mnt/nas_photos/family

  3. Photos load from NAS

Cloud Storage​

Photos from cloud services (Google Photos, Dropbox, etc.):

Options:

  1. Sync to Local: Use rclone or similar to sync cloud photos to local directory
  2. Direct Access: Use API to fetch photos (requires custom widget)

Photo Organization​

Directory Structure​

A gallery is a flat folder: only the images sitting directly in the configured directory are shown. Subdirectories are not searched, so a tree is a way to keep several collections side by side rather than a way to group one gallery.

/mnt/photos/
├── family/
│   ├── 2023/
│   ├── 2024/
│   └── favorites/
├── vacation/
│   ├── beach/
│   ├── mountains/
│   └── europe/
└── seasonal/
    ├── spring/
    ├── summer/
    ├── fall/
    └── winter/

Point the gallery path at the leaf directory holding the photos — /mnt/photos/family/2024, not /mnt/photos/family. Pointing at a parent that only contains folders shows an empty gallery.

Naming Conventions​

Use descriptive filenames:

2024-01-15_family_dinner.jpg
vacation_beach_sunset.jpg
spring_garden_tulips.jpg

Benefits:

  • Easy to identify in gallery
  • Chronological sorting if dated
  • Searchable names

Performance Considerations​

Photo Optimization​

Before uploading:

  1. Resize: Match display resolution

    • 1920x1080 for full HD displays
    • 1280x720 for tablets
    • Smaller for mobile

  2. Compress: Reduce file size without quality loss

    • Use tools like ImageOptim, TinyPNG
    • Target: 500KB - 2MB per photo

  3. Format: Choose appropriate format

    • JPEG for photos
    • PNG for images with transparency

Recommendations:

  • Small Gallery: 20-50 photos
  • Medium Gallery: 50-200 photos
  • Large Gallery: 200-1000 photos

Performance Impact:

  • Loading time increases with gallery size
  • Memory usage for thumbnail generation
  • Consider multiple smaller galleries instead of one huge gallery

Caching​

GEM caches photo thumbnails for fast display:

  • First load generates thumbnails
  • Subsequent loads use cached versions
  • Cache refreshes when photos change

Slideshow Customization​

Configure slideshow behavior via UI attributes:

Timing​

gallery_interval: 10  // Seconds per photo (default: 10)

Recommendations:

  • Fast slideshow: 5 seconds
  • Normal: 10-15 seconds
  • Slow/relaxed: 20-30 seconds

Transition Effects​

gallery_transition: "fade"  // or "slide", "none"

Options:

  • fade - Crossfade between photos
  • slide - Slide left/right
  • none - Instant change

Display Order​

gallery_shuffle: true  // Random order (default: false = sequential)

Random: Different order each slideshow Sequential: Alphabetical by filename

Additional Options​

gallery_show_filename: true    // Show filename overlay
gallery_show_exif: true        // Show photo date/time from EXIF
gallery_fit: "contain"         // or "cover" - how photo fits screen

Advanced Topics​

External Photo APIs​

Integrate with external photo services:

Google Photos:

  1. Create widget that fetches from Google Photos API
  2. Authenticate with API key
  3. Fetch photos from shared album
  4. Display in widget

Flickr, Instagram, etc.:

  • Similar approach with respective APIs
  • Store API keys in secure attributes
  • Refresh periodically

Dynamic Galleries​

Change gallery content based on:

Time of Day:

  • Morning: Bright, energetic photos
  • Evening: Calm, relaxing photos
  • Night: Dark, low-light photos

Season:

  • Spring: Flowers, gardens
  • Summer: Beach, outdoor
  • Fall: Foliage, harvest
  • Winter: Snow, holidays

Events:

  • Holidays: Holiday-themed photos
  • Birthdays: Birthday photos
  • Anniversaries: Special occasion photos

Implement with macros or scheduled tasks that update gallery_photo_path.

Create custom widgets to display gallery photos:

<script>
    import {onMount} from 'svelte';
    let photos = [];
    let currentIndex = 0;

    onMount(async () => {
        photos = await GemApp.getInstance().getGalleryPhotos();

        // Rotate every 10 seconds
        setInterval(() => {
            currentIndex = (currentIndex + 1) % photos.length;
        }, 10000);
    });
</script>

{#if photos.length}
    <img src={photos[currentIndex]} alt="Gallery" />
{/if}

Photo Metadata​

Store metadata in filenames or EXIF:

Filename Metadata:

2024-01-15_location-hawaii_category-vacation.jpg

EXIF Metadata:

  • Date taken
  • Camera model
  • GPS coordinates
  • Tags/keywords

Widget can parse and use metadata for:

  • Filtering by category
  • Sorting by date
  • Grouping by location
  • Displaying captions

Troubleshooting​

Check:

  1. Path Exists: Verify directory exists on server
  2. Permissions: GEM has read permissions on directory
  3. Photos Exist: Directory contains photos — directly, not in a subfolder
  4. Format: Files are JPG, PNG, GIF or WEBP
  5. UI Selected: Correct UI selected

Photos Not Uploading​

Check:

  1. Path Set: Gallery path must be configured on the UI first — an upload to a directory no UI is configured for is refused ("destination is not a configured gallery directory")
  2. Admin Session: Uploading and deleting require an elevated sign-in
  3. Path Writable: GEM has write permissions
  4. Disk Space: Server has sufficient free space
  5. File Size: Individual files under size limit
  6. Format: JPG, PNG, GIF and WEBP only

Slideshow Not Starting​

Check:

  1. Timeout Action: Set to "gallery" (not "not_set")
  2. Timeout Value: screen_timeout attribute set
  3. Photos Available: Gallery has photos
  4. Path Valid: Gallery path points to valid directory
  5. UI Idle: User actually idle for timeout period

Poor Slideshow Performance​

Causes:

  • Photos too large (file size or resolution)
  • Too many photos loading at once
  • Network latency (if using network storage)

Solutions:

  1. Resize photos to display resolution
  2. Compress photos to reduce file size
  3. Use local storage instead of network
  4. Reduce gallery size

Cannot Delete Photos​

Check:

  1. Admin Session: Deleting requires an elevated sign-in
  2. Permissions: GEM has write permissions on gallery directory
  3. File Locks: Photos not open in another application
  4. Network: Network path accessible

The toast reports the number actually removed and names the first failure, so a photo that could not be deleted is never reported as deleted.

Wrong Photos Showing​

Check:

  1. UI Selected: Viewing correct UI's gallery
  2. Path: Gallery path points to correct directory
  3. Cache: Clear browser cache
  4. Refresh: Reload gallery list

Best Practices​

Photo Selection​

  1. Quality: Use high-quality photos appropriate for display size

  2. Orientation: Mix of landscape and portrait, or match display orientation

  3. Content: Choose appropriate content for location

    • Public areas: Generic, safe-for-work
    • Private areas: Personal, family photos

  4. Quantity: 20-100 photos prevents repetition without being overwhelming

  5. Curation: Remove blurry, duplicate, or poor-quality photos

Directory Management​

  1. Dedicated Directory: Don't share with other applications

  2. Backup: Back up photos separately from GEM

  3. Organization: Use subdirectories for categories

  4. Naming: Use consistent, descriptive filenames

  5. Permissions: Set appropriate read/write permissions

Performance​

  1. Optimize Photos: Resize to display resolution before upload

  2. Compress: Use 80-90% JPEG quality

  3. Limit Size: Keep gallery under 500 photos

  4. Local Storage: Prefer local over network for performance

  5. Preload: System preloads next photo for smooth transitions

Use Cases​

Family Photo Frame​

Wall-mounted tablet displaying family photos:

UI: family_room_panel
Gallery Path: /mnt/nas/photos/family
Screen Timeout: 60 seconds
Timeout Action: gallery
Gallery Interval: 15 seconds
Gallery Shuffle: true

Result: Shows family photos continuously, with 60-second access to controls if touched.

Lobby Display​

Commercial lobby showing company photos:

UI: lobby_display
Gallery Path: /opt/gem/gallery/company
Screen Timeout: 30 seconds
Timeout Action: gallery
Gallery Interval: 20 seconds
Show Filename: false

Upload photos of:

  • Company milestones
  • Team photos
  • Product images
  • Office locations

Vacation Rental​

Different photo sets per rental unit:

Unit 1:
  UI: unit_1_panel
  Gallery Path: /mnt/photos/unit_1
  Photos: Beach, sunset, property exterior

Unit 2:
  UI: unit_2_panel
  Gallery Path: /mnt/photos/unit_2
  Photos: Mountain, hiking, property views

Each unit shows location-appropriate imagery.

Integration with Other Features​

Backgrounds and wallpaper​

Gallery photos are not usable as theme or widget backgrounds. The gallery deliberately lives outside the web root so photos are not readable without a session, which means there is no URL a stylesheet or a widget can point at — a background image has to be a file the web server publishes.

Use the right home for the job:

WantPut the image here
Screensaver slideshowThe gallery directory (this page)
Background for a page or routeThe theme's backgrounds folder, via the Themes editor
Wallpaper a user or a UI can pickThe theme's backgrounds folder, or static/backgrounds/ for a theme-independent set — see Personal Settings

The same photo can of course be placed in both, and a photo intended as wallpaper rather than as slideshow content belongs in one of the background folders only.

Event-Triggered Galleries​

Change gallery path based on events:

Example: Holiday photos during December

// In macro or trigger
if (currentMonth === 12) {
    await GemApp.getInstance().setAttribute('ui', uiId, 'gallery_photo_path', '/mnt/photos/holidays');
}

Advanced Topics​

Automated Photo Sync​

Sync photos from cloud storage automatically:

Using rclone:

# Cron job to sync Google Photos to local gallery
0 2 * * * rclone sync googlephotos:album/Family /mnt/photos/family

Using rsync:

# Sync from another server
0 3 * * * rsync -av user@nas:/photos/ /mnt/photos/

Photo Rotation​

Automatically rotate through different galleries:

Monthly Rotation:

  1. Create galleries for each month
  2. Macro runs on 1st of each month
  3. Updates gallery_photo_path attribute
  4. New photos displayed

Event-Based:

  • Birthdays: Show birthday photos
  • Anniversaries: Show anniversary photos
  • Seasons: Show seasonal photos

Metadata Display​

Show photo information in slideshow:

Configure via attributes:

gallery_show_filename: true
gallery_show_date: true
gallery_show_location: true  // From EXIF GPS

Requires custom slideshow component or theme JavaScript.