How to install the plugin - Piwigo/piwigo-videojs GitHub Wiki

Installation

Add the plugin to your Piwigo:

Use the Piwigo built-in plugin manager (preferred)
or git clone and move to your-gallery/plugins/ directory
or download from http://piwigo.org/ext/extension_view.php?eid=831 and move to your-gallery/plugins/ directory

Enable VideoJS from the Administration / Plugins section
Install the LocalFiles Editor plugin if it is not already installed
Configure your server with the LocalFiles Editor extension so that it accepts video files with the text below. It is highly recommended to not add the MOV format which is supported by only a very few web browsers.

    /* File extensions — to allow video and other file types */
    $conf['file_ext'] = array_merge(
        $conf['picture_ext'],
        array('heic','tif','tiff','mp4','m4v','mpg','ogg','ogv','webm','webmv')
    );
    $conf['graphics_library'] = 'ext_imagick';
    $conf['upload_form_all_types'] = true;

    /* File names — to allow special characters */
    $conf['sync_chars_regex'] = '/^[a-zA-Z0-9-_. ]+$/';

Add also these lines to add metadata support:

    /* VideoJS — to add video metadata support */
    $conf['show_exif'] = true;
    $conf['show_exif_fields'] = array(
      'date_creation',
      'formatprofile',
      'latitude',
      'longitude',
      'rotation',
      'Artist',
      'AspectRatio',
      'AudioBitsPerSample',
      'AudioChannels',
      'AudioCodecID',
      'AudioCodecInfo',
      'AudioSampleRate',
      'Author',
      'AvgBitrate',
      'Contrast',
      'DateTimeOriginal',
      'Description',
      'Duration',
      'DurationSeconds',
      'ExifVersion',
      'ExposureBiasValue',
      'ExposureMode',
      'ExposureProgram',
      'ExposureTime',
      'FileSize',
      'FileType',
      'Flash',
      'FNumber',
      'FocalLength',
      'FocalLengthIn35mmFilm',
      'Genre',
      'ISOSpeedRatings',
      'LightSource',
      'Make',
      'MeteringMode',
      'MIMEtype',
      'Model',
      'Resolution',
      'Saturation',
      'Sharpness',
      'Software',
      'Title',
      'VideoBitrate',
      'VideoCodecID',
      'VideoCodecInfo',
      'VideoFrameRate',
      'WhiteBalance',
    );

The above list is complete. Tag names in lower case are stored in the Piwigo database with image data and those in upper case are stored in a table managed by the plugin. You can remove from the above list the tag names of the metadata you are not interested in.

Requirements

VideoJS requires MediaInfo or ffprobe or Exiftool to retrieve metadata, and ffmpeg to produce posters and thumbnails:

If you can compile MediaInfo on your server, download the source code from the MediaInfo website. Add the necessary libraries if needed and compile it. Then, enter the path to the MediaInfo directory as shown below so that the plugin knows how to call it.
If you cannot compile software on your server for some reason, ExifTool is the solution because it is a platform-independent Perl library delivered with a command-line application. Download the ExifTool version corresponding to your server and make it executable. Then, enter the path to the ExifTool directory as shown below so that the plugin knows how to call it.
ffmpeg and ffprobe binaries (executables) can be downloaded from FFbinaries for most platforms. So in most cases, it is not necessary to compile the FFmpeg source code. Once it is installed and made executable, enter the path to the FFmpeg directory as shown below so that the plugin knows how to call it.

