Allow videos support

[Gotcha26]

Video Support for PiwigoPublish

Date: 2026-02-15
Status: Feasible — Moderate development effort

---

Table of Contents

1. Overview
2. Lightroom Classic Side
3. Piwigo Server Side
4. Server Verification Guide
5. Piwigo Configuration Guide
6. Plugin Modifications
7. Limitations & Caveats
8. References

---

Overview

Publishing videos from Lightroom Classic to Piwigo is fully feasible. Both the Lightroom SDK and the Piwigo API support video handling, though both require explicit configuration. The current PiwigoPublish plugin has video support explicitly disabled — the changes needed are moderate and localized to 3 files.

---

Lightroom Classic Side

Video Export Capabilities

The Lightroom SDK natively supports video publication in Publish Services via the canExportVideo property. When enabled, Lightroom displays a "Video" section in the export/publish dialog.

Available Export Formats

Format	Description EN
H.264 (MP4)	Transcodes to MP4 H.264 + AAC. Quality presets: Max (4K), High, Medium, Low. Applies basic LrC adjustments.
DPX	Image sequence for professional/cinema use. Very large files. Not relevant here.
Original	Raw copy of the original file without any transcoding or adjustments.

Recommendation: H.264/MP4 is the ideal choice — universal browser compatibility and natively produced by Lightroom.

SDK API for Video Detection

-- Detect whether a rendition is a video
local fileFormat = photo:getRawMetadata("fileFormat")
local isVideo = (fileFormat == "VIDEO")

The processRenderedPhotos workflow is identical for photos and videos — no separate callback exists. The plugin must detect video renditions itself.

---

Piwigo Server Side

API Compatibility

The pwg.images.upload API endpoint accepts video files with the same parameters as photos, provided the server is configured to allow video extensions. There is no API difference between uploading a photo and a video.

Required Server Plugin

The piwigo-videojs plugin (official, GPL-3.0) is required for proper video playback in the gallery.

Features provided / Fonctionnalités fournies :

Feature / Fonctionnalité	Description EN
HTML5 Player	Integrates VideoJS player into the gallery
Metadata extraction	Reads filesize, dimensions, GPS, date, duration, bitrate, framerate
Poster/Thumbnail generation	Extracts a frame from the video via FFmpeg

What it does NOT do :

• No live transcoding
• No automatic format conversion
• No adaptive bitrate streaming (HLS/DASH)

File Storage

Videos follow the exact same directory structure as photos.

./upload/YYYY/MM/DD/
    video_file.mp4              ← original video file
./_data/i/upload/YYYY/MM/DD/
    video_file-th.jpg           ← thumbnail generated by VideoJS+FFmpeg

---

Server Verification Guide

1. Check FFmpeg Installation

FFmpeg is required on the Piwigo server for automatic thumbnail/poster generation from videos. Without it, videos will display with a generic placeholder.

Via SSH

# Check if FFmpeg is installed
ffmpeg -version

# Expected output (example)
# ffmpeg version 4.4.2 Copyright (c) 2000-2021 the FFmpeg developers
# built with gcc 11 ...

# If not found, check for avconv (legacy alternative)
avconv -version

Via Piwigo Admin Panel

1. Go to Administration > Plugins > VideoJS > Configuration

2. The plugin displays detected tools:

   • ✅ ffmpeg — Required for poster generation
   • ℹ️ exiftool — Optional, metadata extraction
   • ℹ️ mediainfo — Optional, metadata extraction

3. If FFmpeg is not detected, you'll see a warning.

Install FFmpeg (if missing)

# Debian / Ubuntu
sudo apt update && sudo apt install ffmpeg

# CentOS / RHEL
sudo yum install ffmpeg

# Alpine
apk add ffmpeg

# Verify after installation / Vérifier après installation
ffmpeg -version

Note: On shared hosting, FFmpeg may not be available and you cannot install it yourself. Contact your hosting provider.

