> For the complete documentation index, see [llms.txt](https://help.blings.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blings.io/apps/blings-studio/connectors/player-events.md).

# Player Events

Use Player Events when custom code should run at a specific player lifecycle moment. Player-event logic can support advanced interactions, external calls, state updates, frame-based behavior, and custom analytics-adjacent workflows.

<figure><img src="/files/xD0N1YzYvk436tZOYKCZ" alt="Shared Studio connector detail panel where advanced connector behavior, source mode, and internal description controls are configured" width="375"><figcaption></figcaption></figure>

## Event Types

| Event           | When it runs                                                 | Common use                                                               |
| --------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **onAllReady**  | When the video is ready to play.                             | Initialize custom state or prepare external behavior.                    |
| **onFirstPlay** | Immediately after the viewer clicks play for the first time. | Trigger first-play logic that should run once.                           |
| **onPlay**      | Every time the viewer presses play.                          | Resume state, trigger play-specific behavior, or restart a custom timer. |
| **onFrame**     | When the video reaches a configured frame.                   | Trigger frame-specific behavior, reveal logic, or external calls.        |
| **onReplay**    | When the viewer finishes watching and presses replay.        | Reset custom state for another viewing pass.                             |
| **onPause**     | When the viewer pauses the video.                            | Pause custom timers or update external state.                            |
| **onMute**      | When the viewer mutes the video.                             | Update audio-related state or custom UI logic.                           |
| **onUnmute**    | When the viewer unmutes the video.                           | Restore audio-related state or custom UI logic.                          |

## Options

| Option               | What it controls                                                       | Notes                                                                      |
| -------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **Event trigger**    | The lifecycle event that runs the code.                                | Choose the narrowest event that matches the desired behavior.              |
| **Frame value**      | The frame that triggers `onFrame`.                                     | Confirm the frame exists and is reached in every relevant path.            |
| **Custom code**      | The JavaScript that runs for the event.                                | Keep the code focused on the event's purpose.                              |
| **Input values**     | Any project data, live-control value, or state referenced by the code. | Confirm referenced values exist and have fallbacks.                        |
| **Repeat behavior**  | Whether the code should run once or every time the event occurs.       | Important for `onPlay`, `onPause`, `onMute`, `onUnmute`, and replay flows. |
| **Failure handling** | What happens if a value is missing or an external action fails.        | Avoid blocking normal playback.                                            |

## Configure a Player Event

{% stepper %}
{% step %}

### Choose the Event

Select the lifecycle moment that should run the code.
{% endstep %}

{% step %}

### Define the Behavior

Write down what the event should do and whether it should happen once, every time, or only under a condition.
{% endstep %}

{% step %}

### Add the Code

Add the event code and keep any data references aligned with the project schema.
{% endstep %}

{% step %}

### Add Failure Handling

Make sure missing data, repeated triggers, and external failures do not break normal playback.
{% endstep %}

{% step %}

### Test the Playback Path

Preview the experience through play, pause, mute, unmute, frame triggers, completion, and replay when those events are used.
{% endstep %}
{% endstepper %}

## Success Checks

Before publishing Player Events, confirm:

* The selected event matches the intended playback moment.
* Repeated events do not run code more often than intended.
* `onFrame` triggers at the correct frame in each relevant path.
* Missing data and external failures do not stop playback.
* Custom event code does not interfere with analytics, form submission, links, or normal player controls.

{% content-ref url="/pages/vF3GOo8viXK19zuT75hD" %}
[Data in Studio](/apps/blings-studio/data.md)
{% endcontent-ref %}