react-liquid-photos

KO | EN

gitlite — search

#javascript #python #go #android #machine-learning #linux #docker #nodejs #macos #windows #cli #kubernetes #security #open-source

react-liquid-photos

(★ 20)

Liquid Photos is a Photo Viewer for your server with tree folder structure and thousands of scans in seconds

react-liquid-photos 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# <img src="public/logo.svg" alt="Liquid Photos" width="32" height="32" style="vertical-align: middle; margin-right: 8px;" /> Liquid Photos

A fast, modern photo and video viewer application built with React and Node.js.

## Features

- **Fast Image Loading**: Optimized image serving with multiple resolution levels
- **Responsive Design**: Works seamlessly on desktop and mobile devices
- **User Authentication**: Secure login system with user management
- **Folder Navigation**: Browse media organized in folders
- **Full-Screen Viewer**: High-quality image viewing with optimization options
- **Download Support**: Download original quality images
- **Video Playback (HLS)**: Built-in player with HLS streaming for smooth video playback
- **Touch Gestures**: Intuitive swipe controls for mobile devices
- **Loading States**: Smooth loading indicators for thumbnails and navigation
- **Multi-Select**: Select multiple photos for batch download
- **Sharing Links**: Generate shareable links for photos and videos folders
  - Click the share button in the full-screen viewer to generate a direct link
  - Share links provide direct access to media without requiring authentication
  - Perfect for sharing photos with friends and family
- **Favorites**: Add photos and videos to your favorites collection
  - Click the heart icon in the full-screen viewer to add/remove from favorites
  - Access your favorite media through the dedicated favorites section
  - Quick way to organize and find your most cherished photos and videos
- **PWA Support**: Install as a Progressive Web App
  - Install Liquid Photos directly to your device's home screen
  - Native app-like experience with full-screen mode
- **Admin Tools**:
  - "Scan Media" menu with **Full Rescan** and **Scan Path** (admin-only)
  - Create users with an **Admin** toggle
  - Default admin from env (`ADMIN_USER`) cannot be deleted; other admins can
  - Optional per-user library scope via `root_path`

## Screenshots

### Desktop
<img width="1470" height="864" alt="Screenshot 2025-08-22 at 2 28 57 PM" src="https://github.com/user-attachments/assets/850a6c8b-2460-4e22-b02e-d83f69b21bac" />

### Mobile

## Touch Interactions

Liquid Photos provides intuitive touch gestures for mobile devices, making it easy to navigate and interact with your media library.

### Full-Screen Viewer Gestures

- **Swipe Left/Right**: Navigate between photos
  - Swipe left to go to the next photo
  - Swipe right to go to the previous photo
  - Works anywhere in the full-screen viewer area

- **Swipe Down**: Close panels or exit viewer
  - If info panel is open: closes the info panel
  - If info panel is closed: exits the full-screen viewer

### Grid View Interactions

- **Tap**: Open photo in full-screen viewer
- **Multi-select**: Tap photos to select multiple items for batch download
- **Responsive Design**: Optimized for both portrait and landscape orientations

## Image & Video Optimization

The application includes intelligent optimization to improve loading times, especially when accessing your library remotely.

### Resolution Levels

1. **Thumbnails** (`/thumb/:id`): Small WebP images (default width 512px) for grid view
2. **Optimized View** (`/view/:id`): Medium-resolution WebP images (default width 1920px) for full-screen viewing
3. **Full Resolution** (`/media/:id`): Original media for high-quality viewing
4. **Download** (`/download/:id`): Original media for download

### Viewer Controls

- **Optimized Mode** (default): Fast loading with good quality for most viewing needs
- **Full Resolution Mode**: Toggle to view original quality images when needed
- **Download Button**: Always downloads the original full-quality file

### Loading States

- **Thumbnail Loading**: Smooth skeleton loading with spinners while thumbnails load
- **Tree Navigation**: Loading indicators when switching between folder and date views
- **Error Handling**: Graceful fallbacks for failed image loads