2. Check PHP Upload Limits

Videos are significantly larger than photos. Ensure your PHP configuration allows large uploads.

# Check current limits
php -i | grep -E "upload_max_filesize|post_max_size|max_execution_time"

**Recommended values

Parameter	Recommended	File to edit
upload_max_filesize	512M or higher	php.ini
post_max_size	512M or higher	php.ini
max_execution_time	300 (5 min)	php.ini
memory_limit	256M or higher	php.ini

; In php.ini:
upload_max_filesize = 512M
post_max_size = 512M
max_execution_time = 300
memory_limit = 256M

Restart your web server after changes : sudo systemctl restart apache2 or sudo systemctl restart nginx && sudo systemctl restart php-fpm

3. Check piwigo-videojs Plugin

1. Go to Administration > Plugins

2. Search for VideoJS in the plugin list

3. If not installed: click Install then Activate

4. If installed but inactive: click Activate

---

Piwigo Configuration Guide

Step 1: Enable Video File Types

By default, Piwigo only accepts image files. You need to explicitly allow video extensions.

Method A: Via LocalFiles Editor (Recommended)

1. Go to Administration > Tools > LocalFiles Editor

2. Edit local/config/config.inc.php

3. Add the following lines:

<?php
// Enable all file types for upload
$conf['upload_form_all_types'] = true;

// Add video extensions
$conf['file_ext'] = array_merge(
    $conf['picture_ext'],
    array('mp4', 'm4v', 'mpg', 'ogg', 'ogv', 'webm', 'webmv')
);

1. Save the file

Method B: Via direct file editing

# Edit the local config file
nano /var/www/piwigo/local/config/config.inc.php

Add the same PHP code as above.

Step 2: Configure VideoJS Plugin

1. Go to Administration > Plugins > VideoJS > Configuration

2. Recommended settings :

Setting	Value	Description EN
Video player width	720	Default player width in pixels
Poster generation	Enabled	Auto-generate poster from video
Poster second	4	Frame to extract for poster (seconds)
Metadata sync	Auto	Auto-extract metadata on upload

Step 3: Synchronize Existing Videos

After uploading videos, you may need to trigger metadata extraction and poster generation.

1. Go to Administration > Tools > Batch Manager

2. Filter by video files

3. Select VideoJS — Synchronize metadata from the action menu

4. Apply to all selected videos

Quick Verification Checklist

[ ] FFmpeg installed and accessible
[ ] piwigo-videojs plugin installed & active
[ ] upload_form_all_types = true
[ ] Video extensions added to file_ext
[ ] PHP upload_max_filesize >= 512M
[ ] PHP post_max_size >= 512M
[ ] PHP max_execution_time >= 300
[ ] Test: manual video upload via Piwigo UI

---

Plugin Modifications

Files to Modify

File	Change	Impact
PublishServiceProvider.lua	Set canExportVideo = true, add allowVideoExportPresets	Enables video selection in LrC UI
PiwigoAPI.lua	Add video/mp4 content-type, remove file-type restriction	Allows video upload to Piwigo
PublishTask.lua	Detect video renditions, adapt metadata handling	Proper video processing in publish workflow

Detection Logic

-- In processRenderedPhotos
local fileFormat = rendition.photo:getRawMetadata("fileFormat")
local isVideo = (fileFormat == "VIDEO")

if isVideo then
    -- Video-specific handling
    -- - Limited EXIF metadata
    -- - Content-type: video/mp4
    -- - File extension must be preserved
end

---

Limitations & Caveats

#	EN
1	File size: Videos are much larger than photos (100s of MB to GBs). The existing chunked upload will help.
2	Limited metadata: Videos don't have full EXIF data (no lens/camera info). Title, caption, keywords, and date are available.
3	File extension: The uploaded filename must retain its extension (e.g., .mp4). Without it, Piwigo rejects the upload.
4	No server-side transcoding: Piwigo streams the video as-is. The format sent by Lightroom must be browser-compatible (H.264/MP4 is).
5	FFmpeg dependency: Without FFmpeg on the server, video thumbnails won't be auto-generated. Videos will show a generic placeholder.
6	MOV format discouraged: MOV has poor browser support. Prefer MP4. If users export as "Original" and the source is MOV, playback may fail.

