Skip to main content

SiteTrax.io API - Input (Video)

Getting Started

The SiteTrax.io backend requires a centralized data storage to transfer data to and from it. Currently, Amazon AWS S3 buckets are supported as the recommended data store.  If needed, the bucket information and access keys can be provided by SiteTrax.io or your organization is welcome to set up their own S3 buckets. Please submit a support ticket to request a bucket and access keys to process videos. 

Request API Server Access>>

For instructions on setting up a test environment, please see the Test Development Environment - Setup SiteTrax Test API and JSON article.

Overview

The SiteTrax.io backend analyzes video stored in an Amazon S3 bucket and outputs that data to any REST API server.

SiteTrax.io Architecture Diagram 20211221.jpg

Reference: https://docs.google.com/drawings/d/1ZwDE18DMtbIDPIujX_M61jRm2SvanIolZJ7RsnY4XW0/edit

Step #1: Upload Video (Push) - See Input - Video Specifications below for more details

  • Option #1: Using the SiteTrax.io Android app, capture video using any mode, which will upload capture and upload the video automatically for you into a storage bucket.
  • Option #2: Upload video (no more than 1 minute in length) to the Amazon S3 bucket provided.

Step #2: REST API Server (Push)

After the video is uploaded in Step #1 above, the SiteTrax.io Backend will analyze the video and push the data analyzed to any REST API server via the SiteTrax.io Router. See Output - REST API section below forpage more information.

NOTE: Make sure to request API Server access via the link in the Overview section above.

Input - Video Specifications

The files that should be uploaded in {bucket_name}/notprocessed folder. The maximum recommended length of a video is 1 minute.

  1. Video length: If the video is more than 1 minute in length, it is recommended to split the video into multiple 1 minute videos.
  2. The recommended resolution of video is 1920x1080 with a frame rate of 30 frames per second.
  3. The lens of 6mm or longer should be used. A lens less than 5mm could cause distortion and the backend may not be able to read the OCR.
  4. The GPS information should be embedded in the subtitles of the video (this can be overwritten for static cameras)

SiteTrax.io Camera Types

SiteTrax.io can capture data from many different types of cameras including Android and basic security cameras. For implementation purposes, we recommend:

  1. SiteTrax.io Mobile Appapp (i.e. Android) - Many cameras for one bucket. The GPS coordinates are dynamically sent base on the location of the mobile app.
  2. StationarySiteTrax.io Gate or stationary camera - One camera to onedata bucket.store. The GPS coordinates have to be manually defined for each camera.

GPS Encoding

Below is an example of embedded subtitles in SRT format.

1
00:00:00,000 --> 00:00:00,150
36.8626459 -76.2314164

2
00:00:00,150 --> 00:00:00,300
36.8626459 -76.2314164

3
00:00:00,300 --> 00:00:00,450
36.8626459 -76.2314164
.
.
.

Video creation time should be present in both video stream and subtitle stream. In addition to this, creation time should also be present in file metadata. Video should be in mp4 format only. Below in an example of metadata as ffmpeg output.

Input #0, mov,mp4,m4a,3gp,3g2,mj2, from '2_20211018T042608717Z_s00.mp4':
  Metadata:
    major_brand     : isom
    minor_version   : 512
    compatible_brands: isomiso2avc1mp41
    creation_time   : 2021-10-18T16:26:08.000000Z
    encoder         : Lavf58.67.100
  Duration: 00:00:14.55, start: 0.000000, bitrate: 29921 kb/s
  Stream #0:0(eng): Video: h264 (Baseline) (avc1 / 0x31637661), yuvj420p(pc, smpte170m/bt470bg/smpte170m), 1920x1080, 33017 kb/s, SAR 1:1 DAR 16:9, 30.04 fps, 30 tbr, 90k tbn (default)
    Metadata:
      creation_time   : 2021-10-18T16:26:08.000000Z
      handler_name    : VideoHandle
      vendor_id       : [0][0][0][0]
    Side data:
      displaymatrix: rotation of -90.00 degrees
  Stream #0:1(und): Subtitle: mov_text (tx3g / 0x67337874), 1 kb/s (default)
    Metadata:
      creation_time   : 2021-10-18T16:26:08.000000Z
      handler_name    : SubtitleHandler

Sample videos can be found here.

Video Upload

Once a video is generated, it can be uploaded to your designated bucket. The code to upload the video to the bucket is below.

import boto3


s3_client = boto3.client('s3', aws_access_key_id='', 
                    aws_secret_access_key='', 
                    region_name='eu-central-1'
                    )
s3_client.upload_file('/internal video path', bucket_name, 'notprocessed/' + video_name + '.mp4')

Once the video upload is complete, SiteTrax.io backend will start processing the video. The processing time is proportional to the number of trackable assets in the video.

If records from a video do not show up please check our status page or if all services are up then please file a support ticket at our support page.

Back to top