Powered by Ravnur

Annotations

Annotations are interactive overlays that appear on the video at specific times. They can be used to highlight important information, provide additional context, or create clickable call-to-actions.

Interactive Overlays
Annotations appear as text boxes overlaid on the video during specified time ranges. They can be positioned anywhere on the video and styled with custom colors, fonts, and sizes.

Basic Annotations

Add annotations to your video by including them in the source configuration. Annotations appear during playback at their configured times.

Setup Code

const mediaSource = {
  id: 'annotations-demo',
  src: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
  type: 'application/x-mpegURL',
  title: 'Video with Annotations',
  annotations: [
    {
      src: '/annotations.json',     // URL to JSON annotation file
      label: 'Example',              // Display name
      srclang: 'en',                 // Language code
      type: 'json',                  // Specify JSON format
      default: true                  // Set as default annotation track
    }
  ]
};

player.setup(mediaSource);

Multiple Annotation Tracks

Support multiple languages by providing annotation tracks in different languages. Users can switch between language tracks using the annotations menu. Only the track marked with default: true will be active initially.

Setup Code

const mediaSource = {
  id: 'multiple-annotations-demo',
  src: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
  type: 'application/x-mpegURL',
  title: 'Video with Multiple Annotation Tracks',
  annotations: [
    {
      src: '/annotations.json',
      label: 'English',              // English annotations
      srclang: 'en',
      type: 'json',
      default: true
    },
    {
      src: '/annotations-es.json',
      label: 'Español',              // Spanish annotations
      srclang: 'es',
      type: 'json'
    }
  ]
};

player.setup(mediaSource);

Annotation Features

Time-Based Display

Annotations appear at specific start times and disappear at end times, allowing you to show information only when relevant.

Custom Positioning

Position annotations anywhere on the video using top and left percentages (0-100). This allows precise placement relative to video content.

Individual Styling

Each annotation can have its own unique styling defined in the JSON file. Customize font size, text color, background color, and dimensions individually for each annotation to match your brand or design.

Clickable Links

Include URLs in annotation text to create clickable links that open in new tabs.

Annotation File Format

Annotations use JSON format with time ranges, positioning, and styling properties.

JSON Format

[
  {
    "type": 3,
    "text": "This is an example annotation",
    "title": "",
    "starts": {
      "hh": 0,
      "mm": 0,
      "ss": 5,
      "ms": 0
    },
    "ends": {
      "hh": 0,
      "mm": 0,
      "ss": 15,
      "ms": 0
    },
    "top": 10,
    "left": 50,
    "width": 200,
    "height": 40,
    "fontsize": "12px",
    "fontcolor": "FFFFFF",
    "background": "2196F3"
  },
  {
    "type": 3,
    "text": "Check out http://example.com for more info",
    "title": "",
    "starts": {
      "hh": 0,
      "mm": 1,
      "ss": 0,
      "ms": 0
    },
    "ends": {
      "hh": 0,
      "mm": 1,
      "ss": 15,
      "ms": 0
    },
    "top": 70,
    "left": 20,
    "width": 250,
    "height": 40,
    "fontsize": "12px",
    "fontcolor": "FFFFFF",
    "background": "4CAF50"
  }
]

Field Descriptions

Time Properties

  • starts - Start time object with hh, mm, ss, ms
  • ends - End time object with the same structure

Position & Size

  • top - Vertical position as percentage (0-100)
  • left - Horizontal position as percentage (0-100)
  • width - Width in pixels
  • height - Height in pixels

Styling

  • fontsize - Font size (e.g., "12px")
  • fontcolor - Text color as hex without # (e.g., "FFFFFF")
  • background - Background color as hex without # (e.g., "2196F3")

Content

  • type - Annotation type (3 for text annotations)
  • text - Annotation text content (can include URLs)
  • title - Optional title

Additional Annotation Options

Control annotation functionality with player options: 

const options = {
  showAnnotations: true    // Show annotations button (default: true)
};

player.setup(mediaSource, options);
  • showAnnotations - Show/hide the annotations button in the player controls (default: true)
←→