{"id":13907357,"url":"https://github.com/videojs/videojs-overlay","last_synced_at":"2025-12-12T04:26:08.504Z","repository":{"id":16491545,"uuid":"19244179","full_name":"videojs/videojs-overlay","owner":"videojs","description":"A video.js plugin to display simple overlays during playback.","archived":false,"fork":false,"pushed_at":"2023-06-15T16:02:27.000Z","size":803,"stargazers_count":240,"open_issues_count":19,"forks_count":91,"subscribers_count":58,"default_branch":"main","last_synced_at":"2024-05-19T11:02:59.914Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/videojs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2014-04-28T15:46:05.000Z","updated_at":"2024-05-14T17:43:29.000Z","dependencies_parsed_at":"2023-10-20T18:45:43.237Z","dependency_job_id":null,"html_url":"https://github.com/videojs/videojs-overlay","commit_stats":{"total_commits":85,"total_committers":23,"mean_commits":"3.6956521739130435","dds":0.6941176470588235,"last_synced_commit":"84f7ca9b4cd461c92bbb3a44a63716ad9f7bae2e"},"previous_names":["brightcove/videojs-overlay"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videojs%2Fvideojs-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videojs%2Fvideojs-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videojs%2Fvideojs-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/videojs%2Fvideojs-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/videojs","download_url":"https://codeload.github.com/videojs/videojs-overlay/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226353636,"owners_count":17611739,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T23:01:54.292Z","updated_at":"2025-12-12T04:26:08.472Z","avatar_url":"https://github.com/videojs.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# videojs-overlay\n\n[![Build Status](https://travis-ci.org/brightcove/videojs-overlay.svg?branch=master)](https://travis-ci.org/brightcove/videojs-overlay)\n[![Greenkeeper badge](https://badges.greenkeeper.io/brightcove/videojs-overlay.svg)](https://greenkeeper.io/)\n[![Slack Status](http://slack.videojs.com/badge.svg)](http://slack.videojs.com)\n\n[![NPM](https://nodei.co/npm/videojs-overlay.png?downloads=true\u0026downloadRank=true)](https://nodei.co/npm/videojs-overlay/)\n\nA plugin to display simple overlays - similar to YouTube's \"Annotations\" feature in appearance - during video playback.\n\n_Note_: This meaning of an \"overlay\" is distinct from that of a modal dialog, which can overlay the entire player. This is built into video.js as [the `ModalDialog` component](http://docs.videojs.com/docs/api/modal-dialog.html).\n\nMaintenance Status: Stable\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Getting Started](#getting-started)\n- [Documentation](#documentation)\n  - [API](#api)\n    - [`player.overlay()`](#playeroverlay)\n    - [`overlay.get()`](#overlayget)\n    - [`overlay.add(object|array)`](#overlayaddobjectarray)\n    - [`overlay.remove(object)`](#overlayremoveobject)\n  - [Plugin Options](#plugin-options)\n    - [`align`](#align)\n    - [`showBackground`](#showbackground)\n    - [`attachToControlBar`](#attachtocontrolbar)\n    - [`class`](#class)\n    - [`content`](#content)\n    - [`overlays`](#overlays)\n  - [Examples](#examples)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\n## Getting Started\n\nOnce you've added the plugin script to your page, you can use it with any video:\n\n```html\n\u003cscript src=\"path/to/videojs-overlay.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  videojs(document.querySelector('video')).overlay();\n\u003c/script\u003e\n```\n\nThere's also a [working example](https://github.com/brightcove/videojs-overlay/blob/master/index.html) of the plugin you can check out if you're having trouble.\n\n## Documentation\n\n### API\n#### `player.overlay()`\nThis is the main interface and the way to initialize this plugin. It takes [an options object as input](#plugin-options).\n\n#### `overlay.get()`\n\nReturns an array of all the overlays set up for the current video.\n\n#### `overlay.add(Object|Array)`\n\nAdds one or more overlays to the current list of overlays without replacing the current list of overlays.\nReturns a reference to the added overlays.\n\n```js\nconst overlay = player.overlay({\n  content: 'Default overlay content',\n  debug: true,\n  overlays: [{\n    content: 'The video is playing!',\n    start: 'play',\n    end: 'pause'\n  }]\n});\nconst addedOverlays = overlay.add({content: \"this is a new one\", start: \"play\", end: \"pause\"});\n```\n\n\n#### `overlay.remove(Object)`\n\nRemoves an individual overlay from the list of overlays. Calling this method with an invalid overlay object removes nothing from the list.\n\n```js\nconst overlay = player.overlay({\n  content: 'Default overlay content',\n  debug: true,\n  overlays: [{\n    content: 'The video is playing!',\n    start: 'play',\n    end: 'pause'\n  }]\n});\nconst overlayToRemove = overlay.get()[0];\noverlay.remove(overlayToRemove);\n```\n\n#### `overlay.reset(Object)`\n\nOnce the plugin is initialized, the plugin options can be reset by passing this function an object of options. This will remove the previous configuration and overlays, and update the plugin with the new values. It takes [an options object as input](#plugin-options).\n\n```js\n// First initialization\nconst overlay = player.overlay({\n  debug: true,\n  overlays: [{\n    content: 'The video is playing!',\n    start: 'play',\n    end: 'pause'\n  }]\n});\n\n// Update configuration with different overlays\nconst overlayToRemove = overlay.reset({\n  debug: false,\n  overlays: [{\n    content: 'Some new overlay content!',\n    start: 'play',\n    end: 'pause'\n  }]\n});\n```\n\n### Plugin Options\n\nYou may pass in an options object to the plugin upon initialization. This\nobject may contain any of the following properties:\n\n#### `align`\n\n__Type:__ `String`\n__Default:__ `\"top-left\"`\n\n_This setting can be overridden by being set on individual overlay objects._\n\nWhere to display overlays, by default. Assuming the included stylesheet is used, the following values are supported: `\"top-left\"`, `\"top\"`, `\"top-right\"`, `\"right\"`, `\"bottom-right\"`, `\"bottom\"`, `\"bottom-left\"`, `\"left\"`.\n\n#### `showBackground`\n\n__Type:__ `Boolean`\n__Default:__ `true`\n\n_This setting can be overridden by being set on individual overlay objects._\n\nWhether or not to include background styling \u0026 padding around the overlay.\n\n#### `attachToControlBar`\n\n__Type:__ `Boolean`, `String`\n__Default:__ `false`\n\n_This setting can be overridden by being set on individual overlay objects._\n\nIf set to `true` or a `string` value, bottom aligned overlays will adjust positioning when the control bar minimizes. This has no effect on overlays that are not aligned to bottom, bottom-left, or bottom-right. For use with the default control bar, it may not work for custom control bars.\n\nThe value of `string` must be the name of a ControlBar component.\n\nBottom aligned overlays will be inserted before the specified component. Otherwise, bottom aligned overlays are inserted before the first child component of the ControlBar. All other overlays are inserted before the ControlBar component.\n\n#### `class`\n\n__Type:__ `String`\n__Default:__ `\"\"`\n\n_This setting can be overridden by being set on individual overlay objects._\n\nA custom HTML class to add to each overlay element.\n\n#### `content`\n\n__Type:__ `String`, `Element`, `DocumentFragment`\n__Default:__ `\"This overlay will show up while the video is playing\"`\n\n_This setting can be overridden by being set on individual overlay objects._\n\nThe default HTML that the overlay includes.\n\n#### `overlays`\n\n__Type:__ `Array`\n__Default:__ an array with a single example overlay\n\nAn array of overlay objects. An overlay object should consist of:\n\n- `start` (`String` or `Number`): When to show the overlay. If its value is a string, it is understood as the name of an event. If it is a number, the overlay will be shown when that moment in the playback timeline is passed.\n- `end` (`String` or `Number`): When to hide the overlay. The values of this property have the same semantics as `start`.\n\nAnd it can optionally include `align`, `class`, and/or `content` to override top-level settings.\n\nAll properties are currently optional. That is, you may leave `start` or `end` off and the plugin will not complain, but you should always pass a `start` and an `end`. This will be required in a future release.\n\n### Examples\n\nYou can setup overlays to be displayed when particular events are emitted by the player, including your own custom events:\n\n```js\nplayer.overlay({\n  overlays: [{\n\n    // This overlay will appear when a video is playing and disappear when\n    // the player is paused.\n    start: 'playing',\n    end: 'pause'\n  }, {\n\n    // This overlay will appear when the \"custom1\" event is triggered and\n    // disappear when the \"custom2\" event is triggered.\n    start: 'custom1',\n    end: 'custom2'\n  }]\n});\n```\n\nMultiple overlays can be displayed simultaneously. You probably want to specify an alignment for one or more of them so they don't overlap:\n\n```js\nplayer.overlay({\n  overlays: [{\n\n    // This overlay appears at 3 seconds and disappears at 15 seconds.\n    start: 3,\n    end: 15\n  }, {\n\n    // This overlay appears at 7 seconds and disappears at 22 seconds.\n    start: 7,\n    end: 22,\n    align: 'bottom'\n  }]\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvideojs%2Fvideojs-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvideojs%2Fvideojs-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvideojs%2Fvideojs-overlay/lists"}