1h1(#nginx_video_thumbextractor_module). Nginx Video Thumb Extractor Module 2 3Video Thumb Extractor is a module to extract an image from a video frame from a specific second resizing/cropping it to a given size. 4The smallest generated image is ==16x16== pixels. 5 6_This module is not distributed with the Nginx source. See "the installation instructions":installation._ 7 8Available on github at "nginx-video-thumbextractor-module":repository 9 10 11h1(#status). Status 12 13This module is considered production ready. 14 15 16h1(#requirements). Requirements 17 18This module depends from some libraries (headers and shared objects) which has to be installed before it: 19 20* avformat >= 57.56.101 (last tested version: 57.56.101) - commonly distributed with "FFmpeg":http://ffmpeg.org 21* avcodec >= 57.64.101 (last tested versions: 57.64.101) - commonly distributed with "FFmpeg":http://ffmpeg.org 22* avutil >= 55.34.101 (last tested versions: 55.34.101) - commonly distributed with "FFmpeg":http://ffmpeg.org 23* avfilter >= 6.65.100 (last tested versions: 6.65.100) - commonly distributed with "FFmpeg":http://ffmpeg.org 24* swscale >= 4.2.100 (last tested versions: 4.2.100) - commonly distributed with "FFmpeg":http://ffmpeg.org 25* jpeg - "libjpeg":http://libjpeg.sourceforge.net 26 27 28h1(#recommendation). Recommendation 29 30When installing FFmpeg (last tested versions: 3.2.4) from source do not forget to enable shared libraries using _--enable-shared_ 31 32If you don't install FFmpeg from source you need to be sure that you have headers files for the libs. 33 34 35h1(#supported_video_formats). Supported Video Formats 36 37This module uses the libraries avcodec and avformat to read the video files. Any supported video format for these libraries will work. 38Tested formats was _mp4_, _mov_ and _flv_. 39 40 41h1(#installation). Installation 42 43Install the above requirements and follow the steps bellow. 44 45<pre> 46 # clone the project 47 git clone https://github.com/wandenberg/nginx-video-thumbextractor-module.git 48 NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH=$PWD/nginx-video-thumbextractor-module 49 50 # get desired nginx version (tested with 1.10.x series) 51 wget http://nginx.org/download/nginx-1.10.0.tar.gz 52 53 # unpack, configure and build 54 tar xzvf nginx-1.10.0.tar.gz 55 cd nginx-1.10.0 56 # configure nginx 57 ./configure --add-module=$NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH 58 make 59 60 # install and finish 61 sudo make install 62 63 # check 64 sudo /usr/local/nginx/sbin/nginx -v 65 nginx version: nginx/1.10.0 66 67 # test configuration 68 sudo /usr/local/nginx/sbin/nginx -c $NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH/nginx.conf -t 69 the configuration file $NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH/nginx.conf syntax is ok 70 configuration file $NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH/nginx.conf test is successful 71 72 # run 73 sudo /usr/local/nginx/sbin/nginx -c $NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH/nginx.conf 74</pre> 75 76 77h1(#basic-configuration). Basic Configuration 78 79<pre> 80 location ~ /thumbs(.*) { 81 video_thumbextractor; 82 video_thumbextractor_video_filename $1; 83 video_thumbextractor_video_second $arg_second; 84 video_thumbextractor_image_width $arg_width; 85 video_thumbextractor_image_height $arg_height; 86 } 87</pre> 88 89 90h1(#basic-usage). Basic Usage 91 92Assuming that you have a file called _video.mp4_ on your root folder use a browser to test the following urls: 93 94<pre> 95 # get an image from second 10 with the original size 96 http://localhost/thumbs/video.mp4?second=10 97 98 # get an image from second 20 with a 50px of height and proportional width keeping video scale 99 http://localhost/thumbs/video.mp4?second=10&height=50 100 101 # get an image from second 30 with a 50px of height and 100px of width, the image will be cropped to keep video scale 102 http://localhost/thumbs/video.mp4?second=20&height=50&width=100 103</pre> 104 105 106h1(#directives). Directives 107 108 109h2(#video_thumbextractor). video_thumbextractor 110 111*syntax:* _video_thumbextractor_ 112 113*context:* _location_ 114 115*release version:* _0.1.0_ 116 117Set Video Thumb Extractor as the request handler for the location. 118 119 120h2(#video_thumbextractor_video_filename). video_thumbextractor_video_filename 121 122*syntax:* _video_thumbextractor_video_filename filename_ 123 124*default:* _none_ 125 126*context:* _http_ 127 128*release version:* _0.1.0_ 129 130The video filename relative to root folder. 131This directive is required. 132Return a 404 if the video is not found. 133 134 135h2(#video_thumbextractor_video_second). video_thumbextractor_video_second 136 137*syntax:* _video_thumbextractor_video_second second_ 138 139*default:* _none_ 140 141*context:* _http_ 142 143*release version:* _0.1.0_ 144 145The time in seconds where the image should be extracted. The nearest key frame will be used to get the image. 146This directive is required. 147Return a 400 if the value is not specified. 148Return a 404 if the second is not found (the video is shorter than the time specified). 149 150 151h2(#video_thumbextractor_image_width). video_thumbextractor_image_width 152 153*syntax:* _video_thumbextractor_image_width width_ 154 155*default:* _0_ 156 157*context:* _http_ 158 159*release version:* _0.1.0_ 160 161The width used to generate the image. 162This directive is optional. 163If only the width is specified the video size will be used as image size. 164 165 166h2(#video_thumbextractor_image_height). video_thumbextractor_image_height 167 168*syntax:* _video_thumbextractor_image_height height_ 169 170*default:* _0_ 171 172*context:* _http_ 173 174*release version:* _0.1.0_ 175 176The height used to generate the image. 177This directive is optional. 178If only the height is specified the width will be determined using video scale to keep the aspect. 179If both, width and height, are specified the image will suffers a resize and an eventual crop to keep the aspect. 180 181 182h2(#video_thumbextractor_only_keyframe). video_thumbextractor_only_keyframe 183 184*syntax:* _video_thumbextractor_only_keyframe on|off_ 185 186*default:* _on_ 187 188*context:* _http_ 189 190*release version:* _0.3.0_ 191 192Set if only the keyframes should be used to create the image. 193When 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. 194 195 196h2(#video_thumbextractor_next_time). video_thumbextractor_next_time 197 198*syntax:* _video_thumbextractor_next_time on|off_ 199 200*default:* _on_ 201 202*context:* _http_ 203 204*release version:* _0.3.0_ 205 206Set if will use the previous or the next keyframe considering the requested time when configured to use only the keyframes. 207 208 209h2(#video_thumbextractor_tile_rows). video_thumbextractor_tile_rows 210 211*syntax:* _video_thumbextractor_tile_rows number_ 212 213*default:* _none_ 214 215*context:* _http_ 216 217*release version:* _0.6.0_ 218 219Set 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. 220 221 222h2(#video_thumbextractor_tile_cols). video_thumbextractor_tile_cols 223 224*syntax:* _video_thumbextractor_tile_cols number_ 225 226*default:* _none_ 227 228*context:* _http_ 229 230*release version:* _0.6.0_ 231 232Set 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. 233 234 235h2(#video_thumbextractor_tile_max_rows). video_thumbextractor_tile_max_rows 236 237*syntax:* _video_thumbextractor_tile_max_rows number_ 238 239*default:* _none_ 240 241*context:* _http_ 242 243*release version:* _0.6.0_ 244 245Set 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. 246 247 248h2(#video_thumbextractor_tile_max_cols). video_thumbextractor_tile_max_cols 249 250*syntax:* _video_thumbextractor_tile_max_cols number_ 251 252*default:* _none_ 253 254*context:* _http_ 255 256*release version:* _0.6.0_ 257 258Set 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. 259 260 261h2(#video_thumbextractor_tile_sample_interval). video_thumbextractor_tile_sample_interval 262 263*syntax:* _video_thumbextractor_tile_sample_interval number_ 264 265*default:* _none_ 266 267*context:* _http_ 268 269*release version:* _0.6.0_ 270 271Set 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. 272When 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. 273To the interval be respected you should set video_thumbextractor_only_keyframe directive to off. 274 275 276h2(#video_thumbextractor_tile_color). video_thumbextractor_tile_color 277 278*syntax:* _video_thumbextractor_tile_color string_ 279 280*default:* _none_ 281 282*context:* _http_ 283 284*release version:* _0.6.0_ 285 286Set the color to be used on the background. Valid values are defined "here":https://ffmpeg.org/ffmpeg-utils.html#Color 287 288 289h2(#video_thumbextractor_tile_margin). video_thumbextractor_tile_margin 290 291*syntax:* _video_thumbextractor_tile_margin number_ 292 293*default:* _none_ 294 295*context:* _http_ 296 297*release version:* _0.6.0_ 298 299Set the size of the margin to be used on the final image. 300 301 302h2(#video_thumbextractor_tile_padding). video_thumbextractor_tile_padding 303 304*syntax:* _video_thumbextractor_tile_padding number_ 305 306*default:* _none_ 307 308*context:* _http_ 309 310*release version:* _0.6.0_ 311 312Set the size of the padding to be used between the frames. 313 314 315h2(#video_thumbextractor_threads). video_thumbextractor_threads 316 317*syntax:* _video_thumbextractor_threads string_ 318 319*default:* _auto_ 320 321*context:* _http_ 322 323*release version:* _0.6.0_ 324 325Set the number of threads used by avcodec. 326 327 328h2(#video_thumbextractor_processes_per_worker). video_thumbextractor_processes_per_worker 329 330*syntax:* _video_thumbextractor_processes_per_worker number_ 331 332*default:* _1_ 333 334*context:* _http_ 335 336*release version:* _0.7.0_ 337 338Set the number of process each nginx worker can fork to extract the thumbs. The requests will be queued until there is an available process. 339 340 341h1(#contributors). Contributors 342 343"People":contributors 344 345 346h1(#changelog). Changelog 347 348h2(#0_9_0). v0.9.0 349* drop support to versions prior Nginx 1.10.0 and FFmpeg libraries prior to 3.2.4 350 351h2(#0_8_0). v0.8.0 352* add support to use dynamic values on tile configurations 353 354h2(#0_7_0). v0.7.0 355 356* add support to execute the thumb extraction in a different process to not block the nginx worker 357* add video_thumbextractor_processes_per_worker directive 358* try to make the code simpler 359* revert the changes on 0.6.2 360 361h2(#0_6_2). v0.6.2 362 363* trying to improve the performance not reading the raw response (the video) 364 365h2(#0_6_1). v0.6.1 366 367* add support to rotate the image when the video stream has instructions to do it 368* add support to videos with different aspect ratio 369* fix support to files with more than one video stream choosing the best of them 370 371h2(#0_6_0). v0.6.0 372 373* add support to tile filter, used to make story boards or sprites 374* add directive to control the number of threads used by avcodec 375 376h2(#0_5_0). v0.5.0 377 378* fix jpeg dpi configuration usage 379* remove support to old libav* libraries 380* remove MagickWand dependency which cause memory leak 381 382h2(#0_4_0). v0.4.0 383 384* fix to proper read videos with the moov atom is at the end of the file 385* fix to use the nearest decoded frame, in the case of requested time is on the end of the video 386* fix CFLAGS, LDFLAGS and ngx_feature_libs to find the parameters to compile using right MagickWand lib version 387* using av_frame_alloc instead of avcodec_alloc_frame when available 388 389h2(#0_3_0). v0.3.0 390 391* fix frame allocation assert 392* add configuration to choose between only keyframes or not, and if will use the previous or next frame relative to given time 393* make possible read the video from an nginx cache file 394 395h2(#0_2_0). v0.2.0 396 397* fix use of deprecated functions 398 399h2(#0_1_0). v0.1.0 400 401* Initial release 402 403 404[repository]https://github.com/wandenberg/nginx-video-thumbextractor-module 405[installation]#instalation 406[contributors]https://github.com/wandenberg/nginx-video-thumbextractor-module/contributors 407