---

References

• piwigo-videojs — GitHub
• Configure Piwigo for Uploading Videos
• Piwigo — Compatible file formats
• Piwigo API — pwg.images.upload
• Lightroom Classic SDK — Export Service Provider
• Adobe — Supported video formats in Lightroom Classic

[Gotcha26]

Video Support for PiwigoPublish

Date: 2026-02-16
Status: Implemented and tested
Requires: Lightroom Companion plugin (Piwigo side)

---

Table of Contents

1. What This Feature Does
2. Architecture Overview
3. The Lightroom Companion Plugin
4. How It Works
5. Setup Guide
6. Pros and Cons
7. Shared Hosting Considerations
8. Known Limitations
9. Technical Reference
10. References

---

What This Feature Does

PiwigoPublish can now publish videos alongside photos to a Piwigo gallery. Videos are detected automatically, validated against the server's capabilities, and uploaded using the same workflow as photos.

The feature is opt-in and guarded: video upload only works when the Piwigo server has the Lightroom Companion plugin installed, activated, and configured. Without it, videos are silently blocked before any rendering or uploading occurs.

Key Behaviour

• Videos in the publish batch are detected before Lightroom starts rendering
• If the server is not ready, videos are removed from the batch instantly (no transcoding delay)
• Photos in the same batch are still published normally
• A dialog informs the user which videos were blocked and why

---

Architecture Overview

graph TB
    subgraph "Lightroom Classic"
        LR_UI["Publish Service UI"]
        LR_PRE["Pre-scan<br/><code>photosToExport()</code>"]
        LR_CHECK{"Server<br/>video-ready?"}
        LR_REMOVE["Remove videos<br/><code>removePhoto()</code>"]
        LR_RENDER["Render & Upload<br/>photos + allowed videos"]
        LR_SKIP["Skip batch entirely<br/>(only videos, all blocked)"]
    end

    subgraph "Piwigo Server"
        PW_COMP["Lightroom Companion<br/>plugin"]
        PW_API["pwg.companion.getConfig"]
        PW_VJS["VideoJS plugin"]
        PW_UPLOAD["pwg.images.addSimple"]
        PW_STORE["Upload directory<br/><code>./upload/YYYY/MM/DD/</code>"]
    end

    LR_UI --> LR_PRE
    LR_PRE -->|"videos found"| LR_CHECK
    LR_PRE -->|"no videos"| LR_RENDER
    LR_CHECK -->|"call API"| PW_API
    PW_API --> PW_COMP
    LR_CHECK -->|"blocked"| LR_REMOVE
    LR_REMOVE -->|"only videos in batch"| LR_SKIP
    LR_REMOVE -->|"mixed batch"| LR_RENDER
    LR_CHECK -->|"allowed"| LR_RENDER
    LR_RENDER -->|"upload"| PW_UPLOAD
    PW_UPLOAD --> PW_STORE
    PW_VJS -.->|"generates thumbnail"| PW_STORE

Loading

---

The Lightroom Companion Plugin

The Lightroom Companion is a small Piwigo plugin (lightroom-companion/) that acts as the bridge between the Lightroom plugin and the Piwigo server. It exposes server diagnostics and provides one-click video configuration.

What It Provides

Feature	Description
Server diagnostics API	pwg.companion.getConfig returns PHP limits, graphics libs, FFmpeg status, Piwigo config, and video readiness
One-click video setup	pwg.companion.enableVideoSupport writes upload_form_all_types and video extensions to local/config/config.inc.php
Admin page	Dashboard showing all server diagnostics with an "Enable Video Support" button
VideoJS detection	Checks if the VideoJS player plugin is installed and active

