Canvases

Users can create drawings on videos to specify or highlight areas that particular comments refer to. A canvas holds these user drawings which then overlay videos. Drawings are shown at a fixed time in the video so each canvas needs an associated video and a playback time point indicating its position. Canvases can also have user comments and discussions associated with them.


Creating Drawings

Drawings can be created on top of videos by using the HTML5 'canvas' element. These drawings can be submitted for saving as attachment64 by calling the toDataURL() method on it. Make sure the dimensions of drawings match the size of the video (whether standard size or HD). One way you can do this is by sizing the canvas element (which users draw on) to match the video size. Check the HTML5 documentation on the canvas element for more information.


Required parameters

When saving a canvas, there are three required parameters that should be submitted as a POST request:

  • video_id (integer) - This is the VidPrep generated ID that identifies the video that the canvas overlays.
  • attachment64 (string) - The raw data of the image in base64 encoded Data URI string format.
  • video_playback_position (float) - The video time mark in seconds where the canvas is to be shown.

An example follows:

// a canvas element for drawing on, with z-index set to be above a video:
<canvas id="my_canvas" style="position: absolute; z-index: 1000;" height="443" width="640"></canvas>

// creating a reference to the element using javascript:
var user_drawing = document.getElementById('my_canvas');

// once drawing is complete, you can convert it into a format easily sent to VidPrep's servers:
attachment64 = user_drawing.toDataURL();

Head Up! Remember to account for the size of the video controls when determining the drawing canvas dimensions. This ensures that drawings don't accidentally get drawn over the controls.


Optional parameters

In addition to the required parameters, there are optional ones which can be submitted when creating canvas drawings. These values will be saved with the video and can be useful when displaying comments or threaded discussions with the videos.

  • user_name (string) - The canvas author name.
  • user_id (integer) - The id for the canvas/drawing creator.
  • user_image (string) - Location (url) of the profile image for the canvas author.
  • discussion_id (integer) - If the drawing is part of a larger discussion thread, this identifies the discussion.


Deleting canvases

Permanently remove videos through the API.

When deleting canvases, please be sure to have some form of confirmation interface on your end before submission to prevent accidental deletion.

To delete a canvas, submit a REST delete request with the following parameters:

  • video_id (integer) - This is the id of the video the canvas overlays.
  • id (integer) - This is simply the id of the canvas to be deleted.
  • user_id (integer) - Submit the user id of the canvas author to verify the correct canvas is being deleted.

These parameters are required and must match with the stored canvas for successful deletion.