A plugin for video.js to add support for timeline moment/range comments and annotations. 

A plugin for video.js to add support for timeline moment/range comments and annotations

jackpope

contently_devops

sanjayginde

sethwebster

@contently/videojs-annotation-comments

  "name": "@contently/videojs-annotation-comments",

  "description": "A plugin for video.js to add support for timeline moment/range comments and annotations",

  "repository": "git@github.com:contently/videojs-annotation-comments.git",

  "main": "build/videojs-annotation-comments.cjs.js",

    "integration": "echo open in chrome: http://localhost:3004/mocha/features/index.html",

  "author": "Evan Carothers (@ecaroth) & Jack Pope (@jackpope)",

  "copyright": "Copyright Contently, Inc. <https://www.contently.com/>",

    "@semantic-release/changelog": "^3.0.5",

    "babel-plugin-transform-object-rest-spread": "^6.26.0",

    "babel-plugin-transform-es2015-modules-simple-commonjs": "^0.3.0",

    "babel-preset-es2015-script": "^1.1.0",

    "eslint-config-airbnb-base": "^14.0.0",

      "@semantic-release/commit-analyzer",

      "@semantic-release/release-notes-generator",

          "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"

[![CircleCI](https://circleci.com/gh/contently/videojs-annotation-comments/tree/master.svg?style=svg)](https://circleci.com/gh/contently/videojs-annotation-comments/tree/master)

# AnnotationComments : Collaborate in your VideoJS player

![AnnotationComments Screenshot1](test/screenshot.png)

>Please note that the event based API has changed. In version 1, you can subscribe to plugin events with `pluginInstance.on()`. In version 2, the same functionality is available with `pluginInstance.registerListener()`. The following docs are for the latest version.

Collaboration between videographers and clients can be tedious, with emails and phone calls that waste time trying to reference specific frames and areas of the screen. This plugin enables more efficient collaboration from the browser.

This plugin was conceived and developed as a Hack Week project at [Contently](http://www.contently.com) by [Evan Carothers](http://www.github.com/ecaroth) and [Jack Pope](http://www.github.com/jackpope). Continuing our focus and commitment to multimedia support at Contently, the entire team productized and bulletproofed the plugin as a flexible solution to be used in our product and other open-source use cases.

- **Efficient for videographers and clients alike** - Provides useful collaboration features including annotations, comments/replies, ranged time markers, and more, with intuitive controls.

- **SIMPLE & LIGHTWEIGHT** - Everything is contained within the plugin and player element. There is no need to build additional UI components. Just install VideoJS, register the plugin, setup whatever backend storage you wish, and start collaborating.

- **EXTENSIBLE** - The plugin can be integrated with existing commenting systems (as we did within Contently), and makes very few assumptions about how to store annotations. Custom events are available for communicating with external APIs, providing support for on-page interactions and data persistence. Simple CSS overrides can also allow for branding customizations with minimal effort, or completely custom UI/UX.

[VideoJS](http://videojs.com/) is a popular open-source HTML5 video player library used by 400k+ sites. As of v6, there is an extendable plugin architecture which was used to create this plugin. This plugin is built and tested against [VideoJS v7](https://www.npmjs.com/package/video.js/)

yarn add @contently/videojs-annotation-comments

npm install @contently/videojs-annotation-comments

// ...videojs & videojs-annotation-comments have been loaded in script tags...

var plugin = player.annotationComments(pluginOptions)

import AnnotationComments from '@contently/videojs-annotation-comments'

 videojs.registerPlugin('annotationComments', AnnotationComments(videojs))

When initializing the plugin, you can pass in an options array to override default options. Any excluded options are set to their default values, listed below:

    // Collection of annotation data to initialize

    // Flexible meta data object (currently used for user data, but addl data can be provided to wrap each comment with metadata - provide the id of the current user and fullname of the current user at minimum, which are required for the UI)

    meta: { user_id: null, user_name: null },

    // Use arrow keys to move through annotations when Annotation mode is active

    // Show or hide the control panel and annotation toggle button (NOTE - if controls are hidden you must provide custom UI and events to drive the annotations - more on that in "Programmatic Control" below)

    // Show or hide the comment list when an annotation is active. If false, the text 'Click and drag to select', will follow the cursor during annotation mode

    // If false, annotations mode will be disabled in fullscreen

    // Show or hide the tooltips with comment preview, and annotation shape, on marker hover or timeline activate

    // If false, step two of adding annotations (writing and saving the comment) will be disabled

    // If true, toggle the player to annotation mode immediately after init. (NOTE - "annotationModeEnabled" event is not fired for this initial state)

To initialize the plugin with the `annotationsObjects` collection, use the following structure:

    // do stuff with the plugin, such as fire events or setup listeners

 These events are external actions that can be called from your scripts to trigger events within the plugin:

// openAnnotation : Opens an annotation within the player given an ID

plugin.fire('openAnnotation', { id: myAnnotationId });

 // closeActiveAnnotation : Closes any active annotation

 // newAnnotation : Adds a new annotation within the player and opens it given comment data

    shape: { // NOTE - x/y vals are % based (Floats) in video, not pixel values

 // destroyAnnotation : Removes an annotation and it's marker within the player given comment data

plugin.fire('destroyAnnotation', { id: 1 });

 // newComment : Adds a new comment to an Annotation given an Annotation ID and a body

plugin.fire('newComment', { annotationId: 1, body: "My comment string" });

 // destroyComment : Removes a comment from an Annotation given a Comment ID

plugin.fire('destroyComment', { id: 1 });

 // addingAnnotation : Plugin enters the adding annotation state (adding an annotation at the current player timestamp)

 // cancelAddingAnnotation : Plugin exits the adding annotation state

 // toggleAnnotationMode : toggle annotation mode to alternative on/off value

These are events that are triggered from within the running plugin and can be listened for by binding to `plugin.registerListener` within your scripts:

// annotationOpened : Fired whenever an annotation is opened

plugin.registerListener('annotationOpened', (event) => {

    //      annotation: (object) annotation data in format {id:.., comments:..., range:..., shape:...},

    //      triggered_by_timeline: (boolean) TRUE = the event was triggered via a timeline action (like scrubbing or playing), FALSE = the annotation was opened via marker click, UI button interactions, or API/event input

 // annotationClosed : Fired whenever an annotation is closed

plugin.registerListener('annotationClosed', (event) => {

    // event.detail = annotation (object) in format {id:.., comments:..., range:..., shape:...}

 // addingAnnotationDataChanged : Fired from adding annotation state if:

//  2. the start of the marker is moved via control buttons

plugin.registerListener('addingAnnotationDataChanged', (event) => {

    var newRange = event.detail.range; // returns range data if range was changed

    var newShape = event.detail.shape; // returns shape data if shape was changed

 // annotationDeleted : Fired when an annotation has been deleted via the UI

plugin.registerListener('annotationDeleted', (event) => {

 // enteredAnnotationMode : Fired when the plugin enters adding annotation mode

plugin.registerListener('enteredAddingAnnotation', (event) => {

    var startTime = event.detail.range.start;

    // do something when adding annotation state begins

 // onStateChanged: Fired when plugin state has changed (annotation added, removed, etc)

// This is a way to watch global plugin state, as an alternative to watching various annotation events

plugin.registerListener('onStateChanged', (event) => {

    // event.detail = annotation state data

 // playerBoundsChanged : Fired when the player boundaries change due to window resize or fullscreen mode

plugin.registerListener('playerBoundsChanged', (event) => {

    // do something with the new boundaries

 // Entering annotation mode (annotation icon was clicked when previously 'off')

plugin.registerListener('annotationModeEnabled', (event) => {

 // Exiting annotation mode (annotation icon was clicked when previously 'on')

plugin.registerListener('annotationModeDisabled', (event) => {

We're using [yarn](https://yarnpkg.com/en/) for package management and [gulp](https://github.com/gulpjs/gulp) as our build system.

- Visit `http://localhost:3004/test.html` to see the magic happen.

 We're using the [Handlebars](http://handlebarsjs.com/) templating library to render various components within the plugin. For performance, the templates are pre-compiled into a JS file within the development environment. That way we only need to require the Handlebars runtime, saving nearly 100kb from the minified build! ⚡️

The `gulp templates` task is used to precompile every template to `/src/js/compiled/templates.js`. This file should _not_ be modified directly, but rather the templates themselves in `/src/templates` should be modified if changes are needed. The templates task will run automatically within `gulp watch`.

The plugin uses SASS and all styles are defined in [annotaitons.scss](src/css/annotations.scss). There is extenssive commenting on classes and styles in the file. The plugin uses a deep level of specificity to prevent styles from polluting elements on the page, and all classes are prefixed with `vac-` to prevent classname collisions in the global namespace.

You can extend/modify colors and elements quite easily by writing an overrides stylesheet to address the specific elements that you wish to modify. You can also change the variable colors in the stylesheet and compile yourself for more customization.

_NOTE_ - our gulp build tasks use an auto-prefixer to make the styles work cross-browser, so be sure to run that yourself if you compile the SASS files with changes.

Feature tests are currently browser-based and run by visiting `http://localhost:3004/mocha/features/index.html`. Feature tests can be added as files in the `/test/mocha/features/` directory and then included within the `index.html` file as a external scripts.

Unit tests are run through the `gulp test` task. If the `tdd` task is included in `gulp watch`, the tests will run with every change to the test files. Each module should have a corresponding unit test file within the `/test/mocha/modules` directory.

`gulp watch`: Fires up webserver @ `http://localhost:3004/test.html`, watches for any file changes in `/src`, including js, css (scss), and templates (.hbs), repackages, and transpiles to an unminified file in `/build` on change.

`gulp transpile`: Transpiles modules/files to build file in `/build` with JS maps

`gulp build`: Runs transpilation, browserify, sass, then minifies to distribution filename in `/build` with attribution

		{
		"name": "@contently/videojs-annotation-comments",
		"version": "2.0.0",
		"version": "2.0.1",
		"description": "A plugin for video.js to add support for timeline moment/range comments and annotations",
		@@ -13,4 +13,6 @@ "repository": "git@github.com:contently/videojs-annotation-comments.git",
		"test": "gulp test",
		"integration": "echo open in chrome: http://localhost:3004/mocha/features/index.html",
		"watch": "gulp watch",
		"build": "gulp build"
		"build": "gulp build",
		"lint": "eslint ./src"
		},
		@@ -24,2 +26,4 @@ "author": "Evan Carothers (@ecaroth) & Jack Pope (@jackpope)",
		"babel-core": "^6.26.3",
		"babel-eslint": "^10.0.3",
		"babel-plugin-transform-object-rest-spread": "^6.26.0",
		"babel-plugin-transform-es2015-modules-simple-commonjs": "^0.3.0",
		@@ -32,2 +36,7 @@ "babel-preset-es2015": "^6.24.1",
		"es6-object-assign": "^1.1.0",
		"eslint": "^6.8.0",
		"eslint-config-airbnb-base": "^14.0.0",
		"eslint-config-prettier": "^6.9.0",
		"eslint-plugin-import": "^2.19.1",
		"eslint-plugin-prettier": "^3.1.2",
		"gulp": "^3.9.1",
		@@ -43,3 +52,2 @@ "gulp-autoprefixer": "^4.1.0",
		"gulp-insert": "^0.5.0",
		"gulp-jshint": "^2.1.0",
		"gulp-mocha": "^4.3.1",
		@@ -57,6 +65,5 @@ "gulp-rename": "^1.4.0",
		"ie-array-find-polyfill": "^1.1.0",
		"jshint": "^2.9.6",
		"jshint-stylish": "~2.0.1",
		"mocha": "^6.2.0",
		"moment": "^2.24.0",
		"prettier": "^1.19.1",
		"pump": "^1.0.3",
		@@ -63,0 +70,0 @@ "semantic-release": "^15.13.21",

		@@ -125,3 +125,3 @@ [![CircleCI](https://circleci.com/gh/contently/videojs-annotation-comments/tree/master.svg?style=svg)](https://circleci.com/gh/contently/videojs-annotation-comments/tree/master)
		```javascript
		plugin.registerListenerReady(() => {
		plugin.onReady(() => {
		// do stuff with the plugin, such as fire events or setup listeners
		@@ -163,3 +163,3 @@ });
		// toggleAnnotationMode : toggle annotation mode to alternative on/off value
		plugin.fire('toggleAnnotations');
		plugin.fire('toggleAnnotationMode');
		```
		@@ -166,0 +166,0 @@

Improved metrics

Worsened metrics