Video Management
Used to retrieve and manipulate video files found on the camera's SD card.
Table of contents
- GET /api/<versionNumber>/videos
- GET /api/<versionNumber>/videos/<video_id>/thumb
- GET /api/<versionNumber>/videos/<video_id>/frames
- GET /api/<versionNumber>/videos/<video_id>
- GET /api/<versionNumber>/videos/<video_id>/contents
- DELETE /api/<versionNumber>/videos/<video_id>
GET /api/<versionNumber>/videos[?sort=<sort>][&order=<order>][&offset=<offset>][&count=<count>][&tags=<tags>]
Format:
http://<baseURL>/api/<versionNumber>/videos[?sort=<sort>][&order=<order>][&offset=<offset>][&count=<count>][&tags=<tags>]
Example:
http://192.168.1.101/api/2/videos
Parameters:
Parameter 'offset' is 0-based so offset=0 will address the first file from the resource.
'offset' and 'count' are used (based on sort criteria set by 'sort' parameter and 'order') to retrieve video information for 'count' files, first starting at specified 'offset' from beginning of a sorted list of files. If 'offset' is bigger than total count of files, error code will be returned. However, if 'offset' falls into range but 'count' specifies more items than available, this method will return as many items as possible and won't return error status code.
All query parameters are optional. Following table depicts possible options and default value for each of them.
Parameter | Description | Req'd? | Possible values |
baseURL | Fixed address, Bandit acts like an access point with this addres. TomTom Bandit's WiFi has to be turned on. | Yes | 192.168.1.101 |
versionNumber | Service version number. The current value is 2. | Yes | 2 |
[sort] | Results are sorted by filename (default, in case more parameters are added in the future versions). | No | filename |
[order] | Results are returned in ascending (default, if parameter is omitted) or descending order if specified differently. | No | asc (default) desc |
[offset] | Defaults to 0 if omitted, otherwise represents 0-based offset targeting the first item from the result list that should be returned in response. | No | 0-based integer offset |
[count] | Defaults to 1 if omitted, otherwise represents maximum number of items that should be returned in response. If 'count' is bigger than the remaining number of result items, only remaining items will be returned. If count is set to 0, response containing only total number of items, without any actual item will be returned. |
No | integer number of items requested |
[tags] | Defaults to 0 if omitted, for value of '1' returns list of tags (as an JSON array) for every video which is returned in response. If it's set to 0 (or omitted), video details without tag details are returned in response. |
No | 0 (default) 1 |
Description:
Returns total number of videos found on the camera and then array of JSON objects containing information about all video files filtered by query parameters. Every JSON object will contain following information:
Parameter | Description | Type |
path | Path to video in format: '/'+<DCIM_folder>+'/'+<filename>. | string, max. 255 characters |
id | Unique identifier of the video file. | string, max. 49 characters |
created | ISO 8601 UTC format of file's creation time. | string |
size_bytes | Size of a file in bytes. | integer |
length_secs | Length of a video in seconds (rounded to 2 decimal places). | decimal |
nr_highlights | Number of highlights stored in video file. | integer |
mode | Possible values: "normal", "slow_motion", "time_lapse", "night_lapse". | string, max. 32 characters |
resolution | Possible values: "4k", "2.7k", "1080p", "720p", "wvga". | string, max. 16 characters |
framerate_fps | Framerate of recorded video. | integer |
interval_secs | Time interval (in seconds) between taking two consecutive input frames. Valid for time lapse mode. | float |
aspect_ratio | Aspect ratio of the video in format "4/3" or "16/9" (currently, only 16/9 aspect ratio for video is supported). | string, max. 16 characters |
is_valid | Flags if file is valid (true) or corrupt (false). | boolean |
tags | Tag objects are the same ones used in Tag API. This attribute is optional and depends on URL filter specified. | array of tag objects |
Response codes:
Code | Description |
200 | OK |
400 | Bad Request (sort, order, offset and/or count parameters are out of range or missing) |
500 | Server Error (request can't be processed) |
Example request 1:
GET http://192.168.1.101/api/2/videos
and example response:
{ "total":2, "items": [ { "path":"/100TTCAM/MOV_0001.MP4", "id":"7666a33a-6275-4549-836b-4f8d00281233-100-000-001-0001", "created":"2012-03-05T18:34:14Z", "size_bytes":1234567, "length_secs":32.2, "nr_hightlights":12, "mode":"normal", "resolution":"1080p", "framerate_fps":60, "aspect_ratio":"16/9", "is_valid":true } ] }
Example request 2:
GET http://192.168.1.101/api/2/videos?sortby=filename&order=asc&offset=0&count=2&tags=1
and example response:
{ "total":2, "items": [ { "path":"/100TTCAM/MOV_0001.MP4", "id":"7666a33a-6275-4549-836b-4f8d00281233-100-000-001-0001", "created":"2012-03-05T18:34:14Z", "size_bytes":1234567, "length_secs":32.2, "nr_hightlights":12, "mode":"normal", "resolution":"1080p", "framerate_fps":60, "aspect_ratio":"16/9", "is_valid":true }, { "path":"/100TTCAM/MOV_0002.MP4", "id":"9376a883-6345-2349-966b-2a8d00281980-100-000-001-0002", "created":"2012-03-04T12:05:20Z", "size_bytes":4000586, "length_secs":134.5, "nr_hightlights":20, "mode":"slow_motion", "resolution":"1080p", "framerate_fps":60, "aspect_ratio":"16/9", "is_valid":true, "tags": [{ "id":"7666a33a-6275-4549-836b-4f8d00281233", "offset_secs":8.2, "highlight_offset_secs":3.2, "highlight_length_secs":13.2, "max_speed":15.5 }, { "id":"09615314-eb75-4813-b36e-aed6b4aa12bc", "offset_secs":15.5, "highlight_offset_secs":10.5, "highlight_length_secs":17.5, "tag_button":true }] } ] }
Example request 3:
GET http://192.168.1.101/api/2/videos?count=0
and example response:
{ "total":2 }
GET /api/<versionNumber>/videos/<video_id>/thumb[?offset_secs=<value>]
Format:
http://<baseURL>/api/<versionNumber>/videos/<video_id>/thumb
Example:
http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001/thumb
Parameters:
Parameter 'offset_secs' is optional. It's defined as query string meaning:
Parameter | Description | Req'd? | Type |
baseURL | Fixed address, Bandit acts like an access point with this addres. TomTom Bandit's WiFi has to be turned on. | Yes | 192.168.1.101 |
versionNumber | Service version number. The current value is 2. | Yes | 2 |
video_id | Video id. | Yes | — |
[offset_secs] | Number of seconds (float value) from beginning of a video from where thumbnail should be obtained. Example value: 4.5 |
No | float |
If 'offset_secs' parameter is omitted, camera will return default thumbnail stored as a part of user data section of the MP4 container.
Description:
Returns thumbnail (in JPEG format) from requested MP4 file identified by it's id. Thumbnail is taken at the time specified by 'offset_secs' input parameter.
If 'offset_secs' is not specified, default thumbnail already pre-recorded in MP4 container is returned instead.
Content-type field of response's HTTP header will be set to image/jpeg.
Response codes:
Code | Description |
200 | OK |
404 | Not Found (file with requested id not found) |
500 | Server Error (request can't be processed) |
Example request:
GET http://192.168.1.101/1/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001/thumb?offset_secs=4.5
causes JPEG picture representing thumbnail taken 4.5s after beginning of a video to be sent as a response.
Content-type: image/jpeg
GET /api/<versionNumber>/videos/<video_id>/frames[?offset_secs=<value>]
Format:
http://<baseURL>/api/<versionNumber>/videos/<video_id>/frames?offset_secs=<value>&count=<value>
Example:
http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001/frames?offset_secs=4&count=3
Parameters:
Parameter | Description | Req'd? | Type |
baseURL | Fixed address, Bandit acts like an access point with this addres. TomTom Bandit's WiFi has to be turned on. | Yes | 192.168.1.101 |
versionNumber | Service version number. The current value is 2. | Yes | 2 |
video_id | Video id. | Yes | — |
offset_secs | Time in the video at which frame will be captured. | Yes | float |
Description:
Grabs a frame from the video specified by it's <video_id> at the time in the video specified by offset_secs and returns it as a JPG image through response.
Response codes:
Code | Description |
200 | OK |
400 | Bad Request (wrong or unrecognised parameters) |
500 | Server Error (request can't be processed) |
Response:
JPG image as a shapshot taken at specified time in the video.
Example request (starts snapshot capture):
POST http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001/frames?offset_secs=2.5
If successful, this method will return a frame as a JPG image.
GET /api/<versionNumber>/videos/<video_id>[?tags=<tags>]
Format:
http://<baseURL>/api/<versionNumber>/videos/<video_id>
Example:
http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001
Parameters:
Parameter | Description | Req'd? | Type / Values |
---|---|---|---|
baseURL | Fixed address, Bandit acts like an access point with this addres. TomTom Bandit's WiFi has to be turned on. | Yes | 192.168.1.101 |
versionNumber | Service version number. The current value is 2. | Yes | 2 |
video_id | Video id. | Yes | — |
Description:
Returns information about video file stored on camera's SD card and specified by it's id. Response is in JSON format, look at GET /api/<baseURL>/videos for format details and description of returned attributes.
Query parameter is optional. Following table depicts possible options and default value.
Parameter | Possible values | Description | Req'd | Type |
[tags] | 0 (default) 1 |
Defaults to 0 if omitted, for value of '1' returns list of tags (as an JSON array) for a video which is returned in response. If it's set to 0 (or omitted), video details without tag details are returned in response. |
No | boolean |
Response codes:
Code | Description |
200 | OK |
404 | Not Found (file with requested id not found) |
500 | Server Error (request can't be processed) |
Example request 1:
GET http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001
and response:
{ "path":"/100TTCAM/MOV_0001.MP4", "id":"7666a33a-6275-4549-836b-4f8d00281233-100-000-001-0001", "created":"2012-03-05T18:34:14Z", "size_bytes":1234567, "length_secs":32.2, "nr_hightlights":12, "mode":"normal", "resolution":"1080p", "framerate_fps":60, "aspect_ratio":"16/9", "is_valid":true }
Example request 2:
GET http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001?tags=1
and response:
{ "path":"/100TTCAM/MOV_0001.MP4", "id":"7666a33a-6275-4549-836b-4f8d00281233-100-000-001-0001", "created":"2012-03-05T18:34:14Z", "size_bytes":1234567, "length_secs":32.2, "nr_hightlights":12, "mode":"normal", "resolution":"1080p", "framerate_fps":60, "aspect_ratio":"16/9", "is_valid":true, "tags": [{ "id":"7666a33a-6275-4549-836b-4f8d00281233", "offset_secs":8.2, "highlight_offset_secs":3.2, "highlight_length_secs":13.2, "max_speed":15.5 }, { "id":"09615314-eb75-4813-b36e-aed6b4aa12bc", "offset_secs":15.5, "highlight_offset_secs":10.5, "highlight_length_secs":17.5, "tag_button":true }] }
GET /api/<versionNumber>/videos/<video_id>/contents[?resolution=<resolution>&framerate=<framerate>&offset_secs=<value>&length_secs=<value>]
Format:
http://<baseURL>/api/<versionNumber>/videos/<video_id>/contents
Example:
http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001/contents
Parameters:
If query string parameters are omitted this API call will return MP4 video, as it was recorded, defined by it's video_id.
If only 'resolution' and 'framerate' parameters are defined, whole video will be transcoded to defined resolution/framerate before being delivered to the client. Please check possible combination of resolution/framerate values in Capabilities API (GET /capabilities/transcoder). Only both 'resolution' and 'framerate' parameters can be defined, defining only one of them is not supported.
'offset_secs' and 'length_secs' can exists only if both 'resolution' and 'framerate' already exists. When 'offset_secs' and 'length_secs' parameters are defined properly, this method will return transcoded portion of the video defined by it's parameters.
NOTE: Video will be cut to closest second boundaries since camera at the moment doesn't support extraction on sub-second boundaries. Therefore, start of the clip will be rounded down to the nearest integer second while end of the clip will be rounded up to the nearest integer second.
Parameter | Description | Req'd? | Type |
baseURL | Fixed address, Bandit acts like an access point with this addres. TomTom Bandit's WiFi has to be turned on. | Yes | 192.168.1.101 |
versionNumber | Service version number. The current value is 2. | Yes | 2 |
video_id | Video id. | Yes | — |
[resolution] | Requested resolution of resulting video. Supported values are: '4k', '2.7k', '1080p', '720p', '480p' and 'wvga'. | No | string, max. 16 characters |
[framerate] | Requested framerate of resulting video. For possible resolution/framerate combinations take a look at GET /capabilities/transcoder method. 'resolution' and 'framerate' goes hand in hand, either both or none has to be defined.
|
No | integer |
[offset_secs] | Number of seconds (float value) from beginning of a video from where resulting video be obtained. Example value: 4.5 |
No | float |
[length_secs] | Requested length of a video clip, in seconds. 'offset_secs' and 'length_secs' goes hand to hand, either both or none has to be defined. Example value: 10.3 |
No | float |
This API call, if successful, will return resulting MP4 file.
'1080p', '720p' and 'wvga'. For 'framerate' it's '180fps', '120fps', '60fps', '30fps' and '15fps'. To get a matrix of possible options for any given video resolution/framerate, take a look at response of GET /api/<versionNumber>/capabilities/transcoding method.
Description:
Downloads whole video file specified by it's id or a chunk of it from camera's SD card. Both whole video and chunk can be transcoded to one of supported resolution/framerate combination.
Request should set Accept field in the HTTP header to video/mp4. Consequently, response will set Content type in the header as video/mp4.
Response codes:
Code | Description |
200 | OK |
404 | Not Found (file with requested id not found) |
500 | Server Error (request can't be processed) |
Example request:
GET http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/contents?resolution=1080p&framerate=30fps&offset_secs=1&length_secs=10
Content type: video/mp4
and example response:
- will set Content type to video/mp4
- start sending the video file transcoded to 1080p30fps from 1st to 11th second
DELETE /api/<versionNumber>/videos/<video_id>
Format:
http://<baseURL>/api/<versionNumber>/videos/<video_id>
Example:
http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001
Parameters:
Parameter | Description | Req'd? | Type / Values |
---|---|---|---|
baseURL | Fixed address, Bandit acts like an access point with this addres. TomTom Bandit's WiFi has to be turned on. | Yes | 192.168.1.101 |
versionNumber | Service version number. The current value is 2. | Yes | 2 |
video_id | Video id. | Yes | — |
Description:
Deletes video file specified by it's id from camera's SD card.
Response codes:
Code | Description |
200 | OK |
404 | Not Found (file with requested id not found) |
500 | Server Error (request can't be processed) |
Example request:
DELETE http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001