# broadsign-player

> ## Features

Latest version **1.1.6** (published 2019-07-08) · ISC license · 0 weekly downloads

## Install

```sh
npm install broadsign-player
pnpm add broadsign-player
yarn add broadsign-player
bun add broadsign-player
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.6 |
| Published | 2019-07-08 |
| First published | 2019-07-03 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 166.7 KB |
| Known vulnerabilities | 0 (+25 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | alexchasejones |

## Links

- npm: https://www.npmjs.com/package/broadsign-player
- npm.io page: https://npm.io/package/broadsign-player

## Dependencies (1)

- [axios](https://npm.io/package/axios.md) ^0.19.0

## Recent versions

- 1.1.6 (latest) — 2019-07-08
- 1.1.5 — 2019-07-08
- 1.1.4 — 2019-07-04
- 1.1.3 — 2019-07-04
- 1.1.2 — 2019-07-04
- 1.1.1 — 2019-07-03
- 1.1.0 — 2019-07-03
- 1.0.99 — 2019-07-03
- 1.0.98 — 2019-07-03
- 1.0.97 — 2019-07-03
- 1.0.96 — 2019-07-03
- 1.0.95 — 2019-07-03
- 1.0.94 — 2019-07-03
- 1.0.93 — 2019-07-03
- 1.0.92 — 2019-07-03
- … 11 more at https://npm.io/package/broadsign-player/versions

## README

# bsp-interface

## Features

- BroadSignPlay/Render Lifecycle hook
- Content Variable and Monitor Sync integration
- Simplified Video API interface
- Simplified BSP Player API interface

## Browser Support

![Chrome](https://raw.github.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png) | ![Firefox](https://raw.github.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png) | ![Safari](https://raw.github.com/alrra/browser-logos/master/src/safari/safari_48x48.png) | ![Opera](https://raw.github.com/alrra/browser-logos/master/src/opera/opera_48x48.png) | ![Edge](https://raw.github.com/alrra/browser-logos/master/src/edge/edge_48x48.png) | ![IE](https://raw.github.com/alrra/browser-logos/master/src/archive/internet-explorer_9-11/internet-explorer_9-11_48x48.png) |
--- | --- | --- | --- | --- | --- |
Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 8+ ✔ |

## Installing

Using npm:

```bash
$ npm install broadsign-player
```

Using a cdn:

```html
<script src="https://unpkg.com/broadsign-player@1.1.4/lib/min.js"></script>
```

When using a CDN, the module will be namedspaced as `BSP`

## Examples

### Accessing Content Variables

Content variables are available through the `props` object.

```js
import BSP from 'broadsign-player';

const bsp = BSP();

console.log(bsp.props)
```

When running outside of a BroadSign Player environment, Automatic Variables are automagically simulated. The default values are:
```js
{
  ad_copy_id: '111111',
  campaign_id: '222222',
  display_unit_id: '333333',
  display_unit_address: '444444',
  display_unit_location_code: '555555',
  display_unit_lat_long: '40.7,-73.8',
  display_unit_resolution: '1080x1920',
  frame_id: '666666',
  frame_resolution: '1080x1920',
  player_id: '777777'
}
```

To simulate custom content variables in a dev environment, you can pass an object like so:
```js
import BSP from 'broadsign-player';

const contentVariables = {
	display_unit_lat_long: '40.1234567,-70.7654321',
	foo: 'bar'
}

const bsp = BSP(contentVariables);

console.log(bsp.props)

// {
//   ad_copy_id: '111111',
//   campaign_id: '222222',
//   display_unit_id: '333333',
//   display_unit_address: '444444',
//   display_unit_location_code: '555555',
//   display_unit_lat_long: '40.1234567,-70.7654321',
//   display_unit_resolution: '1080x1920',
//   frame_id: '666666',
//   frame_resolution: '1080x1920',
//   player_id: '777777',
//.  foo: 'bar'
// }
```

### BroadSignPlay/Render hook

```js
import BSP from 'broadsign-player';

const bsp = BSP();

