Skip to end of metadata
Go to start of metadata

Table of Contents:

 

Class Diagram:

 

RESPONSE

URL Response Wrapper

This wrapper is just an easy way to wrap a list of assets that live inside a Video. It's used to wrap both scene and surface.

When querying the following Assets, this entity will be returned to you inside the response body:

These are the fields of a URLResponseWrapper

 

FieldField DescriptionField ValuesRequired
usernameName of the user who uploaded the videoSTRINGYES
videoIdVideoUpload IdLONGYES
videoUrlURL of the original (raw) videoSTRINGYES
totalTimeTime of the given entity (video or scene) in secondsFLOATNO
percentagePercentage of the work being done in the video that has been doneINTNO
videoNameName of the video fileSTRINGNO
statusStatus of the job being done on the entitySTRINGNO
scenesUrlList of scenes assets with the url of the first frame of the scene and the scene object inside each itemSCENES LISTNO
surfaceUrlList of surfaces assets with the url of the surface image and the object inside the listSURFACE LISTNO
scoresScores for each natural scene break. Used for Interstitial insertion

INTERSTITIAL_SCORE

LIST

NO
labelsList of labels for the entityLABEL LISTNO

This is a JSON example of the scene response (/cv_backend/api/video_upload/{id}/video):

{
  "error": null,
  "responseBody": {
    "username": "brunno",
    "videoId": "910",
    "videoUrl": "http://s3.amazonaws.com/brohan/brunno/b25f8fb9-fbf0-17a66e938475/video_analysis_pending.mp4",
    "totalTime": 9.6,
    "percentage": 100,
    "videoName": "video_high_shadow.mp4",
    "status": "EMBEDDING",
    "sceneUrls": [
      {
        "id": 4655,
        "url": "http://s3.amazonaws.com/brohan/brunno/b25f8fb9-fbf0-17a66e938475/scene_0/clean.jpg",
        "scene": {
          "initFrame": 0,
          "surfacesList": [
            {
              "id": 37473,
              "x": 297,
              "y": 720,
              "w": 844,
              "h": 342,
              "p1": null,
              "p2": null,
              "p3": null,
              "p4": null,
              "area": 52731
            }
          ],
          "label": [
            {
              "id": 10686,
              "name": "structure",
              "score": 0.94043523
            },
            {
              "id": 10687,
              "name": "sport venue",
              "score": 0.8187629
            },
            {
              "id": 10688,
              "name": "stadium",
              "score": 0.78140283
            },
            {
              "id": 10689,
              "name": "soccer specific stadium",
              "score": 0.7331199
            },
            {
              "id": 10690,
              "name": "games",
              "score": 0.70350242
            }
          ],
          "motion": false,
          "length": 240,
          "dbId": 4655,
          "imageLocation": "",
          "preview": false,
          "totalTime": 9.6,
          "motionValue": null,
          "initTime": 0,
          "confidenceScore": 11,
          "eligible": true,
          "file": "logo.png",
          "warp": false,
          "blend": true,
          "shadow": true,
          "facebookSafe": false
        }
      }
    ],
    "scores": [
      {
        "frame": 240,
        "score": 0,
        "time": 9.6
      }
    ],
    "labels": [
      {
        "id": 10676,
        "name": "hobbies & interest",
        "score": 1
      },
      {
        "id": 10677,
        "name": "structure",
        "score": 0.94043523
      },
      {
        "id": 10678,
        "name": "sport venue",
        "score": 0.8187629
      },
      {
        "id": 10679,
        "name": "stadium",
        "score": 0.78140283
      },
      {
        "id": 10681,
        "name": "games",
        "score": 0.70350242
      },
      {
        "id": 10682,
        "name": "basketball moves",
        "score": 0.69411737
      },
      {
        "id": 10684,
        "name": "arena",
        "score": 0.62757546
      },
      {
        "id": 10685,
        "name": "sports",
        "score": 0.56023037
      }
    ]
  }
}

This is a JSON example of a surface response (/cv_backend/api/video_upload/{id}/video/scene/{sceneId}/surface):

{
  "error": null,
  "responseBody": {
    "username": "brunno",
    "videoId": "910",
    "videoUrl": "http://s3.amazonaws.com/brohan/brunno/b25f8fb9-9508-17a66e938475/video_analysis_pending.mp4",
    "surfacesUrl": [
      {
        "id": 37473,
        "url": "http://s3.amazonaws.com/brohan/brunno/b25f8fb9-9508-17a66e938475/scene_0/surface0.jpg",
        "surface": {
          "id": 37473,
          "x": 297,
          "y": 720,
          "w": 844,
          "h": 342,
          "p1": null,
          "p2": null,
          "p3": null,
          "p4": null,
          "area": 52731
        }
      }
    ]
  }
}

 

