Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 393 lines (213 sloc) 11.895 kB
6fdd9a6 @wandenberg updating documentation
authored
1 h1(#nginx_video_thumbextractor_module). Nginx Video Thumb Extractor Module
fe9f810 @wandenberg Initial version of nginx module to extract thumbs from a video file
authored
2
6fdd9a6 @wandenberg updating documentation
authored
3 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.
9406457 @wandenberg fix use of deprecated functions
authored
4 The smallest generated image is ==16x16== pixels.
fe9f810 @wandenberg Initial version of nginx module to extract thumbs from a video file
authored
5
6fdd9a6 @wandenberg updating documentation
authored
6 _This module is not distributed with the Nginx source. See "the installation instructions":installation._
fe9f810 @wandenberg Initial version of nginx module to extract thumbs from a video file
authored
7
6fdd9a6 @wandenberg updating documentation
authored
8 Available on github at "nginx-video-thumbextractor-module":repository
fe9f810 @wandenberg Initial version of nginx module to extract thumbs from a video file
authored
9
10
6fdd9a6 @wandenberg updating documentation
authored
11 h1(#status). Status
12
13 This module is considered production ready.
14
15
16 h1(#requirements). Requirements
17
9406457 @wandenberg fix use of deprecated functions
authored
18 This module depends from some libraries (headers and shared objects) which has to be installed before it:
6fdd9a6 @wandenberg updating documentation
authored
19
967379f @wandenberg fix libs references on docs and config
authored
20 * avformat >= 55.12.100 (last tested version: 55.12.100, 55.33.100, 55.48.100) - commonly distributed with "FFmpeg":http://ffmpeg.org
21 * avcodec >= 55.18.102 (last tested versions: 55.18.102, 55.52.102, 55.69.100) - commonly distributed with "FFmpeg":http://ffmpeg.org
22 * avutil >= 52.38.100 (last tested versions: 52.38.100, 52.66.100, 52.92.100) - commonly distributed with "FFmpeg":http://ffmpeg.org
23 * avfilter >= 3.79.101 (last tested versions: 3.79.101, 4.2.100, 4.11.100) - commonly distributed with "FFmpeg":http://ffmpeg.org
24 * swscale >= 2.3.100 (last tested versions: 2.3.100, 2.5.102, 2.6.100) - commonly distributed with "FFmpeg":http://ffmpeg.org
6fdd9a6 @wandenberg updating documentation
authored
25 * jpeg - "libjpeg":http://libjpeg.sourceforge.net
26
9406457 @wandenberg fix use of deprecated functions
authored
27
95240cf @wandenberg update README
authored
28 h1(#recommendation). Recommendation
9406457 @wandenberg fix use of deprecated functions
authored
29
967379f @wandenberg fix libs references on docs and config
authored
30 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_
6fdd9a6 @wandenberg updating documentation
authored
31
967379f @wandenberg fix libs references on docs and config
authored
32 If you don't install FFmpeg from source you need to be sure that you have headers files for the libs.
223ca26 @wandenberg adding recomendation about ImageMagick
authored
33
34
9406457 @wandenberg fix use of deprecated functions
authored
35 h1(#supported_video_formats). Supported Video Formats
36
37 This module uses the libraries avcodec and avformat to read the video files. Any supported video format for these libraries will work.
38 Tested formats was _mp4_, _mov_ and _flv_.
39
40
6fdd9a6 @wandenberg updating documentation
authored
41 h1(#installation). Installation
42
43 Install the above requirements and follow the steps bellow.
44
45 <pre>
46 # clone the project
95240cf @wandenberg update README
authored
47 git clone https://github.com/wandenberg/nginx-video-thumbextractor-module.git
6fdd9a6 @wandenberg updating documentation
authored
48 NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH=$PWD/nginx-video-thumbextractor-module
49
50 # get desired nginx version (tested with 1.0.x series)
51 wget http://nginx.org/download/nginx-1.0.10.tar.gz
52
53 # unpack, configure and build
54 tar xzvf nginx-1.0.10.tar.gz
55 cd nginx-1.0.10
8257357 @wandenberg remove MagickWand dependency which cause memory leak
authored
56 # configure nginx
95240cf @wandenberg update README
authored
57 ./configure --add-module=$NGINX_VIDEO_THUMBEXTRACTOR_MODULE_PATH
6fdd9a6 @wandenberg updating documentation
authored
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.0.10
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
8257357 @wandenberg remove MagickWand dependency which cause memory leak
authored
76
6fdd9a6 @wandenberg updating documentation
authored
77 h1(#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
90 h1(#basic-usage). Basic Usage
91
92 Assuming 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
106 h1(#directives). Directives
107
108
109 h2(#video_thumbextractor). video_thumbextractor
110
111 *syntax:* _video_thumbextractor_
112
113 *context:* _location_
114
115 *release version:* _0.1.0_
116
117 Set Video Thumb Extractor as the request handler for the location.
118
119
120 h2(#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
130 The video filename relative to root folder.
131 This directive is required.
132 Return a 404 if the video is not found.
133
134
135 h2(#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
145 The time in seconds where the image should be extracted. The nearest key frame will be used to get the image.
146 This directive is required.
147 Return a 400 if the value is not specified.
148 Return a 404 if the second is not found (the video is shorter than the time specified).
149
150
151 h2(#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
161 The width used to generate the image.
162 This directive is optional.
163 If only the width is specified the video size will be used as image size.
164
165
166 h2(#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
176 The height used to generate the image.
177 This directive is optional.
178 If only the height is specified the width will be determined using video scale to keep the aspect.
179 If both, width and height, are specified the image will suffers a resize and an eventual crop to keep the aspect.
180
181
95240cf @wandenberg update README
authored
182 h2(#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
192 Set if only the keyframes should be used to create the image.
193 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.
194
195
196 h2(#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
206 Set if will use the previous or the next keyframe considering the requested time when configured to use only the keyframes.
207
208
4211eec @wandenberg add tile filter support
authored
209 h2(#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
219 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.
220
221 !test/test_video_1_rows.jpg(using only 1 row)!
222
223
224 h2(#video_thumbextractor_tile_cols). video_thumbextractor_tile_cols
225
226 *syntax:* _video_thumbextractor_tile_cols number_
227
228 *default:* _none_
229
230 *context:* _http_
231
232 *release version:* _0.6.0_
233
234 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.
235
236 !test/test_video_2_cols.jpg(using 2 cols)!
237
238
239 h2(#video_thumbextractor_tile_max_rows). video_thumbextractor_tile_max_rows
240
241 *syntax:* _video_thumbextractor_tile_max_rows number_
242
243 *default:* _none_
244
245 *context:* _http_
246
247 *release version:* _0.6.0_
248
249 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.
250
251 !test/test_video_2_cols_2s_interval_2_max_rows.jpg(using 2 cols limited on up to 2 rows)!
252
253
254 h2(#video_thumbextractor_tile_max_cols). video_thumbextractor_tile_max_cols
255
256 *syntax:* _video_thumbextractor_tile_max_cols number_
257
258 *default:* _none_
259
260 *context:* _http_
261
262 *release version:* _0.6.0_
263
264 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.
265
266 !test/test_video_1_rows_2s_interval_5_max_cols.jpg(using only 1 row limited on up to 5 cols)!
267
268
269 h2(#video_thumbextractor_tile_sample_interval). video_thumbextractor_tile_sample_interval
270
271 *syntax:* _video_thumbextractor_tile_sample_interval number_
272
273 *default:* _none_
274
275 *context:* _http_
276
277 *release version:* _0.6.0_
278
279 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.
280 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.
281 To the interval be respected you should set video_thumbextractor_only_keyframe directive to off.
282
283 !test/test_video_2_cols_2s_interval.jpg(using 2 cols and 2 seconds of interval)!
284
285 !test/test_video_1_rows_2s_interval.jpg(using 1 row and 2 seconds of interval)!
286
287 !test/test_video_4_cols_4_rows.jpg(using 4 rows, 4 cols and calculated sample interval)!
288
289 !test/test_video_4_cols_4_rows_3s_interval.jpg(using 4 rows, 4 cols and 3 seconds of interval)!
290
291
292 h2(#video_thumbextractor_tile_color). video_thumbextractor_tile_color
293
294 *syntax:* _video_thumbextractor_tile_color string_
295
296 *default:* _none_
297
298 *context:* _http_
299
300 *release version:* _0.6.0_
301
302 Set the color to be used on the background. Valid values are defined "here":https://ffmpeg.org/ffmpeg-utils.html#Color
303
304 !test/test_video_2_cols_bg_color.jpg(using #EEAA33 as background color)!
305
306
307 h2(#video_thumbextractor_tile_margin). video_thumbextractor_tile_margin
308
309 *syntax:* _video_thumbextractor_tile_margin number_
310
311 *default:* _none_
312
313 *context:* _http_
314
315 *release version:* _0.6.0_
316
317 Set the size of the margin to be used on the final image.
318
319 !test/test_video_2_cols_2_rows_5_margin.jpg(using 5px of margin)!
320
321
322 h2(#video_thumbextractor_tile_padding). video_thumbextractor_tile_padding
323
324 *syntax:* _video_thumbextractor_tile_padding number_
325
326 *default:* _none_
327
328 *context:* _http_
329
330 *release version:* _0.6.0_
331
332 Set the size of the padding to be used between the frames.
333
334 !test/test_video_2_cols_2_rows_3_padding.jpg(using 3px of padding)!
335
336
e0a7c2f @wandenberg add directive to set the number of threads used by avcodec
authored
337 h2(#video_thumbextractor_threads). video_thumbextractor_threads
338
339 *syntax:* _video_thumbextractor_threads string_
340
341 *default:* _auto_
342
343 *context:* _http_
344
345 *release version:* _0.6.0_
346
347 Set the number of threads used by avcodec.
348
349
6fdd9a6 @wandenberg updating documentation
authored
350 h1(#contributors). Contributors
351
352 "People":contributors
353
354
355 h1(#changelog). Changelog
356
4211eec @wandenberg add tile filter support
authored
357 h2(#0_6_0). v0.6.0
358
359 * add support to tile filter, used to make story boards or sprites
e0a7c2f @wandenberg add directive to set the number of threads used by avcodec
authored
360 * add directive to control the number of threads used by avcodec
4211eec @wandenberg add tile filter support
authored
361
6e0d1aa @wandenberg update changelog to version 0.5.0
authored
362 h2(#0_5_0). v0.5.0
363
364 * fix jpeg dpi configuration usage
365 * remove support to old libav* libraries
366 * remove MagickWand dependency which cause memory leak
367
95240cf @wandenberg update README
authored
368 h2(#0_4_0). v0.4.0
369
370 * fix to proper read videos with the moov atom is at the end of the file
371 * fix to use the nearest decoded frame, in the case of requested time is on the end of the video
372 * fix CFLAGS, LDFLAGS and ngx_feature_libs to find the parameters to compile using right MagickWand lib version
373 * using av_frame_alloc instead of avcodec_alloc_frame when available
374
375 h2(#0_3_0). v0.3.0
376
377 * fix frame allocation assert
378 * add configuration to choose between only keyframes or not, and if will use the previous or next frame relative to given time
379 * make possible read the video from an nginx cache file
380
381 h2(#0_2_0). v0.2.0
382
383 * fix use of deprecated functions
384
6fdd9a6 @wandenberg updating documentation
authored
385 h2(#0_1_0). v0.1.0
386
387 * Initial release
388
389
390 [repository]https://github.com/wandenberg/nginx-video-thumbextractor-module
391 [installation]#instalation
392 [contributors]https://github.com/wandenberg/nginx-video-thumbextractor-module/contributors
Something went wrong with that request. Please try again.