bsp.render = () => {
	console.log('Do something like, start a video or a timer!')
}
```

In a Dev environment, the render method is executed after 3 seconds. When running on the BroadSign Player, this hook is tied directly to the BroadSignPlay function call. [Documentation on this can be found here](https://broadsign.com/docs/broadsign-control/13-0/broadsignplay.html).

### BroadSign Video API simplification

```js
import BSP from 'broadsign-player';

const bsp = BSP();
// params ::: path to video, width, height, offset X, offset Y
bsp.playVideo('videos/video.mp4', 1080, 1920, 0, 0);
```

This is all you need to do, the module takes care of preparing and playing video in a dev environment and a production environment. The only restriction is that you can't call this method in the `bsp.render()` hook, i.e:

```js
// This is an example of what NOT to do
import BSP from 'broadsign-player';

const bsp = BSP();

bsp.render = () => {
	bsp.playVideo('videos/video.mp4', 1080, 1920, 0, 0);
}
// This is an example of what NOT to do
```

This is bad and won't work. The reason being that when running on a BroadSign Player, the application needs time to prepare the video.

### BroadSign Player API simplified

```js
import BSP from 'broadsign-player';

const bsp = BSP();


bsp.stop();

bsp.trigger();

bsp.setCondition();

bsp.getConditions();

bsp.setExt();

bsp.showLoop();

bsp.nowPlaying();

bsp.logBroadSignIncident();

bsp.screenShot();

bsp.skipNext();
```

Full BSP API documentation at the bottom


### BroadSign Fetch Local File (monitor sync integration)

```js
import BSP from 'broadsign-player';

const monitorSyncConfig = {
	'dataOne.json': cv => `http://www.mapping.com/getInfo?location=${cv.display_unit_lat_long}`,
	'dataTwo.xml': () => 'http://www.someXmlFile.com/rss.xml';
}

const bsp = BSP({}, monitorSyncConfig);

bsp.fetchSyncData('data.json', (err, data) => {
	console.log(data)
})
```

In a development environment, the urls returned in the `monitorSyncConfig` object are fetched on every call to `bsp.fetchSyncData`. In a production environment, the application attempts to read the file from the `sync/` folder, using the object key name. For example, for the code snippet above, the ad copy in BroadSign would need a monitor sync configuration such as:
```xml
<monitor_sync_config version="1">
	<sync refresh_period="1800000" expiry="0" timeout_period="30000">
		<url sync_mode="1">
			<from>http://www.mapping.com/getInfo?location={{display_unit_lat_long}}</from>
			<to>dataOne.json</to>
		</url>
	</sync>
	<sync refresh_period="1800000" expiry="0" timeout_period="30000">
 		<url sync_mode="1">
			<from>http://www.someXmlFile.com/rss.xml</from>
			<to>DataTwo.xml</to>
		</url>
	</sync>
</monitor_sync_config>
```

The functions provided in the `monitorSyncConfig` object are provided the content variables as the first parameter, and all content variables can be used in the url.

## Recipe examples

### Recipe One: Use the Video API with params provided from content variables:

```js
import BSP from 'broadsign-player';

const config = {path: 'video.mp4', width: 1080, height: 1920 };

const bsp = BSP(config);

const { path, width, height } = bsp.props;

