This module provides simple annotation capabilities for videos embedded in a Drupal node. The supported embedding formats depend on the available drivers. For now, this is limited to videos embedded using the HTML5 video element without iframes.
The PHP and JavaScript both have hooks for extending the types of shapes and bodies that can be used to annotate a video. See the PHP and JavaScript Hooks sections below.
The general directions for installing modules in Drupal 7 should work for this module. The following are additional installation requirements and settings that you may need to follow for this module to work properly.
Note that this module is not published to the Drupal module list. You should be able to install it through the typical manual process that works for any other Drupal module.
- jquery_update
- services
You need to add a "video_annotations" service under Administration >> Structure >> Services.
For each of the choices in the drop-down menu associated with the service, we outline the needed or expected settings.
The only checked resource should be video_annotation. Under this, all of the CRUD operations should be selected.
The response formatters should have "json" selected.
The request parsing should have "application/json" selected.
The machine-readable name of the endpoint should be "video_annotations".
The server should be "REST".
The path to endpoint should be "video_annotation".
The authentication mechanism should be "Session authentication".
This hook allows the addition of controls for creating annotations or controlling the video player. The hook should return an array of arrays using the following pattern:
$controls["foo"] = array(
"weight" => integer,
"type" => "constraint" || "control",
"mode" => "ShapeOrControlName",
"class" => "css-class-for-icon",
"permission" => 'create' || 'delete' || 'update'
);weight : An integer used for relative ordering of controls in the user interface. Controls are divided into 'control' and 'constraint' sections based on their type.
type : This should be set to 'constraint' if the control represents a new shape that can be drawn on the playsurface to represent a constraint within the video frame. A 'constraint' control will create a new annotation when it is applied to the playsurface. This should be set to 'control' if it does not lead to a new annotation (e.g., a control to start or stop the video playback).
mode : This is the name of the JavaScript application mode that is triggered when the control is selected. For constraints, this should be the shape name associated with any lenses or other shape-specific processing.
class : This is the name of the CSS class that should be applied to the element when building the control UI.
permission : If this is a constraint control, then the permission should be set to the permission required of the user to use this control. Typically, this will be 'create' for adding new annotations.
This hook allows you to add additional context to the JSON-LD context used to flatten the JSON before extracting annotations. The additions should follow the form of the JSON-LD context except use PHP array()s. This hook is intended for modules extending the types of constraints or bodies allowed in a video annotation.
This hook allows you to support new body types by returning an array with appropriate keys based on the information in $data for the given $body_id.
This hook allows you to support new target properties that are not constraints by returning an array with appropriate keys based on the information in $data for the given $target_id.
This hook allows you to support new ways of specifying the timespan in the video which the annotation targets.
This hook allows you to support new shapes for targeting particular areas within the video frame.
This hook allows you to provide JSON-LD properties for the particular type of body appropriate for the given $data.
This hook allows you to provide JSON-LD properties that should be attached to the target but aren't part of a constraint.
This hook allows you to provide the JSON-LD properties for targeting a range of time within the video. The resulting JSON-LD will be a node describing an Open Annotation constraint that will be an item in a compound constraint in the final JSON-LD structure.
This hook allows you to provide the JSON-LD properties for a particular shape targeting an area within the frame. The resulting JSON-LD will be a node describing an Open Annotation constraint that will be an item in a compound constraint in the final JSON-LD structure.
The JS hooks need to be able to add shape types:
OAC.Client.StreamingVideo.Drupal.add_shape_handler("ShapeName", {
export: function(item) { ... },
rootSVGElement: [''],
import: function(svg) { ... },
lens: function(rendering, view, item) { ... }
});The "ShapeName" is the name of the mode that can be used to define a UI control element in PHP.
The rootSVGElement is a list of strings that can match SVG elements indicating that this is the shape of the constraint on the playsurface.
extractFromSVG returns a JS object containing the x, y, height, width, and other information needed to draw and manage the constraint shape on the playsurface.
OAC.Client.StreamingVideo.Drupal.add_body_handler('TextType', {
export: function() { ... },
import: function() { ... },
lens: function(rendering, view, item) { ... }
});The "TextType" is the type of annotation body that should be rendered with the given lens/template.