Copy/paste the below lines in LocalFiles Editor and replace the paths with those of your server. Put the lines in comment for the software that are not available (by adding // at the beginning):

    /* VideoJS — to gather metadata and produce thumbnails */
    // - requires 'MediaInfo' or 'ffprobe' or 'Exiftool' to sync metadata
    // - requires 'FFmpeg' to produce posters i.e. thumbnails
    // - define below the full path of the directories of the available executables
    //=> MediaInfo:
    //   1. download the source from https://mediaarea.net/en/MediaInfo/Download
    //   2. compile the source as explained here: https://github.com/MediaArea/MediaInfo
    //   3. check with './mediainfo --version' (on Linux)
    $conf['vjs_mediainfo_dir'] = '/home/clients/.../mediainfo/';
    //=> ExifTool:
    //   1. download the library and CLI from https://exiftool.org
    //   2. make it executable with e.g. chmod +x exiftool on Linux
    //   3. check it with e.g. './exiftool -ver' on Linux
    $conf['vjs_exiftool_dir'] = '/home/clients/.../exiftool/Image-ExifTool-13.11/';
    //=> FFmpeg:
    //   1. download binaries from https://ffbinaries.com/downloads or https://ffmpeg.org/download.html
    //   2. on Linux: make ffmpeg and ffprobe executable with:
    //      > chmod +x ffmpeg
    //      > chmod +x ffprobe
    //   3. check it with e.g. './ffmpeg -version' on Linux
    $conf['ffmpeg_dir'] = '/home/clients/.../ffmpeg/ffmpeg-7.0.2/';

If you encounter difficulties, for example to determine the full paths, add the following lines so that errors are displayed in the browser and logs are gathered in the _data/logs folder when you sync files:

$conf['log_level'] = 'DEBUG';
$conf['show_php_errors'] = E_ERROR;
$conf['show_php_errors_on_frontend'] = true;

Upload video posters manually

If you cannot install ExifTool, FFmpeg or MediaInfo, you must upload video posters manually to the appropriate pwg_representative folders created inside your virtual or normal albums as shown below:

galleries
└── Video Album
    ├── video1.mp4
    ├── video2.ogv
    ├── video3.webm
    └── pwg_representative
        ├── video1.jpg         -- Poster of Video1
        ├── video1.webm        -- Multiple source of Video1
        ├── video2.png         -- Poster of Video2
        ├── video2.mp4         -- Multiple source of Video2
        ├── video3.png         -- Poster of Video3
        └── video3.vtt         -- WEBVTT of Video3

piwigo
└── upload
    └── 2025
        └── 03
            └── 25
                ├── video1.mp4
                ├── video2.ogv
                ├── video3.webm
                └── pwg_representative
                    ├── video1.jpg         -- Poster of Video1
                    ├── video1.webm        -- Multiple source of Video1
                    ├── video2.png         -- Poster of Video2
                    ├── video2.mp4         -- Multiple source of Video2
                    ├── video3.png         -- Poster of Video3
                    └── video3.vtt         -- WEBVTT of Video3

You create the folder pwg_representative in the folder containing the videos and upload the posters in it. Then, from the Sync tab of the plugin interface, you launch a sync with the option "Adopt posters uploaded manually" enabled.

Troubleshooting

Storage

The videos must be encoded in a supported format (mp4, m4v, mpg, ogg, ogv, webm, webmv)
The filenames must not contain spaces nor special characters (unless you have configure it).
Multiple video sources must be stored in the pwg_representative folder.
Multiple video sources must have the same name as of the main video.
The poster must have the same size (width and height) as of the video.
The poster must have the same name (filename wo extension) of the video.
The poster must be stored in the pwg_representative folder.
The poster must be a valid .jpg or .png file.
The subtitles (WEBVTT) must be a valid .vtt file.

Playback issues

Native Browser: check that the video is compatible with your browser.
VideoJS player: check that your browser supports HTML5 video.

If necessary, convert your video with any software you wish. I recommend HandBrake as it allows converting videos from nearly any format to a selection of modern, widely supported codecs.

Your HTTP server might not be delivering the content with the correct MIME type. Verify that your server returns the correct MIME type, for example by using the following command or using the Web Console of your browser:

    $ wget -Sv -O /dev/null http://localhost/piwigo/galleries/videos/video1.ogv
    --2013-07-01 11:13:17--  http://localhost/piwigo/galleries/videos/video1.ogv
    Resolving localhost (localhost)... 127.0.0.1
    Connecting to localhost (localhost)|127.0.0.1|:80... connected.
    HTTP request sent, awaiting response...
    HTTP/1.1 200 OK
    ...
    Content-Type: video/ogg
    Length: 438268 (428K) [video/ogg]
    Saving to: ‘/dev/null’

You may also add the below lines in your .htaccess file (in Piwigo root directory) to send the correct mime-types to the browsers:

    AddType video/ogg .ogv
    AddType video/mp4 .mp4
    AddType video/webm .webm

Some web hosts, in trying to save bandwidth, gzip everything by default, including video files! This may prevent web browsers to play videos. You can switch off gzip in your .htaccess file by adding this line:

    SetEnvIfNoCase Request_URI \.(og[gv]|mp4|m4v|webm)$ no-gzip dont-vary