# 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>
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.firework.com/firework-for-developers/web/integration-guide/player.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.