skycober / nginx-video-thumbextractor-module

Nginx module to extract thumbs from a video file

Nginx Video Thumb Extractor Module

Video Thumb Extractor is a module to extract an image from a video frame from a specific second resizing/cropping it to a given size.
The smallest generated image is 16x16 pixels.

This module is not distributed with the Nginx source. See the installation instructions.

Available on github at nginx-video-thumbextractor-module

Status

This module is considered production ready.

Requirements

This module depends from some libraries (headers and shared objects) which has to be installed before it:

• avformat >= 53.4.0 (tested versions: 53.4.0, 53.5.0) – commonly distributed with FFmpeg
• avcodec >= 53.7.0 (tested versions: 53.7.0, 53.8.0) – commonly distributed with FFmpeg
• avutil >= 51.9.1 (tested versions: 51.9.1, 51.30.0) – commonly distributed with FFmpeg
• swscale >= 2.0.0 (tested versions: 2.0.0) – commonly distributed with FFmpeg
• jpeg – libjpeg
• MagickWand – commonly distributed with ImageMagick

To install FFmpeg from source with the specified versions follow the steps bellow:

  git clone git://git.videolan.org/ffmpeg
  cd ffmpeg
  git checkout n0.8.7 -b tag_n0.8.7
  ./configure --prefix=/usr --disable-ffserver --disable-ffplay --enable-shared
  make clean && make
  make install

Recommendation

By default ImageMagick uses OpenMP to process images in threads.
I recommend to configure/compile ImageMagick using the option —disable-openmp since that is not a good idea use threads inside workers.

Supported Video Formats

This module uses the libraries avcodec and avformat to read the video files. Any supported video format for these libraries will work.
Tested formats was mp4, mov and flv.

Installation

Install the above requirements and follow the steps bellow.

    # clone the project
    git clone http://github.com/wandenberg/nginx-video-thumbextractor-module.git
    NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH=$PWD/nginx-video-thumbextractor-module

    # get desired nginx version (tested with 1.0.x series)
    wget http://nginx.org/download/nginx-1.0.10.tar.gz

    # unpack, configure and build
    tar xzvf nginx-1.0.10.tar.gz
    cd nginx-1.0.10
    # configure nginx specifying the path where are MagickWand headers
    ./configure --add-module=../nginx-video-thumbextractor-module --with-cc-opt='-I /usr/include/ImageMagick'
    make

    # install and finish
    sudo make install

    # check
    sudo /usr/local/nginx/sbin/nginx -v
        nginx version: nginx/1.0.10

    # test configuration
    sudo /usr/local/nginx/sbin/nginx -c $NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH/nginx.conf -t
        the configuration file $NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH/nginx.conf syntax is ok
        configuration file $NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH/nginx.conf test is successful

    # run
    sudo /usr/local/nginx/sbin/nginx -c $NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH/nginx.conf

Basic Configuration

    location ~ /thumbs(.*) {
        video_thumbextractor;
        video_thumbextractor_video_filename    $1;
        video_thumbextractor_video_second      $arg_second;
        video_thumbextractor_image_width       $arg_width;
        video_thumbextractor_image_height      $arg_height;
    }

Basic Usage

Assuming that you have a file called video.mp4 on your root folder use a browser to test the following urls:

  # get an image from second 10 with the original size
  http://localhost/thumbs/video.mp4?second=10

  # get an image from second 20 with a 50px of height and proportional width keeping video scale
  http://localhost/thumbs/video.mp4?second=10&height=50

  # get an image from second 30 with a 50px of height and 100px of width, the image will be cropped to keep video scale
  http://localhost/thumbs/video.mp4?second=20&height=50&width=100

Directives

video_thumbextractor

syntax: video_thumbextractor

context: location

release version: 0.1.0

Set Video Thumb Extractor as the request handler for the location.

video_thumbextractor_video_filename

syntax: video_thumbextractor_video_filename filename

default: none

context: http

release version: 0.1.0

The video filename relative to root folder.
This directive is required.
Return a 404 if the video is not found.

video_thumbextractor_video_second

syntax: video_thumbextractor_video_second second

default: none

context: http

release version: 0.1.0

The time in seconds where the image should be extracted. The nearest key frame will be used to get the image.
This directive is required.
Return a 400 if the value is not specified.
Return a 404 if the second is not found (the video is shorter than the time specified).

video_thumbextractor_image_width

syntax: video_thumbextractor_image_width width

default: 0

context: http

release version: 0.1.0

The width used to generate the image.
This directive is optional.
If only the width is specified the video size will be used as image size.

video_thumbextractor_image_height

syntax: video_thumbextractor_image_height height

default: 0

context: http

release version: 0.1.0

The height used to generate the image.
This directive is optional.
If only the height is specified the width will be determined using video scale to keep the aspect.
If both, width and height, are specified the image will suffers a resize and an eventual crop to keep the aspect.

Contributors

People

Changelog

v0.1.0

• Initial release