Live Offline Options

Here is a list of the configuration options:

Property Description Default
savelocal Enable local download support. No server side is required. false
serverurl The location to the backend server for saving the images.
tokenurl The location of the backend server for obtaining a csrf token.
token The csrf token to use with the save request.
tokendata Configure specific data to use for sending to the token server request. The server can use this for extra authentication.
s3url The url to the S3 bucket ie //bucket.s3-region.amazonaws.com"
signatureurl The location of the backend server for obtaining the generated authentication signature for s3 requests.
s3 The generated s3 signature provided by the backend configured directly on the player.
postfiles Unless there is three or more dimensions configured. Set postfiles to upload images as files. With the S3 backend multiple image uploads is sent as default and a requirement.
type The image type to use for encoding either png or jpeg.
quality The png / jpeg compression quality.
dimensions A list of dimensions to use for resizing the still including to thumbnails. For thumbnails the thumbnail property is required.
unsharpAmount The sharpness setting for the image resizer in percentage. 50-100 is a good range. 80
unsharpRadius Radius of Gaussian blur for the image resizer that affects sharpness. values between 0.5 and 2.0 0.6
unsharpThreshold Threshold for unsharp mask for the image resizer. values between 0 and 255. 2
success The capture success notification message. Capture Complete
error The capture failure notification message. Capture Failed Try Again.
processing The processing notification message. Processing Please Wait.
thumbnail The thumbnail creation notification message. Generating Thumbnail
debug Display debug logs. false
pauseOnCapture Pause the stream on capture. true

Filename Configuration

To send a custom filename for the capture image configure this on the video config with a snapshotnames or snapshotname property with a time postfix format to add the current frame time

When using a multiple dimensions config the filenames list needs to match and the snapshotnames is required.

{
    "snapshotname": "test2-[time]"
}

:::json
{
    "snapshotnames": [
        "test2.jpg",
        "test2-thumb.jpg"
    ]
}

Multiple Dimensions

To produce multiple sizes with high quality resizing and downsampling the dimensions config is required. For thumnails the thumbnail property is required on that size.

If only a thumbnail dimension is configured the original video dimensions will be used for the larger still.

A width an height can be set. If only a width is set the height will be scaled which is the default option.

{
    "dimensions": [
        //configure thumbnail width to auto scale height to
        { "width": 180, "thumbnail": true }
    ]
}

:::json
{
    "dimensions": [
        { "width": 600 },
        { "width": 400 },
        { "width": 180, "thumbnail": true }
    ]
}

Javascript API

Javascript api

player.capture();
method Description
capture Manually initiate the capture process.

Events

The capture complete event returns data for the generated encoded still and thumbnail as a base64 data uri string. For Html5 captures it also returns the original canvas. For backend storing of captures the data from the server is also returned.

event Description
capturecomplete Returns captured image data
captureerror On capture errors.
uploaderror On upload errors.
uploadprogress On upload progress.
resizeprogress On resize progress.

Token Server

The configured token server must return a Access-Control-Allow-Origin for Ajax requests and a csrf hash in a json object string like so: 

{"token":"f38c9bd8483916513f057a6ea71a6d24"}

If extra authentication data is required along with the token hash these can be returned with the token service and sent to the image upload service. 

{"token":"f38c9bd8483916513f057a6ea71a6d24", "extrahash" : "54353985398235985328953358"}

If required the tokendata can be configured with extra authentication properties for the token server to use to authenticate the client and request. 

NOTE: Safari tries to block third party cookie sessions with ajax requests so a special P3P header is required to work around this.

Backend Server

Included is a backend server which demonstrates handling the cors headers required for Ajax requests, filtering the post and the image sent as a base64 encoded string or as multiple file uploads. The server should provide the parameter and token hash security and base64 decode the image as a string and store on the server. File uploads should be validated. The following properties are required or optional:

property Description
image The image stored as a base64 encoded string.
thumbnail The thumbnail image stored as a base64 encoded string when available.
type The image type chosen either jpg or png.
token The csrf token to use with the save request, if a token is configured this can be used to check the request.
name The name of the image to use when saving.
thumbnailname The name of the thumbnail image to use when saving.
file1..3 The name of the multiple file uploads post data stored as files. The file uploads are required to be validated with multiple options for security purposes.

CORS Rules Requirements

For this feature to work successfully both the backend server and the video hosting server require Cross Origin Resource Sharing rules to be enabled in the headers of the request.

This is required to enable cross origin Ajax requests when posting the captured image data and to be able to gain access to the video data within a Html5 video tag.

The header of the cors request must expose a Access-Control-Allow-Origin header with either a multiple list of domains including ports if using ports or an asterix wildcard to allow all domains.

A Access-Control-Allow-Methods can be exposed to control what request methods are allowed. For authenticated logins with cookies the Access-Control-Allow-Credentials header must be enabled and the feature will pass cookie sessions and other cookies along with the request.