# Player

Firework Player is a component directly rendered by widgets (storyblock, hero unit, player) or initiated after user interaction (carousel, storylink). All players on a scene are registered for programmatic access as soon as they are rendered under a `_fwn.players` map.

## Programmatic control

`window._fwn.players`

* is a map of all players on a scene referenced by a parent widget name.

```html
<!-- E.g.: Widget with name "my-carousel" will have its player accessible by -->
<fw-carousel name="my-carousel" channel="my-channel" />

<!-- will have its player accessible -->
<script type="text/javascript">
    document.addEventListener("fw:player:ready", ({ detail: { name, player } }) => {
        // `window._fwn.players[name]`
        // or `player`
    })
</script>
```

`window._fwn.player`

* is a reference to a player currently in fullscreen or floating.

### Attributes

| Name          | Description                                                             |
| ------------- | ----------------------------------------------------------------------- |
| `video`       | Current video loaded                                                    |
| `currentTime` | Returns current time. Assigning a new value will seek to that position. |
| `muted`       | Flag indicating muted state                                             |

### Methods

| Method       | Description                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------- |
| `play`       | Trigger play                                                                                  |
| `pause`      | Pause the video                                                                               |
| `mute`       | Change mute status                                                                            |
| `unmute`     | Unmute                                                                                        |
| `close`      | Close the player                                                                              |
| `minimize`   | Minimize to floating layout                                                                   |
| `fullscreen` | Switch to fullscreen layout                                                                   |
| `on`         | Subscribe to an event with async callback to control certain behavior. More on events bellow. |
| `off`        | Unsubscribe from an event                                                                     |

### Events

Events provides a way to subscribe to certain player UI interactions with the intention to interrupt them. E.g.: Allow authenticated only to post a livestream chat message.

| Event                                          | Description                                                                                   |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `livestream-enter`                             | Fired when user clicks "Tap to enter livestream" with the first livestream they try to enter. |
| `livestream-chat-input-focus`                  | Clicking on livestream chat input.                                                            |
| `livestream-interaction-giveaway-enter`        | Clicking on a livestream giveaway interaction.                                                |
| `livestream-interaction-trivia-giveaway-enter` | Clicking on a trivia giveaway.                                                                |
| `livestream-interaction-poll-enter`            | Clicking on a poll.                                                                           |
| `livestream-interaction-question-enter`        | Clicking on a question interaction.                                                           |
| `livestream-interaction-heart`                 | Clicking on a "heart" interaction                                                             |

```html
<!-- Storyblock with a name -->
<fw-storyblock name="my-storyblock" channel="my-channel" />

<!-- Subscribe to a global event to receive a player reference as soon as its ready to be used. -->
<script type="text/javascript">
    async function checkAuthStatus() {
        // Check for authentication flags
    }

    document.addEventListener("fw:player:ready", ({ detail: { name, player } }) => {
        if (name == "my-storyblock") {
            // Subscribe to an event to check auth status before
            // interactin with chat input happens.
            player.on("livestream-chat-input-focus", () => {
                return new Promise((resolve, reject) => {
                    checkAuthStatus().then(resolve).error(reject)
                })
            })
            // Same example using async/await
            player.on("livestream-chat-input-focus", async () => {
                if (!await checkAuthStatus()) {
                    throw Exception('Unauthorized')
                }
            })
        }
    })
</script>
```