bsp.playVideo(path, width, height);
```

Locally, this will run as instructed in the `config` object but in a production environment it will read the content variables provided through the BroadSign pipelines (ad copy, player, display unit content variables).

# BSP API

* [BSP](#BSP)
    * [.setCondition(cb, name, enabled, exclusive)](#BSP+setCondition)
    * [.getConditions(cb)](#BSP+getConditions)
    * [.stop(cb, [frame_id])](#BSP+stop)
    * [.setExt(cb, customVals)](#BSP+setExt)
    * [.trigger(cb, trigger_id)](#BSP+trigger)
    * [.showLoop(cb, frame_id, loops)](#BSP+showLoop)
    * [.nowPlaying(cb, frame_id)](#BSP+nowPlaying)
    * [.logBroadSignIncident(cb, problem_description)](#BSP+logBroadSignIncident)
    * [.screenShot(cb, destination_url, scale_factor, screenshot_duration, screenshot_frequency)](#BSP+screenShot)

<a name="BSP+setCondition"></a>

### bsp.setCondition(cb, name, enabled, exclusive)
Sets a string condition (name) on the BroadSign Player

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| cb | <code>requestCallback</code> |  | The callback that handles the response. |
| name | <code>string</code> |  | The name of the condition to be set. |
| enabled | <code>boolean</code> |  | Indicate whether the condition will be enabled or disabled |
| exclusive | <code>boolean</code> | <code>false</code> | Indicate that the condition is of type exclusive. default=false(not exclusive) |

<a name="BSP+getConditions"></a>

### bsp.getConditions(cb)
Returns a list of currently active conditions on the player.

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Description |
| --- | --- | --- |
| cb | <code>requestCallback</code> | The callback that handles the response. |

<a name="BSP+stop"></a>

### bsp.stop(cb, [frame_id])
Stops the currently playing content.

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Description |
| --- | --- | --- |
| cb | <code>requestCallback</code> | The callback that handles the response. |
| [frame_id] | <code>integer</code> | The id of the frame to stop the content for. (optional) if omited, content for all frames will be stopped. |

<a name="BSP+setExt"></a>

### bsp.setExt(cb, customVals)
Sets a the ext1 and ext 2 fields in the pop request.

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Description |
| --- | --- | --- |
| cb | <code>requestCallback</code> | The callback that handles the response. |
| customVals | <code>object</code> | A Json representation of key values to be logged to pop data. |

<a name="BSP+trigger"></a>

### bsp.trigger(cb, trigger_id)
Sends a trigger to the player.

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Description |
| --- | --- | --- |
| cb | <code>requestCallback</code> | The callback that handles the response. |
| trigger_id | <code>object</code> | The id of the triger in BroadSign Control to fire. |

<a name="BSP+showLoop"></a>

### bsp.showLoop(cb, frame_id, loops)
Returns the scheduled loop for the next n loops.

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| cb | <code>requestCallback</code> |  | The callback that handles the response. |
| frame_id | <code>integer</code> | <code>0</code> | The id of the frame to return the content for. Default null will return the content for all frames on this player. |
| loops | <code>integer</code> | <code>1</code> | The number of future loops to return. default = 1 (The next loop only.) |

<a name="BSP+nowPlaying"></a>

### bsp.nowPlaying(cb, frame_id)
Returns the currently playing piece of content for a specific frame, or all frames.

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Description |
| --- | --- | --- |
| cb | <code>requestCallback</code> | The callback that handles the response. |
| frame_id | <code>integer</code> | The id of the frame to return the content for. Default null will return content playing on all frames on this player. |

<a name="BSP+logBroadSignIncident"></a>

### bsp.logBroadSignIncident(cb, problem_description)
Logs a custom incident to BroadSign.

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Description |
| --- | --- | --- |
| cb | <code>requestCallback</code> | The callback that handles the response. |
| problem_description | <code>string</code> | The description of the incident opened. |

<a name="BSP+screenShot"></a>

### bsp.screenShot(cb, destination_url, scale_factor, screenshot_duration, screenshot_frequency)
Takes a series of screenshots and sends them to an http destination

**Kind**: method of [<code>BSP</code>](#BSP)  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| cb | <code>requestCallback</code> |  | The callback that handles the response. |
| destination_url | <code>string</code> |  | The url to send the screenshot to. |
| scale_factor | <code>integer</code> | <code>25</code> | The percentage to which to screenshot will be scaled. default = 25 |
| screenshot_duration | <code>integer</code> | <code>1</code> | the length of time, the player will be taking screenshots for. |
| screenshot_frequency | <code>integer</code> | <code>1</code> | the frequency at which the player will be taking screenshots within the screenshot_duration. |

---
_Source: https://npm.io/package/broadsign-player · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._