Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Nginx module to extract thumbs from a video file
branch: master

README.textile

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 >= 55.12.100 (last tested version: 55.12.100, 55.33.100, 55.48.100) – commonly distributed with FFmpeg
  • avcodec >= 55.18.102 (last tested versions: 55.18.102, 55.52.102, 55.69.100) – commonly distributed with FFmpeg
  • avutil >= 52.38.100 (last tested versions: 52.38.100, 52.66.100, 52.92.100) – commonly distributed with FFmpeg
  • avfilter >= 3.79.101 (last tested versions: 3.79.101, 4.2.100, 4.11.100) – commonly distributed with FFmpeg
  • swscale >= 2.3.100 (last tested versions: 2.3.100, 2.5.102, 2.6.100) – commonly distributed with FFmpeg
  • jpeg – libjpeg

Recommendation

When installing FFmpeg (last tested versions: 2.0, 2.0.6, 2.2.2, 2.3.2) from source do not forget to enable shared libraries using —enable-shared

If you don’t install FFmpeg from source you need to be sure that you have headers files for the libs.

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 https://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
    ./configure --add-module=$NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH
    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.

video_thumbextractor_only_keyframe

syntax: video_thumbextractor_only_keyframe on|off

default: on

context: http

release version: 0.3.0

Set if only the keyframes should be used to create the image.
When set to off, the process will be a bit slower because the video will be decoded from the nearest keyframe up to the exact requested time.

video_thumbextractor_next_time

syntax: video_thumbextractor_next_time on|off

default: on

context: http

release version: 0.3.0

Set if will use the previous or the next keyframe considering the requested time when configured to use only the keyframes.

video_thumbextractor_tile_rows

syntax: video_thumbextractor_tile_rows number

default: none

context: http

release version: 0.6.0

Set the number of rows to be used on tile filter. The number of cols will be calculated using the sample interval, the video duration and the start time used on ‘video_second’ directive, if not set.

using only 1 row

video_thumbextractor_tile_cols

syntax: video_thumbextractor_tile_cols number

default: none

context: http

release version: 0.6.0

Set the number of cols to be used on tile filter. The number of rows will be calculated using the sample interval, the video duration and the start time used on ‘video_second’ directive, if not set.

using 2 cols

video_thumbextractor_tile_max_rows

syntax: video_thumbextractor_tile_max_rows number

default: none

context: http

release version: 0.6.0

Set the max number of rows to be used on tile filter when only the number of cols was set. After calculate the number of necessary rows it can be limited by the configured max number of rows.

using 2 cols limited on up to 2 rows

video_thumbextractor_tile_max_cols

syntax: video_thumbextractor_tile_max_cols number

default: none

context: http

release version: 0.6.0

Set the max number of cols to be used on tile filter when only the number of rows was set. After calculate the number of necessary cols it can be limited by the configured max number of cols.

using only 1 row limited on up to 5 cols

video_thumbextractor_tile_sample_interval

syntax: video_thumbextractor_tile_sample_interval number

default: none

context: http

release version: 0.6.0

Set the sample interval to get the frames for tile. When it was not set and the number of cols and rows were, the sample interval will be calculated to the video can fit on the tile layout.
When only the number of rows or the number of cols was set and sample interval was not, the module will use the default value of 5 seconds.
To the interval be respected you should set video_thumbextractor_only_keyframe directive to off.

using 2 cols and 2 seconds of interval

using 1 row and 2 seconds of interval

using 4 rows, 4 cols and calculated sample interval

using  4 rows, 4 cols and 3 seconds of interval

video_thumbextractor_tile_color

syntax: video_thumbextractor_tile_color string

default: none

context: http

release version: 0.6.0

Set the color to be used on the background. Valid values are defined here

using #EEAA33 as background color

video_thumbextractor_tile_margin

syntax: video_thumbextractor_tile_margin number

default: none

context: http

release version: 0.6.0

Set the size of the margin to be used on the final image.

using 5px of margin

video_thumbextractor_tile_padding

syntax: video_thumbextractor_tile_padding number

default: none

context: http

release version: 0.6.0

Set the size of the padding to be used between the frames.

using 3px of padding

video_thumbextractor_threads

syntax: video_thumbextractor_threads string

default: auto

context: http

release version: 0.6.0

Set the number of threads used by avcodec.

Contributors

People

Changelog

v0.6.0

  • add support to tile filter, used to make story boards or sprites
  • add directive to control the number of threads used by avcodec

v0.5.0

  • fix jpeg dpi configuration usage
  • remove support to old libav* libraries
  • remove MagickWand dependency which cause memory leak

v0.4.0

  • fix to proper read videos with the moov atom is at the end of the file
  • fix to use the nearest decoded frame, in the case of requested time is on the end of the video
  • fix CFLAGS, LDFLAGS and ngx_feature_libs to find the parameters to compile using right MagickWand lib version
  • using av_frame_alloc instead of avcodec_alloc_frame when available

v0.3.0

  • fix frame allocation assert
  • add configuration to choose between only keyframes or not, and if will use the previous or next frame relative to given time
  • make possible read the video from an nginx cache file

v0.2.0

  • fix use of deprecated functions

v0.1.0

  • Initial release
Something went wrong with that request. Please try again.