Why a Companion Plugin?

Without a server-side component, the Lightroom plugin cannot reliably determine whether the server will accept video uploads. Attempting to upload a video to an unconfigured server results in:

• Silent failures (no error message, just a broken entry)
• Wasted bandwidth (large file uploaded for nothing)
• Confused users (the photo appears "published" but shows no content)

The Companion plugin solves this by providing a pre-flight check before any upload occurs.

Files

lightroom-companion/
├── main.inc.php    # Plugin bootstrap: admin menu + API method registration
├── admin.php       # Admin controller: server diagnostics + enable video action
└── admin.tpl       # Smarty template: admin UI with light/dark theme support

---

How It Works

Pre-scan Flow (Before Rendering)

sequenceDiagram
    participant LR as Lightroom Classic
    participant PS as PiwigoPublish Plugin
    participant PW as Piwigo Server
    participant LC as Lightroom Companion

    LR->>PS: User clicks "Publish"
    PS->>PS: photosToExport() — scan batch

    alt No videos in batch
        PS->>PS: Skip video checks
    else Videos detected
        PS->>PW: pwg.companion.getConfig
        PW->>LC: Gather server info
        LC-->>PW: PHP limits, FFmpeg, video_ready
        PW-->>PS: Server config response

        alt Companion absent
            PS->>LR: ⛔ "Companion plugin not installed"
            PS->>PS: removePhoto() for all videos
        else video_ready = false
            PS->>LR: ⛔ "Video upload not authorized"
            PS->>PS: removePhoto() for all videos
        else video_ready = true
            PS->>PS: Check per-file size limits
            PS->>PS: Proceed with upload
        end
    end

    alt Only videos (all blocked)
        PS->>LR: Return immediately (no rendering)
    else Mixed batch or videos allowed
        PS->>LR: Enter render loop (photos + allowed videos)
    end

Loading

Blocking Conditions

Videos are blocked when any of these conditions is true:

Condition	Message shown to user
Companion plugin not installed on server	"The 'Lightroom Companion' plugin is not installed on your Piwigo server"
Companion installed but video_ready = false	"Video upload not authorized" + details on what's missing
Video file exceeds server upload limit	"Video too large: X MB (limit: Y MB)"
Cannot reach server to verify	"Cannot verify server video support (connection issue)"

What Happens to Blocked Videos?

• They are removed from the export session before rendering starts
• No transcoding, no rendering, no bandwidth used
• They remain in the "To Publish" list in Lightroom (they were never published)
• The user can retry after configuring the server

---

Setup Guide

Step 1: Install Lightroom Companion on Piwigo

1. Copy the lightroom-companion/ folder to your Piwigo plugins/ directory
2. In Piwigo admin: Plugins > Installed Plugins > find "Lightroom Companion" > click Activate

Step 2: Enable Video Support

Option A: Via the Companion admin page

1. Go to Plugins > Lightroom Companion in the Piwigo admin menu
2. Review the server diagnostics
3. Click "Enable Video Support"
4. The plugin writes the necessary configuration to local/config/config.inc.php

Option B: Via Lightroom

1. In Lightroom Classic, go to your Publish Service settings
2. Click "Server Info"
3. If the Companion is detected and video is not yet enabled, use the "Enable Video Support" button

Option C: Manual configuration

Edit local/config/config.inc.php on your server:

<?php
$conf['upload_form_all_types'] = true;
$conf['file_ext'] = array_merge(
    $conf['picture_ext'],
    array('mp4', 'm4v', 'ogg', 'ogv', 'webm')
);

Step 3: Install VideoJS (Recommended)

1. In Piwigo admin: Plugins > Browse > search "VideoJS" > Install > Activate
2. Without VideoJS, uploaded videos will not play in the browser gallery

Step 4: Verify PHP Upload Limits

