---
updatedAt: 2026-10-22T17:33:33.000Z
agentTools:
  projectIndex: https://docs.wistia.com/llms.txt
---

# Migrating from the Legacy Player (Vulcan) to Aurora

Aurora is the current Wistia Player. It replaces the previous-generation player (Vulcan), and it's built as a [Web Component.](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) It's a native `<wistia-player>` HTML element rather than a JavaScript object you retrieve through a queue. If you have a custom Vulcan integration, most of what you were doing is still possible in Aurora. The shape of the calls is just different.&#x20;

This page maps the patterns our team is asked about most. For the complete API, see [Player Events](https://docs.wistia.com/docs/player-events), [Player Methods](https://docs.wistia.com/docs/player-methods), and [Attributes & Properties](https://docs.wistia.com/docs/player-attributes-and-properties). For the basics of grabbing a player on your page, see [Interacting with Aurora on your page](https://docs.wistia.com/docs/interacting-with-aurora-on-your-page).

## Readiness callbacks: `_wq.push` and `bind("ready", ...)`

In Vulcan, you waited for the player by pushing an `onReady` handler onto `_wq`, or by calling `bind("ready", ...)` on a `wistiaEmbed` reference:

```javascript Vulcan
window._wq = window._wq || [];
_wq.push({
  id: "abc123",
  onReady: function(video) {
    video.play();
  }
});
```

In Aurora, the equivalent is the [`api-ready`](https://docs.wistia.com/docs/player-events#api-ready) event, dispatched on the `<wistia-player>` element once its API is initialized:

```html Aurora — HTML + JavaScript
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>

<script>
  const player = document.getElementById("my-player");
  player.addEventListener("api-ready", () => {
    player.play();
  });
</script>
```

In React, use the [`onApiReady`](https://docs.wistia.com/docs/player-events#api-ready) prop:

```jsx Aurora — React
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  return (
    <WistiaPlayer
      mediaId="abc123"
      onApiReady={(event) => event.target.play()}
    />
  );
}
```

You don't need a `_wq` queue as Aurora's `<wistia-player>` element exists in the DOM as soon as the browser parses it, so you can attach listeners immediately.

## Reading duration and other metadata

In Vulcan, your `onReady` callback received a `video` handle whose metadata methods (`getAssetDuration()`, `videoWidth()`, `videoHeight()`) returned values right away.

In Aurora, [`duration`](https://docs.wistia.com/docs/player-attributes-and-properties#duration) is exposed as a read-only property on the `<wistia-player>` element — but `api-ready`**&#x20;fires before metadata has loaded**. Wait for [`loaded-metadata`](https://docs.wistia.com/docs/player-events#loaded-metadata) before reading it:

```html Aurora — HTML + JavaScript
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>

<script>
  const player = document.getElementById("my-player");
  player.addEventListener("loaded-metadata", () => {
    console.log(player.duration);
  });
</script>
```

Depending on the browser, `loaded-metadata` may be delayed until the viewer interacts with the video.

**Reading the asset's width and height** is no longer exposed on the player itself. If you need the underlying video's intrinsic dimensions, fetch them from the [Data API `GET /v1/medias/{hashed_id}` endpoint](https://docs.wistia.com/reference/get_medias-mediahashedid), which returns each asset with its `width` and `height`. To reserve the right amount of layout space at render time without a fetch, set the [`aspect`](https://docs.wistia.com/docs/player-attributes-and-properties#aspect) attribute on the embed.

## React component event timing

`<WistiaPlayer>` is a thin wrapper around `<wistia-player>` and follows the same event lifecycle. A few patterns to watch for when porting React code:

* `onApiReady`**&#x20;does not fire synchronously on mount.** If your code calls `play()` or `seekTo()` from a `useEffect` that depends on the ref, gate the call on `onApiReady` instead.
* **Methods on the ref require the API to be ready.** Calling `myPlayer.current.play()` before `api-ready` is a no-op. Use the ref pattern from [Player Methods](https://docs.wistia.com/docs/player-methods) and trigger from event handlers or user actions, not directly inside render or mount effects.
* **Programmatic seeks fire&#x20;**`seeking`**&#x20;and&#x20;**`seeked`**&#x20;the same as user-initiated seeks** — there is no separate "internal seek" event. If you need to distinguish them, set a flag in your code before calling `currentTime = ...` and clear it inside the `seeked` handler.

For the full React API, see [Aurora React Component](https://docs.wistia.com/docs/player-react-component).