Video Management

Once you create an account, you can upload videos for storage, submit drawings and comments tied to a video and manage all these elements for display. Comments can be associated with threads and displayed in order of creation (as a running discussion). Both drawings and comments can be tied to a specific time point in the video.


Uploading Videos

To upload a video to your account send a multipart POST request to http://localhost:3999/videos.

Valid parameters for uploading the video are:

  • api_key (string) - Your API key (required)
  • attachment (file) - Video file (required)
  • hd (boolean) - Whether the video should be in HD quality (default false)
  • foreign_id (string) - Foreign video ID, set by you
  • callback (string) - After the video is finished processing, the JSON data will be POSTed to this URL.

Example multipart POST to upload a video file:

POST "http://localhost:3999/videos"
     api_key="XXXXXXXXXXXXXXXX"
     attachment=[VIDEO_FILE]
     hd="true"
     foreign_id="my_video_id_1"
     callback="http://yourdomain.com/vidprep_callback"

Example response: see the example JSON response below


Getting Video Information


To get information on one of your videos, submit an HTTP GET request with the ID of the video and your API key.

Example request paths for retrieving video information:

Example 1: Using the video ID specified by VidPrep, where the video ID is OOOOOOOO and your api_key is XXXXXXXXXXXXXXXX:

GET "http://localhost:3999/videos/OOOOOOOO.json?api_key=XXXXXXXXXXXXXXXX"