Videos are much larger than photos. Ensure your PHP allows large uploads:

Parameter	Minimum	Recommended
upload_max_filesize	50M	512M
post_max_size	50M	512M
max_execution_time	120	300

The Companion admin page displays these values. If they're too low, edit your php.ini or .htaccess.

Quick Checklist

• Lightroom Companion installed and activated on Piwigo
• Video support enabled (via Companion admin or manual config)
• VideoJS plugin installed and active
• PHP upload limits adequate for your video sizes
• (Optional) FFmpeg installed on server for automatic thumbnails

---

Pros and Cons

Pros

	Benefit
Unified workflow	Photos and videos publish through the same Lightroom interface
Safe by default	Videos are blocked unless the server is explicitly configured
Zero wasted time	Blocked videos are removed before rendering (no transcoding delay)
Smart batch handling	Mixed batches work: photos upload normally, blocked videos are skipped
One-click setup	The Companion plugin configures the server automatically
Size validation	Videos exceeding server limits are caught before upload

Cons

	Limitation
Requires server plugin	The Lightroom Companion must be installed on Piwigo
No transcoding on server	Piwigo streams videos as-is; the format must be browser-compatible
Large file sizes	Videos consume significant disk space and bandwidth
No chunked upload	The current pwg.images.addSimple does not support chunked upload; large videos may timeout
Limited metadata	Videos have limited EXIF data compared to photos (no lens, aperture, ISO)
FFmpeg optional	Without FFmpeg, no automatic thumbnail — videos display a generic placeholder

---

Shared Hosting Considerations

Publishing videos to a shared hosting server requires extra caution. Shared environments have limited resources and strict usage policies.

Resource Impact

graph LR
    subgraph "What happens when you upload a video"
        A["Video Upload<br/>200 MB file"] --> B["PHP Process<br/>holds memory"]
        B --> C["Disk Write<br/>200 MB to upload/"]
        C --> D["VideoJS trigger<br/>(if FFmpeg available)"]
        D --> E["FFmpeg<br/>CPU-intensive<br/>thumbnail generation"]
    end

    subgraph "Shared hosting limits"
        F["CPU quota<br/>(may kill process)"]
        G["Memory limit<br/>(128M-256M typical)"]
        H["Disk quota<br/>(fills fast with videos)"]
        I["Execution time<br/>(30-120s typical)"]
    end

    B -.->|"may exceed"| G
    C -.->|"fills"| H
    E -.->|"may trigger"| F
    B -.->|"may exceed"| I

Loading

Risks and Mitigations

Risk	What happens	Mitigation
Upload timeout	PHP kills the process mid-upload, corrupt file on server	Keep videos under 100 MB; export at "Medium" quality in Lightroom
Memory exhaustion	PHP runs out of memory handling the upload	Check memory_limit; some hosts enforce 128 MB
CPU spike from FFmpeg	Hosting provider throttles or kills the process	FFmpeg is optional — disable poster generation in VideoJS settings
Disk quota exceeded	Server runs out of space; Piwigo stops working	Monitor disk usage; consider cloud/VPS for video-heavy galleries
Hosting provider alert	Sustained high CPU/bandwidth triggers automated warnings	Upload videos in small batches (2-3 at a time), not bulk
Execution time limit	max_execution_time too low for large uploads	Some hosts ignore .htaccess overrides; contact provider

Best Practices for Shared Hosting

flowchart TD
    A["Want to publish videos?"] --> B{"What type of hosting?"}

    B -->|"Shared hosting"| C["Keep videos small"]
    C --> C1["Export at Medium quality<br/>(720p, ~50-100 MB)"]
    C1 --> C2["Upload 2-3 videos at a time"]
    C2 --> C3["Avoid peak hours"]
    C3 --> C4["Monitor disk usage"]

    B -->|"VPS / Dedicated"| D["More freedom"]
    D --> D1["Export at High/Max quality"]
    D1 --> D2["Install FFmpeg for thumbnails"]
    D2 --> D3["Increase PHP limits freely"]
    D3 --> D4["Batch upload is fine"]

    B -->|"Cloud hosting"| E["Best option for video"]
    E --> E1["Scalable resources"]
    E1 --> E2["No CPU throttling concerns"]

