docs: new features and documentations

README.md

@@ -9,7 +9,7 @@ imagorvideo is a new initiative that brings video thumbnail capability through f
 
 imagorvideo uses ffmpeg C bindings that extracts image thumbnail from video by attempting to select the best frame, then forwards to libvips to perform all the image cropping, resizing and filters supported by imagor.
 
-imagorvideo uses read stream for mkv and webm video types. For other video types that requires seeking from a non seek-able source such as HTTP or S3, it simulates seek using memory buffer or temp file, by having the whole file to be fully loaded to perform seek.
+imagorvideo uses read stream for mkv and webm video types. For other video types that requires seeking from a non seek-able source such as HTTP or S3, it simulates seek using memory or temp file as buffer.
 
 This also aims to be a reference project demonstrating imagor extension.
 
@@ -21,16 +21,72 @@ docker run -p 8000:8000 shumc/imagorvideo -imagor-unsafe
 
 Original:
 ```
-https://raw.githubusercontent.com/ietf-wg-cellar/matroska-test-files/master/test_files/test4.mkv
+http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4
 ```
 
 Result:
 ```
-http://localhost:8000/unsafe/fit-in/300x200/filters:label(imagorvideo,10,-10,20,yellow):fill(yellow)/https://raw.githubusercontent.com/ietf-wg-cellar/matroska-test-files/master/test_files/test4.mkv
+http://localhost:8000/unsafe/300x0/7x7/filters:label(imagorvideo,-10,-7,20,yellow):fill(yellow)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4
 ```
-<img src="https://raw.githubusercontent.com/cshum/imagorvideo/master/testdata/demo.jpg" width="200" />
 
-Check out [imagor](https://github.com/cshum/imagor#image-endpoint) for all image features supported.
+![imagorvideo](https://raw.githubusercontent.com/cshum/imagorvideo/master/testdata/demo.jpg)
+
+imagorvideo works by streaming out a limited number of frames data from start of the video, looping through and populating the histogram data of each frame. It then choose the best frame for imaging, based on root-mean-square error (RMSE). This allow skipping the black frames that usually occur at the beginning of videos. 
+
+imagorvideo then converts the selected frame to RGB image data, forwards to the imagor libvips module, which has always been best at image processing with tons of features. Check out [imagor documentations](https://github.com/cshum/imagor#image-endpoint) for all the image options supported.
+
+### Filters
+
+imagorvideo supports the following filters:
+
+- `frame(n)` specifying the frame index `n` for imaging. This allows skipping the default automatic selection, which involves computing root-mean-square error (RMSE) of histogram frames data.
+- `max_frames(n)` restrict the maximum number of frames allocated for image selection. The smaller the number, the faster the processing time.
+
+Example:
+```
+http://localhost:8000/unsafe/300x0/7x7/filters:max_frames(70):fill(yellow)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4
+```
+
+### Metadata
+
+imagor provides metadata endpoint that extracts video metadata, dimension and duration data. By default, it only process the header without extracting the frame data, which result faster processing speed:
+
+```
+http://localhost:8000/unsafe/meta/https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/1080/Big_Buck_Bunny_1080_10s_30MB.mp4
+```
+
+```json
+{
+  "format": "mp4",
+  "content_type": "video/mp4",
+  "orientation": 1,
+  "duration": 10000,
+  "width": 1920,
+  "height": 1080,
+  "title": "Big Buck Bunny, Sunflower version",
+  "artist": "Blender Foundation 2008, Janus Bager Kristensen 2013",
+  "has_video": true,
+  "has_audio": false
+}
+```
+Appending the `max_frame()` filter however, would trigger the frames processing. This result more processing time but would also allow frames per second `fps` and selected frame index to be available:
+
+```json
+{
+  "format": "mp4",
+  "content_type": "video/mp4",
+  "orientation": 1,
+  "duration": 10000,
+  "width": 1920,
+  "height": 1080,
+  "title": "Big Buck Bunny, Sunflower version",
+  "artist": "Blender Foundation 2008, Janus Bager Kristensen 2013",
+  "fps": 30,
+  "selected_frame": 21,
+  "has_video": true,
+  "has_audio": false
+}
+```
 
 ### Configuration