Detect Scene Changes

Detect scene changes in the input video.

The Detect Scene Changes API extract images from videos based on scene changes.

For a full list of supported video container formats and codecs, see Supported Media Formats. The API extracts the scene changes as base64 encoded images, along with the time when the scene change was detected.

Quick Start

You can upload a video to the API as a file, in which case you must use a POST method. You can also input a URL or a Haven OnDemand reference. For example:

/1/api/async/detectscenechanges/v1?url=https://www.havenondemand.com/sample-content/videos/funfair.mp4

Note: Due to the runtime of this API, it is available only as an asynchronous version. See Get the Results.

Note: This API has rate and duration limits:

  • Input files are truncated after 30 minutes.
  • The processing terminates after two hours and returns only what it has completed within that time.

For more information, see Rate Limiting, Quotas, Data Expiry, and Maximums.

Specify the Interval Between Scene Changes

The default options generate a new scene change image only when there is a scene change in the video. If you want to generate scene change images after a certain amount of time, even when the scene has not changed, you can specify the max_interval parameter (in seconds).

/1/api/async/detectscenechanges/v1?max_interval=30&url=https://www.havenondemand.com/sample-content/videos/funfair.mp4

You can also specify the min_interval parameter (in seconds) so that the output does not include too many changes if the scene changes rapidly in the video.

/1/api/async/detectscenechanges/v1?min_interval=10&url=https://www.havenondemand.com/sample-content/videos/funfair.mp4

Specify the Output Size

The default options generate the scene change images with a width of 480 pixels, and maintain the aspect ratio of the original video. You can use the width and height parameters to specify the size of the images. For example:

/1/api/async/detectscenechanges/v1?width=160&height=90&url=https://www.havenondemand.com/sample-content/videos/funfair.mp4

If you want to resize the image and maintain the aspect ratio of the original video, set the value that you want for width or height, and omit the other. For example:

/1/api/async/detectscenechanges/v1?width=160&url=https://www.havenondemand.com/sample-content/videos/funfair.mp4

The width and height parameters both have a minimum value of 50. The maximum width is 480 pixels, and the maximum height is 270 pixels.

Specify the Output Format

The default options generate the scene change images as base64 encoded jpeg images {jpg). You can use the format parameter to specify the output format; Portable Network Graphics (png) is also supported. See also Supported Media Formats for a list of all graphics formats supported in HPE Haven OnDemand.

/1/api/async/detectscenechanges/v1?format=png&url=https://www.havenondemand.com/sample-content/videos/funfair.mp4

Get the Results

The asynchronous mode returns a job-id, which you can then use to extract your results. There are two methods for this:

  • Use /1/job/status/ to get the status of the job, including results if the job is finished.
  • Use /1/job/result/, which waits until the job has finished and then returns the result.

    Note: Because /result has to wait for the job to finish before it can return a response, using it for longer operations such as processing a large video file can result in an HTTP request timeout response. The /result method returns a response either when the result is available, or after 120 seconds, whichever is sooner. If the job is not complete after 120 seconds, the /result method returns a code 7010 (job result request timeout) response. This means that your asynchronous job is still in progress. To avoid the timeout, use /status instead.

The results take the form:


    {
        "items": [
            {
                "time": 12,
                "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAAAAAA6fptVAAAACklEQVQYV2P4DwABAQEAWk1v8QAAAABJRU5ErkJggg=="
            },
            {
                "time": 28,
                "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAAAAAA6fptVAAAACklEQVQYV2P4DwABAQEAWk1v8QAAAABJRU5ErkJggg=="
            },
            {
                "time": 58,
                "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAAAAAA6fptVAAAACklEQVQYV2P4DwABAQEAWk1v8QAAAABJRU5ErkJggg=="
            }
        ]
    }
  
Asynchronous
https://api.havenondemand.com/1/api/async/detectscenechanges/v1

This API only supports Asynchronous invocation.

Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
file
binary A video file containing the scene changes to detect. Multi part POST only.
reference
string A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding video is passed to the API.
url
string A publicly accessible HTTP URL from which a video can be retrieved.
Optional
Name Type Description
width
integer The width of the extracted images (in pixels).
height
integer The height of the extracted images (in pixels).
format
enum The output format of the extracted images. Default value: jpeg.
max_interval
integer The maximum time interval in seconds between scene changes. If no scene change is detected after this interval, a new scene change image at the end of the interval is created.
min_interval
integer The minimum time interval in seconds between scene changes.
Enumeration Types

This API's parameters use the enumerations described below:

format
The output format of the extracted images.
jpeg jpeg
Jpeg
png png
Portable network graphic

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Detect Scene Changes Response {
message ( string , optional) Response message.
items ( array[Items] ) The scene changes present in the video
}
Detect Scene Changes Response:Items {
time ( number ) Time offset in seconds (expressed as a number with decimal values) from the start of the video where the scene change was detected.
width ( number , optional) The width of the image in pixels.
height ( number , optional) The height of the image in pixels.
image ( string ) A data URI containing the image as a base64 encoded string.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "message": {
            "type": "string"
        },
        "items": {
            "items": {
                "properties": {
                    "time": {
                        "type": "number"
                    },
                    "width": {
                        "type": "number"
                    },
                    "height": {
                        "type": "number"
                    },
                    "image": {
                        "type": "string"
                    }
                },
                "required": [
                    "time",
                    "image"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "items"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/async/detectscenechanges/v1
/api/api-example/1/api/async/detectscenechanges/v1
Examples
See this API for yourself - select one of our examples below.
Funfair
Motorcyles
Parameters
Required
Select file Change Remove
Optional
Name Type Value
width
integer
height
integer
format
enum
max_interval
integer
min_interval
integer

Note: This API will be invoked asynchronously.



ASync – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.