## Admin: Scan Media

- **Full Rescan**: Re-index the entire library
- **Scan Path**: Re-index only a selected folder path (useful after adding/renaming a folder)
- Renamed folders: scanning now prunes stale entries so only the new folder name is shown
- "Scan Media" controls are visible to admins only

**If videos are not playing in Optimized (HLS) mode:**
- Switch to "Original" mode using the quality toggle button in the video player
- This bypasses HLS processing and uses direct video streaming
- Works for all video formats and resolutions

## System Dependencies

Install these on the host (for Docker images, they are included):

- `ffmpeg` – video thumbnails and HLS support
- `exiftool` – EXIF extraction and RAW preview
- `libheif` / `heif-convert` – HEIC/HEIF preview (optional but recommended)

## Development (local)

Prerequisites:
- Docker

1. Run from your project folder root which has Dockerfile:
```bash
docker build -t liquid-photos:latest .

docker stop liquid-photos || true
docker rm liquid-photos

docker run -d \
  --name liquid-photos \
  --restart unless-stopped \
  -p 6363:6363 \
  -e HOST=0.0.0.0 \
  -e PORT=6363 \
  -e ADMIN_USER=admin \
  -e ADMIN_PASS=admin123 \
  -v "/Users/m4air/Pictures":/pictures:ro \  # <- Change it your local pictures folder
  -v "/Users/m4air/liquid-photos-cache":/app/.cache \   # <- Change it your local cache folder
  liquid-photos:latest

```

2. Open `http://localhost:6363`

## Deploy to Server using Docker

### Docker Compose

Use home folders appropriate to your OS.

```yaml
version: "3.8"
services:
  liquid-photos:
    image: nikunjsingh/liquid-photos:latest
    container_name: liquid-photos
    restart: unless-stopped
    environment:
      HOST: "0.0.0.0"
      PORT: "6363"
      ADMIN_USER: "admin" # <— change this to your admin user
      ADMIN_PASS: "admin123" # <— change this to your admin pass
    ports:
      - "6363:6363"
    volumes:
      # Linux (example)
      - /home/youruser/Pictures:/pictures:ro # <— change this to your Pictures/Videos folder
      - /home/youruser/.liquid-photos-cache:/app/.cache # <— change this to your preferred cache folder for thumbnails/DB
      # macOS (example)
      # - /Users/youruser/Pictures:/pictures:ro
      # - /Users/youruser/.liquid-photos-cache:/app/.cache
      # Windows (example; Docker Desktop)
      # - C:/Users/youruser/Pictures:/pictures:ro
      # - C:/Users/youruser/.liquid-photos-cache:/app/.cache
```

Start with:
```bash
docker compose up -d
```

### Docker Run

Linux/macOS example:
```bash
docker run -d \
  --name liquid-photos \
  --restart unless-stopped \
  -p 6363:6363 \
  -e HOST=0.0.0.0 \
  -e PORT=6363 \
  -e ADMIN_USER=admin \ # <— change this to your admin user
  -e ADMIN_PASS=admin123 \ # <— change this to your admin pass
  -v "/home/youruser/Pictures":/pictures:ro \ # <— change this to your Pictures/Videos folder
  -v "/home/youruser/.liquid-photos-cache":/app/.cache \ # <— change this to your preferred cache folder for thumbnails/DB
  nikunjsingh/liquid-photos:latest
```

If your files are 200,000+ items and has videos, first Indexing can take upto 10 minutues. check Docker logs and wait for a message like "[index] done: 234,895 files in 694.5s" before going to the WEB UI

Dont make the cache folder your external HDD path as docker cant write to external HDDs

## Notes

- Default Admin admin cannot be deleted.
- For Docker, ensure Docker Desktop (macOS/Windows) has access to your host folders.
- When using **Scan Path** after renames, stale entries under the scanned (or nearest existing parent) directory are pruned from the DB so only the new folder name remains.

react-liquid-photos

react-liquid-photos 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

react-liquid-photos

react-liquid-photos 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README