Example 2: Using a foreign video ID that you have previously specified (it will probably correspond to the video's ID in your database) and an api_key of XXXXXXXXXXXXXXXX:

GET "http://localhost:3999/videos/foreign/YOUR_FOREIGN_VIDEO_ID.json?api_key=XXXXXXXXXXXXXXXX"

Example JSON response:

{
  "allow_notations":true,
  "created_at":"2012-01-16T22:23:12Z",
  "duration":11362,
  "hd":false,
  "name":"short video.mp4",
  "pause_comments":true,
  "public":false,
  "size":20589,
  "state":"finished",
  "mp4":"http://vidcoder.s3.amazonaws.com/accounts/2/videos/FUJJswK9/video.mp4",
  "vidprep_id":"FUJJswK9",
  "width":640,
  "height":480,
  "webm":"http://vidcoder.s3.amazonaws.com/accounts/2/videos/FUJJswK9/video.webm",
  "thumbnail":"http://vidcoder.s3.amazonaws.com/accounts/2/videos/FUJJswK9/thumb.png"
}

Details about the response data:

  • allow_notations (boolean) - Allow comments and drawings on the video?
  • created_at (datetime) - Created date and time for video
  • duration (integer) - Video length in milliseconds
  • foreign_id (string) - The foreign ID that you have previously supplied (if available)
  • hd (boolean) - Is the video in HD quality?
  • name (string) - The original video filename
  • pause_comments (boolean) - Will the video pause while displaying comments?
  • progress (string) - the processing progress (%) of the video (only valid when state = processing)
  • public (boolean) - Is the video publicly viewable? (default false)
  • size (integer) - Video file size in bytes
  • state (string) - The server status of the video. Valid states include: waiting, queued, pending, transferring to storage, processing, finished, failed, cancelled
  • mp4 (string) - The URL of the MP4 video file
  • vidprep_id (string) - The unique VidPrep generated identifier for the video
  • width (integer) - Native video width size in pixels
  • height (integer) - Native video height size in pixels
  • webm (string) - The URL of the WEBM video file
  • thumbnail (string) - The URL of the thumbnail for the video (in PNG format)

Not all fields will be present. For example, the foreign_id will only exist for foreign videos.

With this video information, you'll be able to set up your site any way you like. You'll know exactly where to set the video and frame elements around it based on the height, width and HD status. And with the unique vidprep_id, you'll be able to retrieve the associated drawings and comments for display on your page.


Resumable uploader

The resumable uploader allows you to upload large videos by splitting the file into smaller chunks. The uploading process can be paused and resumed at a later time. The first step in this process is to create a unique SHA1 hash of the video that will serve as its temporary identifier. To avoid hash collisions, it is recommended that you create a SHA1 hash consisting of:

YOUR_API_KEY + FILENAME + FILESIZE_IN_BYTES + RAW_FILE_DATA

Here's some pseudocode as an example:

SHA1("XXXXXXXXXXXXXXXX" + "movie.mp4" + my_file.size.to_string() + my_file.data.to_string())

You will also need to create a foreign_id to uniquely identify the video. When uploading a chunk, send an HTTP POST to http://uri.vidprep.com/chunks/SHA1 with the following parameters:

  • api_key(string) - Your API key (required)
  • callback (string) - After the video is finished processing, the JSON data will be POSTed to this URL.
  • file (file) - The chunk data as a blob
  • foreign_id (string) - Foreign video ID, set by you (required)
  • hd (boolean) - Whether the video should be in HD quality (default false)
  • resumable_chunk_number (integer) - The chunk number of the video file (NOT zero-based, starts at 1)
  • resumable_filename (string) - The name of the video
  • resumable_total_size (integer) - The size in bytes of the entire video file

Heads up! Please note that the domain for chunks is http://uri.vidprep.com and NOT http://api.vidprep.com.

An example of uploading a single chunk:

POST "http://uri.vidprep.com/chunks/4e224506c899348ed9bb6c665ba1966c5eb0ea76"
     api_key="XXXXXXXXXXXXXXXX"
     callback="http://yourdomain.com/vidprep_callback"
     file=[VIDEO_FILE_BLOB]
     foreign_id="my_video_id_2"
     hd="true"
     resumable_chunk_number=72
     resumable_filename="my video.mp4"
     resumable_total_size=28571521

Multiple chunks can be uploaded simultaneously. To check whether a particular chunk has finished uploading, send a GET request with the SHA1, chunk number, and your API key. For example, if the SHA1 is 4e224506c899348ed9bb6c665ba1966c5eb0ea76 and you want to check on chunk number 72:

GET "http://localhost:3999/chunks/4e224506c899348ed9bb6c665ba1966c5eb0ea76?resumable_chunk_number=72&api_key=XXXXXXXXXXXXXXXX"

If the chunk exists, the response will have an HTTP status code of 200. If the chunk does not exist, the response will have an HTTP status code of 202. In either case, the response message will be the highest consecutive chunk number that has successfully been uploaded. An example response confirming that chunk number 72 has been uploaded:

HTTP/1.1 200 OK
72

After all chunks have been successfully uploaded, you can check on the status of the video by getting the video information.


Listing All Your Videos

Log into your account where you can view all of your videos via the web interface.


Retrieving Videos for Display

To show one of your videos on your web page, refer to the embedding videos page.

You can use the default HTML5 video controls by setting your video option for controls. Alternatively, you can create and implement your own custom controls.


Deleting Stored Videos

Once you no longer need a video or to free up space on your account submit an HTTP DELETE request with the video ID and your API key. Make sure you have some sort of user confirmation feature on your front end to avoid accidental deletion of videos.

Example 1: Using the video ID specified by VidPrep, where the video ID is OOOOOOOO and your api_key is XXXXXXXXXXXXXXXX:

DELETE "http://localhost:3999/videos/OOOOOOOO"
       api_key="XXXXXXXXXXXXXXXX"

Example 2: Using a foreign video ID that you have previously specified (it must be specified in the URL and the parameters) and an api_key of XXXXXXXXXXXXXXXX:

DELETE "http://localhost:3999/videos/YOUR_FOREIGN_VIDEO_ID"
       api_key="XXXXXXXXXXXXXXXX"
       foreign_id="YOUR_FOREIGN_VIDEO_ID"

The response will be the vidprep_id of the video.

Example Response:

OOOOOOOO