Loading

Golden rules for shared hosting:

1. Export at "Medium" quality (720p) in Lightroom — this reduces file size from 500+ MB to ~50-100 MB
2. Publish 2-3 videos per batch, not 20 at once — spreads the load over time
3. Avoid FFmpeg if your host has strict CPU limits — a generic thumbnail is better than a killed process
4. Check your disk quota before uploading — 10 videos at 100 MB = 1 GB of disk space consumed
5. Test with one video first — verify the full round-trip works before bulk publishing

---

Known Limitations

#	Limitation	Detail
1	No chunked upload	pwg.images.addSimple sends the entire file in one POST. For very large files (>500 MB), this may timeout. A future improvement could use pwg.images.upload with chunk support.
2	No server-side transcoding	Piwigo plays the video as-is. If the user exports as "Original" and the source is a non-browser-friendly format (e.g., ProRes MOV), playback will fail. Always export as H.264/MP4.
3	MOV format	MOV has inconsistent browser support. Lightroom's H.264 export produces MP4, which works everywhere. "Original" export of a MOV source is risky.
4	No local pre-processing	Videos are uploaded as Lightroom renders them. There is no local compression, thumbnail generation, or metadata extraction before upload. This is a potential future improvement.
5	skipRender() does not work	The Lightroom SDK's rendition:skipRender() cannot be called inside the renditions() loop. The plugin uses exportSession:removePhoto() before the loop instead.
6	FFmpeg absence is silent	If FFmpeg is not installed on the server, videos upload successfully but have no custom thumbnail. The information is available in the Companion admin page.
7	DPX format disabled	Only H.264 (MP4) and Original are offered as video export presets. DPX produces image sequences, which is not useful for web galleries.

---

Technical Reference

Lightroom SDK Methods Used

Method	Purpose
lrPhoto:getRawMetadata("fileFormat")	Returns "VIDEO" for video files
exportSession:photosToExport()	Iterates photos before rendering starts
exportSession:removePhoto(photo)	Removes a photo/video from the session (no rendering occurs)
exportSession:countRenditions()	Total items in the batch
rendition:waitForRender()	Waits for Lightroom to finish rendering (fallback for size check)

Piwigo API Methods

Method	Purpose
pwg.companion.getConfig	Returns full server diagnostics (PHP, FFmpeg, video config, VideoJS status)
pwg.companion.enableVideoSupport	Writes video extensions and upload_form_all_types to local config
pwg.images.addSimple	Uploads the video file (same endpoint as photos)

Plugin Files Modified

File	Changes
PublishServiceProvider.lua	Added canExportVideo = true, allowVideoExportPresets (H.264, Original)
PublishTask.lua	Pre-scan with photosToExport(), server check via Companion API, removePhoto() for blocked videos, per-file size validation
PiwigoAPI.lua	Added getServerVideoSupport() function
PublishDialogSections.lua	FFmpeg notice in Server Info dialog
utils.lua	Added parsePhpSize() for PHP notation conversion

Companion Plugin Files

File	Role
main.inc.php	Registers admin menu and API methods (pwg.companion.getConfig, pwg.companion.enableVideoSupport)
admin.php	Admin controller: gathers diagnostics, handles "Enable Video Support" action
admin.tpl	Smarty template: admin UI with light/dark theme support

---

References

• piwigo-videojs — GitHub
• Configure Piwigo for Uploading Videos
• Piwigo — Compatible file formats
• Piwigo API — pwg.images.upload
• Lightroom Classic SDK — Export Service Provider
• Adobe — Supported video formats in Lightroom Classic