VideoUpload:

The VideoUpload entity is a meta-entity that tracks the processing status of each video that has been uploaded by the user.

This entity is returned in the following queries/requests:

 

This are the following fields of this entity.

 

FieldField DescriptionField Values
idVideoUpload IdLONG
percentageProgress, in percent, of the current processing jobINTEGER
currentStatusCurrent status of the jobSTRING
finalUrlIf a new video has been produced by embedding a logo in the original (raw) video, its URL will appear here

STRING

 

messageAny message related to the status of the job or error of current running job.STRING
thumbnailURL of the Thumbnail of the videoSTRING
nameName of the file of the videoSTRING
createdDateTimestamp of the creation of the videoSTRING
totalTimeLength of the video in secondsDouble
labelsList of labelsLIST LABEL
warningMessageWarning Message in case of recoverable errorSTRING

This is a JSON example of the video upload response (/cv_backend/api/video_upload/{id} ) :

{
  "error": null,
  "responseBody": {
    "id": 1113,
    "percentage": 100,
    "currentStatus": "EMBEDDING",
    "finalUrl": "http://s3.amazonaws.com/brohan/brunno/fbf0-44d1-9508-17a66e938475/4/video_high_shadow-20170106 10-42-47.mp4",
    "message": "Embedding",
    "thumbnail": "http://s3.amazonaws.com/brohan/brunno/44d1-9508-17a66e938475/scene_0/clean_thumbnail.jpg",
    "name": "video_high_shadow.mp4",
    "createdDate": "2017-01-02 15:15:14",
    "totalTime": 9.6,
    "labels": null,
    "warningMessage": null
  }
}

 

Video:

The Video entity provides details about the uploaded video itself. Among other things, it contains a list of the Scene entities that have been parsed from the uploaded video. 

FieldField DescriptionField ValuesRequired
usernameName of the user who uploaded the videoSTRINGYES
videoIdVideoUpload IdLONGYES
videoUrlURL of the original (raw) videoSTRINGYES

Scene:

Scene entity provides details about a particular Scene that has been parsed from an uploaded video. Among other things, it details where the scene starts and ends and provides a list of the Surfaces that have been identified in the Scene. 

 

FieldField DescriptionField Values
idScene IdINTEGER
UrlURL of jpeg of Scene's first frame (raw)STRING
initFrameInitial Frame of SceneINTEGER
surfacesListList of Surfaces inside the SceneSURFACES LIST
motionBoolean field indicating if the Scene is a locked shot or notBOOLEAN
lengthNumber of frames on SceneINTEGER
dbIdDatabase Id of scene (main id)LONG
imageLocation  
preview BOOLEAN
totalTimeTime (in seconds) the Scene lastsDOUBLE
motionValue  
initTimeInitial Time of Scene (in seconds)DOUBLE
confidenceScoreConfidence score of the Scene (static Scenes with many Surfaces have a high score).DOUBLE
eligibleIndicates if Scene is good for Logo placement or notBOOLEAN
fileLogo file previous uploadedSTRING
warpIf the scene has automatic warp or notBOOLEAN
blendIf the scene has automatic blend or notBOOLEAN
shadowIf the scene has automatic shadow or notBOOLEAN
facebookSafeIf you want to activate the facebook safe for the logo placement in this sceneBOOLEAN

Label:

The Label entity provides details about the automatic labelling information of the given entity:

FieldField DescriptionField Values
idLabel IdLONG
nameLabel nameSTRING
scoreConfidence scoreDouble

 

Surface:

The Surface entity provides details about a particular Surface that has been identified inside a Scene. 

 

FieldField DescriptionField Values

id

Id of the SurfaceINTEGER
xUpper left point x coordinate (for Rectangular area)INTEGER
yUpper left point y coordinate (for Rectangular area)INTEGER
wWidth of the rectangle (for Rectangular area)INTEGER
hHeight of the rectangle (for Rectangular area)INTEGER

p1

x and y coordinates for top left corner (for Free form area)LIST <INTEGER>

p2

x and y coordinates for bottom left corner (for Free form area)LIST <INTEGER>

p3

x and y coordinates for bottom right corner (for Free form area)LIST <INTEGER>

p4

x and y coordinates for top right corner (for Free form area)LIST <INTEGER>
areaArea of the SurfaceDOUBLE

REQUEST

SCENE AND SURFACE

The Scene and Surface entities are uploaded on the following request:

