Scene Change Detection

Detects scene changes within a target video.

The Scene Change Detection API identifies the time in a video where the scene changes.

For a full list of supported video container formats and codecs, see Supported Media Formats.

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: Because input files for this API can be large and take a long time to process, the API runs only in asynchronous mode. 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 maximum_scene_interval parameter (in seconds).

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

You can also specify the minimum_scene_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/v2?minimum_scene_interval=10&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_offset": 12
            },
            {
                "time_offset": 28
            },
            {
                "time_offset": 58
            }
        ]
    }
  
Asynchronous
https://api.havenondemand.com/1/api/async/detectscenechanges/v2

This API supports only 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
maximum_scene_interval
integer The maximum time interval between scene changes. If this is exceeded, a scene change is created regardless of the scene state.
minimum_scene_interval
integer The minimum time interval between scene changes. Any possible scene change detected in an interval below this constraint is ignored.

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.
Scene Change Detection Response {
source_information ( Source_information , optional) Metadata information about a media file
items ( array[Items] ) The format of scene change detection results in the response.
}
Scene Change Detection Response:Source_information {
mime_type ( string ) MIME type of the document.
video_information ( Video_information , optional) Information about the video track if one is present.
audio_information ( Audio_information , optional) Information about the audio track if one is present.
}
Scene Change Detection Response:Source_information:Video_information {
width ( integer ) The width of the video in pixels.
height ( integer ) The height of the video in pixels.
codec ( string ) The algorithm used to encode the video.
pixel_aspect_ratio ( string ) The aspect ratio of pixels in the video. For example, if the video is made up of square pixels, this value is 1:1
}
Scene Change Detection Response:Source_information:Audio_information {
codec ( string ) The algorithm used to encode the audio.
sample_rate ( integer ) The frequency at which the audio was sampled.
channels ( integer ) The number of channels present in the audio. For example, for stereo this value is 2.
}
Scene Change Detection Response:Items {
time_offset ( number ) Time offset from the start of the video to where the scene change occurred. This value is expressed as a non integer number.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "source_information": {
            "properties": {
                "mime_type": {
                    "type": "string"
                },
                "video_information": {
                    "properties": {
                        "width": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "height": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "codec": {
                            "type": "string"
                        },
                        "pixel_aspect_ratio": {
                            "type": "string"
                        }
                    },
                    "type": "object",
                    "required": [
                        "width",
                        "height",
                        "codec",
                        "pixel_aspect_ratio"
                    ]
                },
                "audio_information": {
                    "properties": {
                        "codec": {
                            "type": "string"
                        },
                        "sample_rate": {
                            "type": "integer"
                        },
                        "channels": {
                            "type": "integer"
                        }
                    },
                    "type": "object",
                    "required": [
                        "codec",
                        "sample_rate",
                        "channels"
                    ]
                }
            },
            "required": [
                "mime_type"
            ],
            "type": "object"
        },
        "items": {
            "items": {
                "properties": {
                    "time_offset": {
                        "type": "number",
                        "minimum": 0
                    }
                },
                "required": [
                    "time_offset"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "items"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/async/detectscenechanges/v2
/api/api-example/1/api/async/detectscenechanges/v2
Examples
See this API for yourself - select one of our examples below.
Funfair
Motorcyles
Parameters
Required
Select file Change Remove
Optional
Name Type Value
maximum_scene_interval
integer
minimum_scene_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.