Permalink
Browse files

updating documentation

  • Loading branch information...
1 parent 1a53e13 commit 6fdd9a629c6142ea5d6a32447b9ddec17693e5e5 @wandenberg committed Dec 5, 2011
Showing with 176 additions and 16 deletions.
  1. +176 −16 README
View
192 README
@@ -1,21 +1,181 @@
-nginx-video-thumbextractor-module
+h1(#nginx_video_thumbextractor_module). Nginx Video Thumb Extractor Module
-=============
-Requirements:
-=============
+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.
-lib avformat
-lib avcodec
-lib swscale
-lib jpeg
-GCC, make, the usual guys
+_This module is not distributed with the Nginx source. See "the installation instructions":installation._
+Available on github at "nginx-video-thumbextractor-module":repository
-================
-Developer Guide:
-================
-Install the above requirements.
-Download nginx server.
-Configure nginx using
- ./configure --add-module=<PATH_TO_MODULE_CODE>/nginx-video-thumbextractor-module
+h1(#status). Status
+
+This module is considered production ready.
+
+
+h1(#requirements). Requirements
+
+This module depends from some libraries which has to be installed before it, like:
+
+* avformat - commonly distributed with "FFmpeg":http://ffmpeg.org
+* avcodec - commonly distributed with "FFmpeg":http://ffmpeg.org
+* swscale - commonly distributed with "FFmpeg":http://ffmpeg.org
+* jpeg - "libjpeg":http://libjpeg.sourceforge.net
+* MagickWand - commonly distributed with "ImageMagick":http://www.imagemagick.org
+
+
+h1(#installation). Installation
+
+Install the above requirements and follow the steps bellow.
+
+<pre>
+ # 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
+</pre>
+
+h1(#basic-configuration). Basic Configuration
+
+<pre>
+ 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;
+ }
+</pre>
+
+
+h1(#basic-usage). Basic Usage
+
+Assuming that you have a file called _video.mp4_ on your root folder use a browser to test the following urls:
+
+<pre>
+ # 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
+</pre>
+
+
+h1(#directives). Directives
+
+
+h2(#video_thumbextractor). video_thumbextractor
+
+*syntax:* _video_thumbextractor_
+
+*context:* _location_
+
+*release version:* _0.1.0_
+
+Set Video Thumb Extractor as the request handler for the location.
+
+
+h2(#video_thumbextractor_video_filename). 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.
+
+
+h2(#video_thumbextractor_video_second). 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).
+
+
+h2(#video_thumbextractor_image_width). 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.
+
+
+h2(#video_thumbextractor_image_height). 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.
+
+
+h1(#contributors). Contributors
+
+"People":contributors
+
+
+h1(#changelog). Changelog
+
+h2(#0_1_0). v0.1.0
+
+* Initial release
+
+
+[repository]https://github.com/wandenberg/nginx-video-thumbextractor-module
+[installation]#instalation
+[contributors]https://github.com/wandenberg/nginx-video-thumbextractor-module/contributors

0 comments on commit 6fdd9a6

Please sign in to comment.