@saran-ign/video-annotation-tool

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.

Developers

• Sarankumar Sengottuvel