Introduction


Video Smart Module provides an efficient way to collect the video data that your IoT devices capture and to get access to the stored video resources. Video Smart Module uses Stream Data Store Smart Module as its data uploading interfaceso you need to create a Stream Data Store Smart Module ahead of time.

Setting up Video Smart Module


zero | Create a Stream Data Store Smart Module that will be the data source of the Video Smart Module you are creating. See Setting up Stream Data Store Smart Module for details.

One | In the Developer Console, navigate to the SMART MODULE LIST page and select +NEW. Click +Add on the section for Video.

Screenshot - Console Smart Modules Add Video

TWO | Fill out the "New Video Module" form.

Screenshot - Console Smart Modules Add Stream Data Store
  • Module ID: Uniquely identifiable name used for getting access to the data in SDS from the REST API.
  • Description: Description for the new Smart Module.
  • Data Source: Module ID of the Stream Data Store which you are supposed to create in the previous step.
  • Stream Name Prefix: (optional) Among the streams in your Stream Data Store Smart Module, those streams which are prefixed with the value of this field will be processed and uploaded to the Video Smart Module.

Collecting video data


As we explained in the Introduction section, you need to upload data to the Stream Data Store Smart Module. So, please refer to How to collect data with the Stream Data Store Smart Module first if you are not familiar.

In order for the data uploaded to the Stream Data Store Smart Module to be processed and stored in the Video Smart Module, you need to upload the video data which will be captured in your IoT devices in a certain manner.

When you format the data to upload, it should be logically composed of two major parts: 1) video metadata which is represented by a MessagePack map; 2) actual video data that is unique to the types of Video uploading format.

Video metadata is a data map consisting of two key-value pairs:

  • searchKey: string value to be used for searching and retrieving video data
  • format: string value representing video data format

Currently, the only acceptable format is ts (Transport Stream). In the next section, we will explain the details of using the ts format in video data uploading.

How to send your ts files

The content of each ts file should be represented as a bin MessagePack data type. For example, if you have 10 ts files to send, you may need to create 10 bin-formatted MessagePack sequences. You are supposed to organize the MessagePack bin sequences in the same order as the ts files,right after the MessagePack map that contains the video metadata. The entire data sequence looks like the following.

  • map format data : e.g. {"seearchKey": "/foo/bar/1", "format": "ts"}
  • bin format data : e.g. content of seq0.ts
  • bin format data : e.g. content of seq1.ts
  • bin format data : e.g. content of seq2.ts
  • ...

If you can create and organize the data sequence, you are ready to send the data to the Stream Data Store Service. Note that the SDS Data Packets don't have to align with the boundaries of the MessagePack data sequences described in the table above. That means, as long as the order of the data sequence is maintained, chunks of multiple MessagePack data can be mixed up in one Data Packet. For example, your data can look like the following diagram.

Concept diagram of Video Smart Module

Retrieving video data

You can get access to the video clips that are stored in your Video Smart Module via REST API.

For instance, if you retrieve the videos from the my-video Smart Module in the Home 1234, make the following HTTP Request:

GET /homes/1234/smartModules/my-video/videos

The API call above will match all video clips in the my-video Smart Module. In a real use case, you may want to retrieve more specific data. You can do that by specifying either a searchKeyPrefix parameter or a searchKeys parameter.

If you use searchKeyPrefix parameter, your HTTP request will look like:

GET /homes/1234/smartModules/my-video/videos?searchKeyPrefix=/foo

This request will return the video clips whose searchKey is prefixed with /foo: e.g. /foo/1, /foo/2, and /foo/bar will match.

On the other hand, if you use the searchKeys parameter, your HTTP request will look like the following;

GET /homes/1234/smartModules/my-video/videos?searchKeys=/foo/1,/bar/1

In this request, only those video clips with searchKey matching either /foo/1 or /bar/1 will be returned. Use "," ( commas ) to delimit the search keys.

Regardless of whether you specify the searchKeys or searchKeyPrefix, the videos API will return the following JSON object as its response:

{
  "items": [
    {
      "homeId": 1234,
      "searchKey": "/foo/1",
      "video": "{url to mp4 file}",
      "thumbnail": "{url of image file}"
    },
    {...}
  ]
}

By default the number of the items in the response is limited to 20. You can change this limit by specifying the limit parameter in your request. That should be between 1 and 100.

If there are more video clips matching your query than the limit, the response JSON object will contain the nextToken field. For example:

{
  "nextToken": "5f7fd2867a0b107eca40e784",
  "items": [
    {
      "homeId": 1234,
      "searchKey": "/foo/1",
      "video": "{url to mp4 file}",
      "thumbnail": "{url of image file}"
    },
    {...}
  ]
}

If you need to retrieve the video clips after the first lot of matching items, use nextToken in the response JSON as the nextToken parameter in the next API Request. In the case above, your query will be the following HTTP request:

GET /homes/1234/smartModules/my-video/videos?searchKeyPrefix=/foo&nextToken=5f7fd2867a0b107eca40e784

For more details, please refer to the REST API Documentation for Video.