Camera Media ServerBackchannel notifications
Background
Backchannel notifications are used to signal certain events to mobile client who is connected to the camera. One of the reasons to introduce this signalling mechanism is to allow mobile client to better handle feedback from the camera in terms of refreshing it's UI and to improve UX. Also, it allows camera to send important status information asynchronously so that mobile application can react accordingly.
Backchannel notifications are not HTTP calls, these are TCP packets which are sent on port which is reported as a result of GET /api/<versionNumber>/status method. Typically, every backchannel notification is in the form of JSON object consisting of it's name and actual payload which can be another JSON object. Currently supported backchannel notifications are:
recording_started
Description:
Sent when recording starts.
| Parameter | Description | Req'd? | Type |
| recording_active | Flag to start/stop recoding. | Yes | boolean |
tag_created
Description:
Sent when tag/highlight has been created.
Contains information about highlights's id, offset from beginning of video when it occurred, start offset from beginning of a video, length of the tag and an attribute defining type of tag and it's value.
| Parameter | Description | Req'd? | Type |
| id | Tag ID. | Yes | string, max. 36 characters |
| offset_secs | Exact tag offset (in seconds) from beginning of the video. | Yes | float |
| highlight_offset_secs | Tag start offset (in seconds) from beginning of the video. | Yes | float |
| highlight_length_secs | Tag length (in seconds) from beginning of the video. | Yes | float |
| attribute from the list of allowed attributes, look at GET /api/<versionNumber>/videos/<video_id>/tags) | Tag type. | Yes | depends on attribute type |
recording_stopped
Description:
Sent when recording has been stopped. Contains information about newly created file name(s), id, time created, size (in bytes), length (in seconds), number of highlights, mode and video's aspect ratio. If multiple videos are recorded within one session, information about every recorded video will be returned in an array of objects.
| Parameter | Description | Req'd? | Type |
| path | Path to the recorded file. | Yes | string, max. 255 characters |
| id | Recorded file ID. | Yes | string, max. 49 characters |
| created | Create time of recorded video. | Yes | string |
| size_bytes | Size of recorded video (in bytes). | Yes | integer |
| length_secs | Duration of recorded video (in seconds). | Yes | integer |
| nr_highlights | Number of highlights detected in recorded video. | Yes | integer |
| mode | Recorded video mode. | Yes | string, max. 32 characters |
| resolution | Recorded video resolution. | Yes | string, max. 16 characters |
| framerate_fps | Recorded video framerate. | Yes | integer |
| aspect_ratio | Recorded video aspect ratio. | Yes | string, max. 16 characters |
photo_captured
Description:
Sent when single, continuous or burst photo(s) are captured and after they are written to the SD card. For single photo, payload will contain only one id entry. For photo burst payload will contain list of photo ids captured. For continuous mode, one backchannel message will be sent after every photo is taken and recorded onto SD card.
| Parameter | Description | Req'd? | Type |
| array of image objects | Each object's structure corresponds to image object. Obtained from Image API. |
Yes | depends on number of photos captured |
memory_low
Description:
Sent when SD card full event is detected. Contains information about remaining free space on the SD card.
| Parameter | Description | Req'd? | Type |
| available_bytes | Number of bytes still available in. | Yes | integer |
shutting_down
Description:
Sent just before camera is shut down. One reason for this event to occur would be camera shutting down due to battery low level while it's connected to mobile client. In that case 'battery_critical' will be set to 'true'. If shut down was initiated by user action, appropriate flag will be set. Camera shuts down due to being overheated.
| Parameter | Description | Req'd? | Type |
| battery_critical | Sent if battery critical (low) is detected. | Yes | boolean |
| user_initiated | Sent if camera is about to be shut down because in user intervention. | Yes | boolean |
| overtemperature_shutdown | Sent if camera is about to be shut down due to overheating. | Yes | boolean |
wifi_stopped
Description:
Sent when WiFi is disabled (by using camera UI or other means)
| Parameter | Description | Req'd? | Type |
| wifi_active | Flags activity status of WiFi connection. | Yes | boolean |
transcoding_progress
Description:
Send periodically only while transcoding is in progress. Returns current percentage of finished transcoding job.
| Parameter | Description | Req'd? | Type |
| progress_pct | Percentage of video already transcoded. | Yes | integer |
viewfinder_started
Description:
Sent when viewfinder has been started.
| Parameter | Description | Req'd? | Type |
| viewfinder_active | Activity status of the viewfinder. | Yes | integer |
viewfinder_stopped
Description:
Sent when viewfinder has been stopped.
| Parameter | Description | Req'd? | Type |
| viewfinder_active | Activity status of the viewfinder. | Yes | integer |
memory_error
Description:
Sent when SD card error has occurred.
| Parameter | Description | Req'd? | Type |
| memory_error | Memory error status. | Yes | boolean
|
Examples:
recording_started
{
"recording_started" : {
"recording_active":true
}
}
recording_stopped
{
"recording_stopped" : [{
"path":"/100TTCAM/MOV_0001.MP4",
"id":"3e5bdae0-a097-415e-9f34-e3e031b407da-100-000-001-0001",
"created":"2012-03-04T12:05:20Z",
"size_bytes":4174913786,
"length_secs":1254,
"nr_highlights":12,
"mode":"normal",
"resolution":"1080p",
"framerate_fps":60,
"aspect_ratio":"16/9"
},
{
"path":"/100TTCAM/MOV_0002.MP4",
"id":"a783dae3-b492-1154-cc32-512631b407da-100-000-001-0002",
"created":"2012-03-04T11:25:12Z",
"size_bytes":74913786,
"length_secs":33,
"nr_highlights":12,
"mode":"normal",
"resolution":"1080p",
"framerate_fps":60,
"aspect_ratio":"16/9"
}]
}
photo_captured
{
"photo_captured" : [{
"path":"/100TTCAM/IMG_0001.JPG",
"id":"ae03e5bd-7a09-e415-49f3-407dae3e031b-100-001-002-0003",
"created":"2012-03-04T12:05:20Z",
"size_bytes":2154637,
"mode":"normal",
"resolution":"16MP",
"aspect_ratio":"4/3",
"lat_deg":44.715513,
"lon_deg":20.632324
},
{
"path":"/100TTCAM/IMG_0002.JPG",
"id":"dae03e5b-97a0-5e41-349f-b407dae3e031-100-001-004-0002",
"created":"2012-03-04T12:15:40Z",
"size_bytes":2857372,
"mode":"continuous",
"resolution":"8MP",
"aspect_ratio":"4/3",
"lat_deg":44.715513,
"lon_deg":20.632324
}]
}
tag_created
{
"tag_created" : {
"id":"3e5bdae0-a097-415e-9f34-e3e031b407da",
"offset_secs":8.2,
"highlight_offset_secs":3.2,
"highlight_length_secs":10.5,
"tag_button":true
}
}
memory_low
{
"memory_low" : {
"available_bytes":51234
}
}
shutting_down
{
"shutting_down" : {
"battery_critical":true
}
}
wifi_stopped
{
"wifi_stopped" : {
"wifi_active":false
}
}
transcoding_progress
{
"transcoding_progress" : {
"progress_pct":20
}
}
viewfinder_started
{
"viewfinder_started" : {
"viewfinder_active":true
}
}
viewfinder_stopped
{
"viewfinder_stopped" : {
"viewfinder_active":false
}
}
memory_error
{
"memory_error" : true
}