@saran-ign/video-annotation-tool NPM

Video Annotation Tool

📦 Description @saran-ign/video-annotation-tool is a powerful Typescript React-based video player component that comes with built-in annotation capabilities. It enables developers to easily integrate interactive video tagging, markup, and labeling features into any React application.

Designed for media annotation workflows, this tool supports seamless interaction with video content—ideal for applications in video analysis, machine learning dataset preparation, education, surveillance, and more.

Features

✨ Key Features 🎞️ Custom Video Player – Built on top of robust video libraries with support for modern formats (HLS, MP4, etc.)

🏷️ Interactive Annotation – Add, update, and remove annotations with a visual overlay.

🔁 Playback Sync – Ensure annotations are time-aligned with video playback.

🎯 Flexible Integration – Easily embeddable in any React project.

🛠️ Highly Customizable – Extend or theme annotations, labels, and controls as needed.

⚙️ Performance Optimized – Lightweight and efficient even with large annotation sets.

Keyboard Shortcuts for Improved Productivity
Ctrl + Z: Undo the last action.
Ctrl + Y: Redo the undone action.
Delete Button: Remove selected shapes.

Installation

Install the package using npm or yarn:

npm install @saran-ign/video-annotation-tool

Usage

App.ts Example

import { useRef, useState } from "react";
import { TwoDVideoAnnotation } from "@saran-ign/video-annotation-tool";
import { FaUndo, FaRedo, FaTrash } from "react-icons/fa";

function App() {
  const annotationRef = useRef(null);
  const [allAnnotations, setAllAnnotations] = useState([]);

  return (
    <div className="app">
      {/* Toolbar */}
      <div className="tools">
        <button onClick={() => annotationRef.current?.undo()}>
          <FaUndo /> Undo
        </button>
        <button onClick={() => annotationRef.current?.redo()}>
          <FaRedo /> Redo
        </button>
        <button onClick={() => annotationRef.current?.deleteShape()}>
          <FaTrash /> Delete
        </button>
      </div>

      {/* Video Annotation Tool */}
      <TwoDVideoAnnotation
        rootRef={annotationRef}
        shapes={allAnnotations}
        setShapes={setAllAnnotations}
        selectedShapeTool={"rectangle"} 
        videoTimeAnnotation={true}
        videoUrl="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
      />
    </div>
  );
}

export default App;

Shapes objects and properties examples, expected as initial Data array of shapes of objects if passed

// Example of initial data array with shape objects
const initialShapes = [
{
  id: "rectangle1", // Unique identifier for the shape
  color: "blue", // Color of the annotation
  label: "My Rectangle", // Optional label for the shape
  data: {}, // Custom data for user-defined purposes
  properties: {
    type: "rectangle", // Shape type
    x: 13, // X-coordinate of the rectangle
    y: 5, // Y-coordinate of the rectangle
    width: 4, // Width of the rectangle
    height: 4, // Height of the rectangle
    startTime: 0, // Start time of the annotation (seconds)
    endTime: 0.5, // End time of the annotation (seconds)
    scaleX: 1, // Horizontal scale factor
    scaleY: 1, // Vertical scale factor
    screenHeight: 600, // Height of the annotation area
    screenWidth: 400, // Width of the annotation area
    strokeWidth: 2, // Stroke width for the rectangle
    opacity: 0.8, // Opacity of the rectangle
  },
},
{
  id: "circle1", // Unique identifier for the circle
  color: "red",
  label: "My Circle", // Optional label for the circle
  data: {}, 
  properties: {
    type: "circle", 
    x: 10,
    y: 15, 
    radius: 4, // Radius of the circle
    startTime: 1, 
    endTime: 1.5, 
    scaleX: 1, 
    scaleY: 1,
    screenHeight: 600, 
    screenWidth: 400, 
    strokeWidth: 2, 
    opacity: 0.8,
  },
},
{
  id: "line1", 
  color: "green", 
  label: "My Line", 
  data: {}, 
  properties: {
    type: "line",
    x: 20,
    y: 30, 
    points: [0, 0, 100, 0, 100, 100], // Array of points defining the line
    startTime: 2, 
    endTime: 2.5, 
    scaleX: 1, 
    scaleY: 1, 
    screenHeight: 600, 
    screenWidth: 400, 
    strokeWidth: 2, 
    opacity: 0.8, 
  },
},
];

API

TwoDVideoAnnotation Props

Prop	Type	Default	Description
`rootRef`	`ref`	-	Ref to access methods (e.g., undo, redo, deleteShape).
`shapes`	`array`	`[]`	Initial array of annotations.
`setShapes`	`function`	-	State setter to update annotations.
`videoUrl`	`string`	-	URL of the video to annotate.
`selectedShapeTool`	`string`	-	The currently selected shape tool ('rectangle' , 'circle' , 'line').
`hideAnnotations`	`boolean`	`false`	Whether to hide all annotations.
`annotationColor`	`string`	`"red"`	Color for new annotations.
`videoControls`	`object`	`{}`	Video playback controls ({`autoPlay:true`, `loop:true`}, etc.).
`lockEdit`	`boolean`	`false`	Disable editing annotations.
`selectedAnnotationData`	`function`	-	Callback triggered when annotation is selected.
`videoTimeAnnotation`	`boolean`	`true`	Enable editing video annotations particular time.
`showVideoDuration`	`boolean`	`true`	Enable videoDuration.