@brandbrigade/ott-bb-player 1.0.69 → 1.1.1

package/README.md

@@ -1,358 +1,214 @@
 # OTT-BB-Player
 
-Welcome to OTT-BB-Player! This README provides information about the project, including installation instructions and a changelog.
-
-## Table of Contents
-
-- [Overview](#Overview)
-- [Installation](#installation)
-- [HowTo](#HowTo)
-- [Example](#example)
-- [Changelog](#changelog)
-
-## Overview
-
-The SDK allows to augment targeted ads on top of DRM1 stream, providing that the same content is/was augmetned by BrandBrigade and the augmentation metadata is stored in the BrandBrigade cloud Smart-Feed, and providing that the stream contains embeded timecodes that match in a frame-accurate manner the timecode embedded in the smart feed.
+BrandBrigade OTT Player SDK for targeted ad augmentation on live streams.
 
 ## Installation
 
-To install My Project, follow these steps:
-
-1. Login into npmjs repo if you are not logged in
-
-```bash
-npm login
-```
-
-2. Use npm to install the package
-
 ```bash
-npm install @brandbrigade/ott-bb-player --prefix .
+npm install @brandbrigade/ott-bb-player
 ```
 
-## HowTo
+## Usage
 
 ### Initialization
 
-To initialize the SDK, one should provide:
-
-1. Video Tag: You should submit the video element (the one that is submitted to the MK player by wmcMgr.setContainer(video))
-
-2. Frame rate
-   (In the future this parameter will be omitted and fetched internally with the MediaKind API)
-
-3. A game id: This is an identifier for the game which is shared between the NBA app and the BB DTC client to define the appropriate smart feed to be accessed
-
-4. A channel name: The programmatic emulation channel to demonstrate the targeted ad
-
-```
-bbPlayer = new BB.OTTPlayer(
-  video, //Video Tag
-  30000/1001, // frame rate
-  { gameId:<game id>,//game id
-    augmentation:{“channelName”:”nba”}});//channel name
+```javascript
+const bbPlayer = new BB.OTTPlayer(
+  videoElement,
+  frameRate, // e.g., 30000/1001 for 29.97 fps
+  {
+    gameId: 'game_identifier',
+    augmentation: { channelName: 'channel_name' }
+  }
+);
 ```
 
-## Example
+## API Reference
 
-**sample.html** is an example page showing usage of OTT-BB-Player
-A test page hosted on the BB server can be accessed [here](http://bb-ott-player.s3-website-us-east-1.amazonaws.com/demo/node_modules/@brandbrigade/ott-bb-player/sample.html)
+### Event Integration
 
-The inital configuration on the config json on the top of the sample.html page, requires:
+#### `onNewMetadata(event)`
+Forward MediaKind metadata events containing timecode information.
 
-1. A Stream URL. An example stream can be accessed at [this link](https://nbablpng.akamaized.net/live/hls-itc/bbtest49/v0-121.m3u8?stSecret=rj12sw543terw32422334swees) (MK Stream with MetadataEvents) or [here](https://injecto-streams.s3-accelerate.amazonaws.com/hls_fileTest_tmp/index_test.m3u8) (BB Stream without MetadataEvents)
-2. The game id. For a test case use “arena_nba_BB_test_Lakers_long”. The game id is a convention to be agreed between the NBA App and the BrandBrigade SDK to identify the playing game.
-3. A Channel for the programmatic ads simulation. For a test case use “nba”
-   Example:
-
-```
-var config = {
-  "url":"https://injecto-streams.s3-accelerate.amazonaws.com/hls_fileTest_tmp/index_test.m3u8",
-  "gameId":"“arena_nba_BB_test_Lakers_long”,
-  "channel":"nba"
-};
+```javascript
+wmcMgr.addEventListener(wmcEvents.AMC_EVENT_PLAYER_METADATA, (event) => {
+  bbPlayer.onNewMetadata(event);
+});
 ```
 
-To get Timecode information AMC_EVENT_PLAYER_METADATA and AMC_EVENT_PLAYER_SEGMENT_PLAYBACK events should be forwarded to OTTPlayer
+#### `onNewSegment(event)`
+Forward MediaKind segment playback events for synchronization.
 
+```javascript
+wmcMgr.addEventListener(wmcEvents.AMC_EVENT_PLAYER_SEGMENT_PLAYBACK, (event) => {
+  bbPlayer.onNewSegment(event);
+});
 ```
-	function onNewMetadata(eventObj) {
-		bbPlayer.onNewMetadata(eventObj)
-	};
-	function onNewSegment(eventObj) {
-		bbPlayer.onNewSegment(eventObj);
-	};
-	wmcMgr.addEventListener(wmcEvents.AMC_EVENT_PLAYER_METADATA, onNewMetadata);
-	wmcMgr.addEventListener(wmcEvents.AMC_EVENT_PLAYER_SEGMENT_PLAYBACK, onNewSegment);
-
-```
-
-### Control
 
-To toggle the SDK on off, use the SDK Toggle method with a boolean:
+#### `onAdEvent(eventType)`
+Notify player of ad events to pause/resume augmentation.
 
+```javascript
+bbPlayer.onAdEvent('start'); // Pause augmentation during ad
+bbPlayer.onAdEvent('end');   // Resume augmentation after ad
 ```
-bbPlayer.Toggle({true|false});
-```
-
-## Changelog
-
-### Version 1.0.0
-
-Initial version
-
-### Version 1.0.1
-
-Initial version
-
-### Version 1.0.2
-
-Initial version
-
-### Version 1.0.3
-
-Added readme.md
-
-### Version 1.0.4
-
-Added support of 59.94 streams
-
-Added interface functions to get sync timecodes from MK MetadataEvents
-
-### Version 1.0.5
-
-Added support of Safari on Mac
-
-### Version 1.0.6
-
-Enabled support of Safari on Mac
-
-### Version 1.0.7
-
-Fixed Safari issue.
-Improved Chrome rendering
-
-### Version 1.0.8
-
-Added usage of TimeCodesSync service
-
-### Version 1.0.9
-
-Bug fix
-
-### Version 1.0.10
-
-Bug fix
-
-### Version 1.0.11
-
-Bug fix
-
-### Version 1.0.12
-
-All is packed to one file
-
-### Version 1.0.13
-
-Chrome on MK REF App support
-
-### Version 1.0.14
-
-Safari on MK REF App support
 
-### Version 1.0.15
+### Control Methods
 
-MK REF App DEV stream support
+#### `toggle(enabled)`
+Enable or disable augmentation rendering.
 
-### Version 1.0.16
-
-Improvements
-
-### Version 1.0.17
-
-Improvements
-
-### Version 1.0.18
-
-Improvements
-
-### Version v1.0.19
-
-Chrome-Mac support
-
-### Version v1.0.20
-
-Improvements### Version v1.0.21
-test26
-
-### Version v1.0.22
-
-test26
-
-### Version v1.0.23
-
-test_v_1.0.23
-
-### Version v1.0.24
-
-test
-
-### Version v1.0.25
-
-test
-
-### Version v1.0.26
-
-test
-
-### Version v1.0.27
-
-test
-
-### Version v1.0.28
-
-test
-
-### Version v1.0.29
-
-test
-
-### Version v1.0.30
-
-test
-
-### Version v1.0.31
-
-test
+```javascript
+bbPlayer.toggle(true);  // Enable
+bbPlayer.toggle(false); // Disable
+```
 
-### Version v1.0.32
+#### `setMediaInfo(mediaInfo)`
+Update media stream information (fps, bitrate).
 
-QA_newAPi_funcNames
+```javascript
+bbPlayer.setMediaInfo({ fps: 29.97, bitrate: 5000000 });
+```
 
-### Version v1.0.33
+#### `setFps(fps)`
+Update frame rate independently.
 
-mac_any_screenFPS
+```javascript
+bbPlayer.setFps(29.97);
+```
 
-### Version v1.0.34
+### Asset Override Methods
 
-29_fps_support_in_chrome_windows
+#### `setAd(source, placeholder?)`
+Override ad creative at runtime. Accepts URL, Blob, or ImageBitmap.
 
-### Version v1.0.35
+```javascript
+bbPlayer.setAd('https://example.com/ad.png', 'brand_name');
+bbPlayer.setAd(adBlob);
+bbPlayer.setAd(imageBitmap);
+```
 
-added_more_debug_to_virtualott
+#### `setLED(source)`
+Override LED board creative. Accepts URL, Blob, or ImageBitmap.
 
-### Version v1.0.36
+```javascript
+bbPlayer.setLED('https://example.com/led.png');
+bbPlayer.setLED(ledBlob);
+bbPlayer.setLED(imageBitmap);
+```
 
-mac_chrome_correction_disable
+#### `setGameParams(gameParams)`
+Manually override game parameters (offsets, bucket info).
+
+```javascript
+bbPlayer.setGameParams({
+  bucketName: 'game-bucket',
+  offsets: [{ frame: 0, offset: 0, timecode: '00:00:00:00' }],
+  startZip: 'start.zip',
+  endZip: 'end.zip',
+  customerId: 'customer_id',
+  customerName: 'Customer Name'
+});
+```
 
-### Version v1.0.37
+### Event Subscription
 
-one_of_jitters_fixed_on_safari_mac
+#### `on(eventName, listener)`
+Subscribe to player events.
 
-### Version v1.0.38
+```javascript
+bbPlayer.on('augmentationStatusChanged', (event) => {
+  console.log('Status:', event.detail);
+});
+```
 
-one_of_jitters_fixed_on_safari_mac_2
+#### `off(eventName, listener)`
+Unsubscribe from player events.
 
-### Version v1.0.39
+```javascript
+bbPlayer.off('augmentationStatusChanged', listener);
+```
 
-dual_mac_chrome_safari
+### Lifecycle
 
-### Version v1.0.40
+#### `destroy()`
+Cleanup and dispose of player instance. Terminates workers, removes event listeners, and frees resources.
 
-added_fps_checks
+```javascript
+bbPlayer.destroy();
+```
 
-### Version v1.0.41
+## Platform Support
 
-chrome_mac_mkRefApp_jitter_fix
+- Chrome (Mac, Windows)
 
-### Version v1.0.47
 
-OTT Web rebuild, supports Chrome Mac
+## Changelog
 
-### Version v1.0.49
+**Version v1.0.47** - OTT Web rebuild, supports Chrome Mac
 
-Fixed augmentation size bug,
+**Version v1.0.49** - Fixed augmentation size bug,
 Updated configurations
 
-### Version v1.0.50
-
-Fixed multiple instances of OTT Player,
+**Version v1.0.50** - Fixed multiple instances of OTT Player,
 Applied SetInterval in Adepter,
 Added OTTActions support
 
-### Version v1.0.52
-
-Adapter, Downloader and Decoder Settings added to global player options
-
-### Version v1.0.53
+**Version v1.0.52** - Adapter, Downloader and Decoder Settings added to global player options
 
-More debug metrix added,
+**Version v1.0.53** - More debug metrix added,
 Pixel tickers color changed to dark gray
 
-### Version v1.0.55
+**Version v1.0.55** - Pattern tracking based renderer calls implemented
 
-Pattern tracking based renderer calls implemented
-
-### Version v1.0.57
-
-Added support for Windows Chrome,
+**Version v1.0.57** - Added support for Windows Chrome,
 Updated logging
 
-### Version v1.0.58
-
-Improve support for Windows Chrome
-
-### Version v1.0.59
+**Version v1.0.58** - Improve support for Windows Chrome
 
-Logging to Datadog Enabled
+**Version v1.0.59** - Logging to Datadog Enabled
 Minor improvements
 
-### Version v1.0.60
-
+**Version v1.0.60** - 
 - Game parameters are now fetched every 10 seconds.
 - After seeking, if new metadata with a relevant timecode is not received, the augmentation will stop.
 - Fixed an issue where the timecode exceeds 24 hours.
 
-### Version v1.0.61
-
-WebGL Quad rendering optimization
+**Version v1.0.61** - WebGL Quad rendering optimization
 Added error logging in case of the missing JSON in zip
 
-### Version v1.0.62
-
-Minor Update
+**Version v1.0.62** - Minor Update
 
-### Version v1.0.63
-
-Added setMediaInfo(mediaInfo: { fps?: number; bitrate?: number }) for communication with MK
+**Version v1.0.63** - Added setMediaInfo(mediaInfo: { fps?: number; bitrate?: number }) for communication with MK
 Added logging metrics to backend
 Hardcoded BurkerKing logo to be replaced by campaigns
 Dev tests of Firefox support
 
-### Version v1.0.64
-
-Added Beacon Evenst
+**Version v1.0.64** - Added Beacon Evenst
 Added onAdEvent
 Ad campaings connected
 Added internal metrics logging to cloud
 
-### Version v1.0.65
-
-Added global augmentation status to beacon events
+**Version v1.0.65** - Added global augmentation status to beacon events
 Console logs cleared
 
-### Version v1.0.66
+**Version v1.0.66** - Minor fixes
 
-Minor fixes
-
-### Version v1.0.67
-
-Killswitch status is now checked on game params headers instead of zip headers
+**Version v1.0.67** - Killswitch status is now checked on game params headers instead of zip headers
 Added metrics for zip fetch as URL parameters
 Implemented a zip fetch retry mechanism while there is still time to fetch them
 Added OTTPlayer off method to unsubscribe from player events
 Implemented destroy method to properly dispose OTTPlayer instances
 
-### Version v1.0.68
+**Version v1.0.68** - Zip download logic fixed
+
+**Version v1.1.00** -
+- Add banchmarking
+- Add Lifecicle management
+- Add status overlay
+- Fix toggle(flag: boolean)
+- Update onAdEvent(eventType: 'start' | 'end') logic
 
-Zip download logic fixed
+**Version v1.1.1** -
+- Fix no augmentation when showAugmentationStatus: false
+- Reset ads to default if no arguments provided to setAd()