# Events

You can listen to **all player events**, **groups of events**, or **individual events** to react to user interaction, playback state changes, ads, and UI behavior.

Events can be subscribed to using:

* **`.on(event, callback)`** – listens to an event continuously and is triggered every time the event occurs.
* **`.once(event, callback)`** – listens to an event only once and is automatically removed after the first trigger.

You can subscribe to:

* all events (e.g. `*.*`),
* a specific event namespace (e.g. `media.*`, `player.*`),
* or a single event (e.g. `media.ready`).

**Examples**

```javascript
// Listen to all events (not recommended)
player.on('*.*', function (data) {
    console.log('js3q::' + this.event + ' ' + JSON.stringify(data));
});

// Listen to all media events
player.on('media.*', function (data) {
    console.log('js3q::' + this.event + ' ' + JSON.stringify(data));
});

// Listen to a specific event only once
player.once('media.ready', function (data) {
    console.log('js3q::' + this.event + ' ' + JSON.stringify(data));
});
```

### Player Events

| Event                      | Description                       |
| -------------------------- | --------------------------------- |
| `player.init`              | Player initialization started     |
| `player.ready`             | Player is ready                   |
| `player.uiready`           | Player UI is ready                |
| `player.fullscreenChange`  | Player entered or left fullscreen |
| `player.controllbarChange` | Control bar state changed         |
| `player.playRequest`       | User requested playback           |
| `player.pauseRequest`      | User requested pause              |
| `player.seekRequest`       | User requested seek               |
| `player.bufferingChange`   | Buffering state changed           |
| `player.displayClickEvent` | Click on player surface           |
| `player.menusOpenRequest`  | Open menu requested               |
| `player.menusCloseRequest` | Close menu requested              |
| `player.playlistShow`      | Playlist opened                   |
| `player.playlistHide`      | Playlist closed                   |
| `player.destroy`           | Player destroyed                  |

***

### Configuration Events

| Event                     | Description                       |
| ------------------------- | --------------------------------- |
| `configuration.loaded`    | Configuration loaded successfully |
| `configuration.changed`   | Configuration changed             |
| `configuration.cssLoaded` | Configuration CSS loaded          |
| `configuration.loadError` | Configuration failed to load      |

### Media Events

| Event                       | Description              |
| --------------------------- | ------------------------ |
| `media.init`                | Media initialized        |
| `media.loading`             | Media loading            |
| `media.ready`               | Media ready              |
| `media.playing`             | Media playback started   |
| `media.paused`              | Media playback paused    |
| `media.complete`            | Media playback completed |
| `media.seeking`             | Seek started             |
| `media.seeked`              | Seek completed           |
| `media.timeChange`          | Playback time changed    |
| `media.durationChange`      | Media duration changed   |
| `media.volumeChange`        | Volume changed           |
| `media.muted`               | Media muted              |
| `media.unmuted`             | Media unmuted            |
| `media.subtitleChange`      | Subtitle changed         |
| `media.subtitleTrackChange` | Subtitle track changed   |
| `media.audioChange`         | Audio track changed      |
| `media.dvrChange`           | DVR window changed       |
| `media.switchSource`        | Media source switched    |
| `media.backToLiveRequest`   | Back to live requested   |
| `media.mediaNotFound`       | Media not found          |
| `media.autoplay`            | Autoplay succeeded       |
| `media.autoplayfailed`      | Autoplay failed          |
| `media.autoplaymuted`       | Autoplay started muted   |
| `media.destroy`             | Media destroyed          |

### Ad Events

| Event                      | Description                |
| -------------------------- | -------------------------- |
| `ads.initEvent`            | Ad system initialized      |
| `ads.loadError`            | Ad loading failed          |
| `ads.adRequest`            | Ad requested               |
| `ads.adLoaded`             | Ad loaded                  |
| `ads.adPlaying`            | Ad started                 |
| `ads.adPaused`             | Ad paused                  |
| `ads.skipped`              | Ad skipped                 |
| `ads.skippableChange`      | Ad skippable state changed |
| `ads.adClick`              | Ad clicked                 |
| `ads.adError`              | Ad error occurred          |
| `ads.adComplete`           | Ad finished                |
| `ads.contentPauseRequest`  | Content paused for ad      |
| `ads.contentResumeRequest` | Content resumed after ad   |
| `ads.completeEvent`        | All ads completed          |

### Casting Events

| Event          | Description     |
| -------------- | --------------- |
| `cast.started` | Casting started |
| `cast.resumed` | Casting resumed |
| `cast.stopped` | Casting stopped |

### Call-to-Action (CTA) Events

| Event            | Description   |
| ---------------- | ------------- |
| `cta.displaying` | CTA displayed |
| `cta.closed`     | CTA closed    |

### UI & Control Events

| Event                    | Description        |
| ------------------------ | ------------------ |
| `controls.hover`         | Controls hovered   |
| `controls.seekBarExpand` | Seek bar expanded  |
| `controls.showQoS`       | QoS panel shown    |
| `controls.hideQoS`       | QoS panel hidden   |
| `sidebar.toggle`         | Sidebar toggled    |
| `transcript.toggle`      | Transcript toggled |
| `thumbnails.toggle`      | Thumbnails toggled |
| `download.toggle`        | Download toggled   |

### Sticky Player Events

| Event                       | Description            |
| --------------------------- | ---------------------- |
| `sticky.change`             | Sticky mode changed    |
| `sticky.stickyCloseRequest` | Sticky close requested |


---

# 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://player.docs.3q.video/player-web-sdk/events.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.