Video API

From DocuWiki
Revision as of 10:42, 17 July 2014 by 0oqb9d (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

The Video secton of the API is the most commonly used and thus the more complex element of the API, providing features to view, add, edit and remove videos from the 247 Platform.


Get

Returns the information on a video on the 247 Platform

Request URL

http://console.247platform.com/api/video/get/[video id]?sessionId=[Session ID]&userId=[Client Id]

Params: none.

Response
{
  "response":{
     "video":{
        "videoId":"12345",
        "title":"My Live Video",
        "categoryId":"230",
        "published":"1",
        "thumbnailKey":"https:\/\/s3-eu-west-1.amazonaws.com\/247platform-test\/247platform-images\/42\/12345\/custom-908.png",
        "live":{
           "formatId":"7",
           "enabled":true,
           "videoFormatSettings":{
              "videoFormatId":"7",
              "enabled":"1",
              "streamName":"2c-61e-live",
              "requiresAuth":"1"
           },
           "primaryStreamingDetails":{
              "protocol":"rtmp",
              "portNumber":"1935",
              "publicDNS":"46.137.7.26",
              "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com",
              "application":"origin",
              "stream":"2c-61e-live"
           },
           "backupStreamingDetails":{
              "protocol":"rtmp",
              "portNumber":"1935",
              "publicDNS":"46.137.7.26",
              "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com",
              "application":"origin",
              "stream":"2c-61e-live"
           },
           "publishString":{
              "protocol":"rtmp",
              "portNumber":"1935",
              "publicDNS":"46.137.7.26",
              "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com",
              "application":"origin",
              "stream":"2c-61e-live"
           }
        },
        "vod":{
           "formatId":"9",
           "enabled":true,
           "settings":{
              "protocol":"rtmp",
              "portNumber":"1935",
              "publicDNS":"46.137.7.26",
              "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com",
              "application":"vods3",
              "stream":"2c-61e-vod"
           }
        },
        "download":{
           "formatId":"8",
           "enabled":false
        }
     },
     "code":"200",
     "isOk":true
  },
  "code":"200"
}

Errors

  • 404 ResourceNotFound - We are unable to locate the Video ID you requested
  • 400 AuthenticationRequired - Authentication is required but not provided.


Put

Create a new video on the 247 Platform.

Request URL

http://console.247platform.com/api/video/put/?sessionId=[Session ID]&userId=[Client Id]&categoryId=[Category Id]&published=[1 or 0]

Params

  • `videoTitle` (required), String, Title you wish to change the video to
  • `categoryId` (required), Integer, Category Id you wish to change this Video to
  • `published` (required), Integer, 1 for published, 0 for not.


Response

{
  "response":{
     "videoId":1705,
     "data":{
        "title":"My New Video",
        "categoryId":"270",
        "published":1,
        "ownerId":42
     },
     "clientId":42,
     "log":{
        "formats":{
           "live":"7",
           "vod":"9",
           "download":"8"
        },
        "uniqueIdentifer":"2c-78a",
        "streamNames":{
           "live":"2c-78a-live",
           "vod":"2c-78a-vod"
        }
     },
     "code":"200",
     "message":"Video has been added.",
     "isOk":true
  },
  "code":"200"
}

Errors

  • 400 AuthenticationRequired - Authentication is required but not provided.
  • 404 ResourceNotFound - One or more of the required params where not passed.


Update

Updates the title, category and publish status of a video

Request URL

http://console.247platform.com/api/video/update/[Video Id]/?video=[JSON Object]&sesionId=[Session ID]&userId=[Client ID]

Params

  • Video Id (Required), Int, ID of the video you wish to update
  • `video` (Required), String, The JSON reporesentation of the details you wish to update for the video, e.g.:
{
  "title":"My New Title",
  "categoryId":4,
  "published":0
}

Response

{
  "response":{
     "code":"200",
     "message":"Video Updated.",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.


Authenticate

Creates an authentication record for a users' IP against a video stream, providing them the ability to watch the video. See the Embedding Your Video page on how to the response from this API call to embed secure URLs.

Request URL

http://console.247platform.com/api/video/authenticate/?ip=[Viewer IP]&streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]&returnAll=[1 or 0]&ttl=[TTL]

Params

  • `ip` (Required), String, The IP address of the viewer (not of the web server, or any load-balancer), you can pass a * (asterix) which will allow any IP to connect to the video
  • `streamName` (required), String, The stream name of the video you're authenticating the user to watch.
  • `ttl`, Int, Seconds, how long can the video be played before the viewer needs to refresh the page to get a new authorisation. Defaults to 21600 seconds (5 hours).
  • `returnAll`, Integer, 1 for returning the video source url - (allows you to use your own custom player and integration), 0 for not.

Response

{
  "response":{
     "clientIp":"192.168.100.1",
     "streamName":"aa-b1234-live",
     "authHash":"34ce63220112342cdb63204298788f323",
       "videoSource":"Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmfdsfds2NlIjoiKjJjLWI5YWE0KiIsICJDb25kaXRpb24iOnsiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE0MDI5NDk1OTJ9fX1dfQ__&Signature=WnN3~AXC~t-hIOIJbOu61r4~DHWcKgfdsfsdttwFvryL2KZWraQefZTWsAhw~9BIbFYj-yuSyI~FKUX1f6ZSOA4MCTpsMLKqv96kO6TYs0J5JZPpgxdhvtAcnS2zIRitoUhV7zh18Zn8lmQL4fAzoiX5y-HQgqMohcNISKZpfjuwG7F2LXvtqfqAFlkLn3P74UI2aUSk0P1GP3TsUX3wc3I8PJUGSTRb5X5R6NezISQ7Te1Mf9YZNA4VE5bHDFy3mtDq7x5TXemSf5hHybu~2MOau0YEZp9-M1GoSfCsPxC6~Z4WVsErbu1gTvMVuIOAlvmSQvqXR2BgpsFShzH-3PS9cQ6Oo~A__&Key-Pair-Id=APKAII5FS2T7S2UQ4YHQBARA",
     "code":"200",
     "isOk":true
  }
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

Status

Returns the status of the video, so that it can be used to check the video's status before embedding the player, and handle errors in your own fashion.

Request URL

http://console.247platform.com/api/video/status/?streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]

Params

  • `streamName` (Required), String. the stream name of the video you wish the status of.
  • `ip` (optional), String, The viewers IP address, required if you wish to include a Geoblocking check against the user in the response.

Response

{
  "response":{
     "video":{
        "live":true,
        "original":"2c-61e-live",
        "uniqueIdentifer":"2c-61e",
        "simpleName":"2c-61e-live"
     },
     "errors":[
     ],
     "code":"200",
     "isOk":true
  },
  "code":"200"
}

Possible Responses

The `errors` array can contain a number of possible keys and descriptions:

  • COM_PLATFORM247_EMBED_ERROR_NOTEXIST : The video doesn't exist
  • COM_PLATFORM247_EMBED_ERROR_VIDEONOTPUBLISHED - The video hasn't been published.
  • COM_PLATFORM247_EMBED_ERROR_CATEGORYNOTPUBLISHED - The category (or one of the parent categories) of this video hasn't been published.
  • COM_PLATFORM247_EMBED_ERROR_VIDEONOTENABLED - The requested format hasn't been abled for this video.
  • COM_PLATFORM247_EMBED_ERROR_GEOBLOCKED - The video has been geoblocked for the given IP address

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.



Delete

Deletes any physical objects for a video such as recordings and thumbnails, does not remove the video from the 247 Platform to ensure you continue to have access to log information.

Request URL

http://console.247platform.com/ap/video/delete/[Video Id]/?deleteThumbs=[deleteThumbs]

Params

  • Video Id (Required), Integer, The Video ID that you're trying to delete
  • `deleteThumbs`, Integer, 1 or 0, if you wish to delete an thumbnail images also.

Response

{
  "response":{
     "code":"200",
     "message":"VOD has been deleted.",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.



isPublishing

Returns the connection status of the streams required to publish the live stream. For videos using more than one bitrate, it will return each individual required stream with it's own publishing status.

Request URL

http://console.247platform.com/api/video/ispublishing/?streamname=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]

Params

  • `streamName` (reqired) String - Stream name to verify

Response

{
  "response":{
     "isPublishing":{
        "isPublishing":{
           "1":{
              "name":"platform-example-270p-500",
              "publishing":1,
              "streamName":"2c-61e-live-1"
           },
           "2":{
              "name":"platform-example-360-1000",
              "publishing":1,
              "streamName":"2c-61e-live-2"
           },
           "3":{
              "name":"platform-example-360-1500",
              "publishing":0,
              "streamName":"2c-61e-live-3"
           },
           "4":{
              "name":"platform-example-540-2500",
              "publishing":0,
              "streamName":"2c-61e-live-4"
           },
           "5":{
              "name":"platform-example-576-3500",
              "publishing":0,
              "streamName":"2c-61e-live-5"
           }
        },
        "publishingOk":0
     },
     "timeoutSeconds":60,
     "code":"200",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.




UploadFormParams

Returns parameters required to host your own upload form for transferring files to an Amazon S3 Folder so that they can be transcoded through the 247 Platform.

Request URL

http://console.247platform.com/api/video/uploadformparams/?sessionId=[Session ID]&userId=[Client ID]

Response

{
  "response":{
     "policy":"eyJleHBpcmF0aW9uIjogIjIwMTMtMDYtMjBUMDk6MTE6MTlaIiwiY29uZGl0aW9ucyI",
     "signature":"KtzHA6RoypairnKrOsiY8UVadRFbsrM=",
     "AWSAccessKeyId":"dKtzsHA6eRoywpainqKrOieY8UVdRFbrM",
     "s3BucketName":"247platform-test",
     "key":"users\/635\/uploads\/${filename}",
     "scriptUrl":"http:\/\/247platform-test.s3.amazonaws.com\/"
     "code":"200",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.

Usage

Once you have the parameters above you can host your own upload form, we use the jQuery plugin 'uploadify' to implement our upload form. An example of an implementation with uploadify: http://www.flynsarmy.com/2011/03/upload-to-amazon-s3-with-uploadify/

Using the parameters in the example response above you would fill in the gaps as so:

<script type="text/javascript">
$(document).ready(function() {
   $("#file_upload").uploadify({
    'uploader' : '<?= WEBROOT ?>files/uploadify/uploadify.swf',
    'buttonText' : 'Browse',
    'cancelImg' : '<?= WEBROOT ?>files/uploadify/cancel.png',
    'script' : '<?=$this->apiResponse->scriptUrl ?>',
    'scriptAccess' : 'always',
    'method' : 'post',
    'scriptData' : {
    "AWSAccessKeyId" : "<?=$this->apiResponse->AWSAccessKeyId ?>",
    "acl" : "authenticated-read",
    "policy" : "<?=$this->apiResponse->policy ?>",
    "signature" : "<?=$this->apiResponse->signature ?>",
    "success_action_status" : "201",
    "key" : "<?=$this->apiResponse->key ?>",
    "fileext" : "",
    "Filename" : ""
},
 'fileExt' : '*.*',
 'fileDataName' : 'file',
 'simUploadLimit': 2,
 'multi' : true,
 'auto' : true,
 'onError' : function(errorObj, q, f, err) { console.log(err); },
 'onComplete' : function(event, ID, file, response, data) { console.log(file); }
 });
});
</script> 


ListVideosByCategory

List your videos for a specified optional list of categoryids

Request URL

http://console.247platform.com/api/video/listvideosbycategory/?sessionId=[Session ID]&userId=[Client Id]&categoryIds=[Category Ids]

Params

  • `categoryIds` (optional), String, List of categories to pull videos for, format required is 1-2-3-4 (each category separated by a dash) if no category is specified we return all your videos

Response

[
 {
   "videoId":"9",
   "title":"test",
   "categoryId":"98",
   "published":"-2",
   "formats":[
     {
       "title":"Live Flash",
       "videoFormatId":"7",
       "isLive":"1",
       "isVod":"0",
       "isDownload":"0",
       "published":"1"
     }
   ]
 },
 {
   "videoId":"10",
   "title":"test",
   "categoryId":"98",
   "published":"1",
   "formats":[
     {
       "title":"VOD Flash",
       "videoFormatId":"9",
       "isLive":"0",
       "isVod":"1",
       "isDownload":"0",
       "published":"1"
     }
   ]
 },
 {
   "videoId":"11",
   "title":"vide 2",
   "categoryId":"98",
   "published":"1",
   "formats":[
     {
       "title":"Live Flash",
       "videoFormatId":"7",
       "isLive":"1",
       "isVod":"0",
       "isDownload":"0",
       "published":"1"
     },
     {
       "title":"VOD Flash",
       "videoFormatId":"9",
       "isLive":"0",
       "isVod":"1",
       "isDownload":"0",
       "published":"1"
     }
   ]
 }
]

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.




ListViewers

Returns a list of users who are viewing a particular stream in the last 10 minutes.

Request URL

http://console.247platform.com/api/video/listviewers/?streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]

Params

  • `streamName` (reqired) String - Stream name to verify

Response

{
  "response":{
     "viewers":{
           {
              "ipaddress":"78.129.148.101",
              "country_name":"United Kingdom",
              "city_name":"London"
           },
           {
              "ipaddress":"94.197.127.197",
              "country_name":"United Kingdom",
              "city_name":"London"
           },
     },
     "code":"200",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.



RemoveAuth

Disconnect a user from viewing a stream.

Request URL

http://console.247platform.com/api/video/removeauth/?streamName=[Stream Name]&ipAddress[IP Address]&sessionId=[Session ID]&userId=[Client ID]

Params

  • `streamName` (required) String - Stream name to verify
  • `ipAddress` (required) String - IP to disconnect

Response

{
  "response":{
     "code":"200",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.
  • InternalError (code 500) The stream was not found or the user was found to not be watching the stream anymore


Download

Creates signed URLs so VOD content can be downloaded from the 247 Platform.

Request URL

 http://console.247platform.com/api/video/download/?filename=[Video File NAme]&sessionId=[Session ID]&userId=[Client ID]

Params

Response

{
  "response":{
     "link":"https://247platform-test.s3.amazonaws.com/users/99/588897/3/ab-12345-6-720-1280-5000.mp4?AWSAccessKeyId=AASO4WRSSEIJAWDA&Expires=1395142829&Signature=afEmzVSLsdurssaSlvAYmg%2Bjj3ytM%3D",
     "TTL":"300"
  },
  "code":"200"
}



Create Viewer Login Credential

Creates a login credential for the viewer to watch the video

Request URL

http://console.247platform.com/api/video/createviewercredential/[Video Id]/?password=[Password]&email=[Email]&liveEnabled=[Live Enabled]&vodEnabled=[Vod Enabled]&downloadEnabled=[Download Enabled]&sesionId=[Session ID]&userId=[Client ID]

Params

  • Video Id (Required), Int, ID of the video you wish to create a login credential for
  • Email (Required), String, The email address of the viewer
  • Password (Required), String, A password for the viewer
  • Live Enabled , Int, Is the live video to be enabled under this credential
  • Vod Enabled , Int, Is the vod video to be enabled under this credential
  • Download Enabled , Int, Is the download video to be enabled under this credential

Response

{
  "response":{
     "code":"200",
     "message":"Credential Created.",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • MissingRequiredQueryParameter (code 400), One or more of the required params where not passed.
  • FailedToPerformAction (code 400), Failed to Perform the Action.




Delete Viewer Login Credential

Delete a login credential

Request URL

http://console.247platform.com/api/video/deleteviewercredential/[Video Id]/?email=[Email]&sesionId=[Session ID]&userId=[Client ID]&videoName=[Video Name]

Params

  • Video Id (Required), Int, ID of the video you wish to delete a login credential for
  • Email (Required), String, The email address of the viewer
  • Video Name (Required), String, The video name to delete credential for - eg: 4d-564-vod or 4d-564-live

Response

{
  "response":{
     "code":"200",
     "message":"Credential Deleted.",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • MissingRequiredQueryParameter (code 400), One or more of the required params where not passed.
  • FailedToPerformAction (code 400), Failed to Perform the Action.

Viewer Statistics

Retrieve the viewing stats for a video. The duration stats will only show for any views recorded after 11th July 2014

Note: the uid field below can be set using the embed url parameter "uid" as below, if you do not specify the uid then we will set the uid to the value of a cookie which is placed on the viewers device (1 yr expiration cookie) - this cookie value stays the same when the viewer navigates to different videos.

http://console.247platform.com/embed/?v=4d-355-vod&uid=1234

Request URL

http://console.247platform.com/api/video/viewerstats/[Video Id]/?sesionId=[Session ID]&userId=[Client ID]

Params

  • Video Id (Required), Int, ID of the video you wish to retrieve stats for

Response

{
  "response":{
     "statsLive":{
           {
              "ip":"78.129.148.101",
              "hash":"0137o34ims1huba3d3cqc0huo1.88705831",
              "uid":"f123f87653e143d0810a9c8dbe2f29c9"
              "updated":"12-07-14 20:59:33",
              "created":"12-07-14 20:57:33",
              "userAgent":"Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
              "duration":"1258",
              "seeks":"1",
              "videoName":"2c-b9edb-live",
           },
           {
              "ip":"80.215.229.114",
              "hash":"c52f3c6efqeu2t4ou843mjc647.46817052",
              "uid":"b66f6a183af2e0984478b3a331fb5f1d"
              "updated":"12-07-14 08:58:13",
              "created":"12-07-14 08:58:13",
              "userAgent":"Mozilla/5.0 (iPhone; CPU iPhone OS 5_0_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A405 Safari/7534.48.3",
              "duration":"0",
              "seeks":"0",
              "videoName":"2c-b9edb-live",
           },
     },
     "code":"200",
     "isOk":true
  },
  "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • MissingRequiredQueryParameter (code 400), One or more of the required params where not passed.
  • FailedToPerformAction (code 400), Failed to Perform the Action.