Entity
JSON Example
JSON Schema
Surface

Make sure the field id is null

{
          "id"null,
          "x"510,
          "y"106,
          "w"122,
          "h"75,
          "p1"null,
          "p2"null,
          "p3"null,
          "p4"null,
          "area"9150
        }
{
  "type""object",
  "properties": {
    "id": {
      "type""integer"
    },
    "x": {
      "type""integer"
    },
    "y": {
      "type""integer"
    },
    "w": {
      "type""integer"
    },
    "h": {
      "type""integer"
    },
    "p1": {
      "type""array",
      "items": {
        "type""integer"
      }
    },
    "p2": {
      "type""array",
      "items": {
        "type""integer"
      }
    },
    "p3": {
      "type""array",
      "items": {
        "type""integer"
      }
    },
    "p4": {
      "type""array",
      "items": {
        "type""integer"
      }
    },
    "area": {
      "type""integer"
    }
  },
  "required": [
    "id",
    "x",
    "y",
    "w",
    "h",
    "p1",
    "p2",
    "p3",
    "p4",
    "area"
  ]
}
Scene

Make sure the field dbId is null

{
          "initFrame"0,
          "surfacesList": [],
          "motion"false,
          "length"10000000,
          "dbId": null,
          "imageLocation""",
          "preview"false,
          "totalTime"0,
          "motionValue"1,
"initTime": 0,
"confidenceScore": 5,
"eligible": true
}
 {
  "type""object",
  "properties": {
    "initFrame": {
      "type""integer"
    },
    "surfacesList": {
      "type""array",
      "items": {
         "type""object",
          "properties": {
            "id": {
              "type""integer"
            },
            "x": {
              "type""integer"
            },
            "y": {
              "type""integer"
            },
            "w": {
              "type""integer"
            },
            "h": {
              "type""integer"
            },
            "p1": {
              "type""array",
              "items": {
                "type""integer"
              }
            },
            "p2": {
              "type""array",
              "items": {
                "type""integer"
              }
            },
            "p3": {
              "type""array",
              "items": {
                "type""integer"
              }
            },
            "p4": {
              "type""array",
              "items": {
                "type""integer"
              }
            },
            "area": {
              "type""integer"
            }
          },
          "required": [
            "id",
            "x",
            "y",
            "w",
            "h",
            "p1",
            "p2",
            "p3",
            "p4",
            "area"
          ]
        }
      }
    },
    "motion": {
      "type""boolean"
    },
    "length": {
      "type""integer"
    },
    "dbId": {
      "type""integer"
    },
    "imageLocation": {
      "type""string"
    },
    "preview": {
      "type""boolean"
    },
    "totalTime": {
      "type""number"
    },
    "motionValue": {
      "type""number"
    },
    "initTime": {
      "type""integer"
    },
    "confidenceScore": {
      "type""number"
    },
    "eligible": {
      "type""boolean"
    }
  },
  "required": [
    "initFrame",
    "surfacesList",
    "motion",
    "length",
    "dbId",
    "imageLocation",
    "preview",
    "totalTime",
    "motionValue",
    "initTime",
    "confidenceScore",
    "eligible"
  ]
}

 

Custom Request

The customized scene and surface request can be made to the following endpoint

 

 

 

Entity
JSON Example
Json Schema
CustomRequest

Make sure the field id, from the surface, is null

{  
   "surfaceList":[  
      {  
         "sceneId":1234,
         "surface":{  
            "id":null,
            "x":510,
            "y":106,
            "w":122,
            "h":75,
            "p1":null,
            "p2":null,
            "p3":null,
            "p4":null,
            "area":0
         }
      }
   ]
}
{
  "type": "object",
  "properties": {
    "surfaceList": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sceneId": {
            "type": "integer"
          },
          "surface": {
            "type": "object",
            "properties": {
              "id": {
                "type": "null"
              },
              "x": {
                "type": "integer"
              },
              "y": {
                "type": "integer"
              },
              "w": {
                "type": "integer"
              },
              "h": {
                "type": "integer"
              },
              "p1": {
                "type": "null"
              },
              "p2": {
                "type": "null"
              },
              "p3": {
                "type": "null"
              },
              "p4": {
                "type": "null"
              },
              "area": {
                "type": "integer"
              }
            },
            "required": [
              "id",
              "x",
              "y",
              "w",
              "h",
              "p1",
              "p2",
              "p3",
              "p4",
              "area"
            ]
          }
        },
        "required": [
          "sceneId",
          "surface"
        ]
      }
    }
  },
  "required": [
    "surfaceList"
  ]
}
  • No labels