Wistia Learning Center
Guides
Login

Aurora Methods

Learn more about the methods available for your embedded player.

Suggest Edits

Quick reference

NameDescription
cancelFullscreen()Exits fullscreen if the media is playing in fullscreen mode.
definePlugin(name, options)Defines a plugin on the player.
getPlugin(name)Gets a plugin from the player.
pause()Pauses the media.
play()Plays the media.
releaseControls(requesterName)Registers that requesterName would like the controls to return to their normal behavior.
replaceWithMedia(mediaId, options)Replaces the content of the current media with the media identified by the mediaId.
requestControls(requesterName)Registers that requesterName would like the controls to be visible.
requestFullscreen()Attempts to enter fullscreen mode.

Try it!

Methods:

Using methods

The methods we've included can be used to further customize and add functionality to the player. As long as you have a reference to your <wistia-player> element, you can use methods like play() by calling <wistia-player>.play().

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<wistia-player id="my-player" media-id="abc123"></wistia-player>

<button type="button" id="my-play-button">Play</button>

<script>
  const player = document.getElementById("my-player");
  const myPlayButton = document.getElementById("my-play-button");
  
  // When our custom button is clicked, play the video.
  myPlayButton.addEventListener("click", () => {
    player.play();
  });
</script>

You can also target every <wistia-player> on your page at once using browser functions like getElementsByTagName():

<script src="https://fast.wistia.com/player.js" async></script>

<wistia-player id="my-player" media-id="abc123"></wistia-player>
<wistia-player id="my-player" media-id="def456"></wistia-player>
<wistia-player id="my-player" media-id="ghi789"></wistia-player>

<button type="button" id="my-play-all-button">Chaos!</button>

<script>
  const allPlayers = document.getElementsByTagName("wistia-player");
  const playAllButton = document.getElementById("my-play-all-button");

  // When our custom button is clicked, play every video we can find!
  playAllButton.addEventListener("click", () => {
    for (const player of allPlayers) {
      player.play();
    }
  });
</script>

Methods can also be used with the React component version of the player, <WistiaPlayer>. 

import { useRef } from 'react';
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // When our custom button is clicked, play the video.
  function handleClick() {
    if (player.current === null) { return; }
    player.current.play();
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Play</button>
  );
}

cancelFullscreen()

Exits fullscreen if the media is playing in fullscreen mode.

const player = document.getElementById("my-player");
const customCancelButton = document.getElementById("cancel-button");

// When our custom button is clicked, exit fullscreen.
customCancelButton.addEventListener("click", () => {
  player.cancelFullscreen();
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // When our custom button is clicked, exit fullscreen.
  function handleClick() {
    if (player.current === null) { return; }
    player.current.cancelFullscreen();
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Cancel Fullscreen</button>
  );
}

definePlugin(name, options)

Defines a plugin on the player. For more information on plugins, see our Plugin API Documentation.

Parameters:

NameTypeDescription
namestringRequired. The name of the plugin.
optionsobjectThe options to be defined on the plugin.
const player = document.getElementById("my-player");

// As soon as the player embed has an api, add a plugin.
player.addEventListener("api-ready", () => {
  player.definePlugin("turnstile", {
    time: "before",
    topText: "Please enter your email to view this video.",
  });
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // As soon as the player embed has an api, add a plugin.
  function handleApiReady() {
    if (player.current === null) { return; }
    player.current.definePlugin("turnstile", {
      time: "before",
      topText: "Please enter your email to view this video.",
    });
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onApiReady={handleApiReady} />
  );
}

getPlugin(name)

Gets a plugin from the player. For more information on plugins, see our Plugin API Documentation.

Parameters:

NameTypeDescription
namestringRequired. The name of the plugin.
const player = document.getElementById("my-player");

// As soon as the player embed has an api, get a plugin.
player.addEventListener("api-ready", () => {
  player.getPlugin("turnstile");
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // As soon as the player embed has an api, get a plugin.
  function handleApiReady() {
    if (player.current === null) { return; }
    player.current.getPlugin("turnstile");
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onApiReady={handleApiReady} />
  );
}

pause()

Pauses the media. If this is called and the video's state is "playing", it's expected that it will change to "paused".

const player = document.getElementById("my-player");
const customPauseButton = document.getElementById("pause-button");

// When our custom button is clicked, pause the video.
customPauseButton.addEventListener("click", () => {
  player.pause();
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // When our custom button is clicked, pause the video.
  function handleClick() {
    if (player.current === null) { return; }
    player.current.pause();
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Pause</button>
  );
}

play()

Plays the media. If this is called, it is expected that the media's state will change to "playing".

❗️

About play...

On iOS, desktop Safari, and other mobile devices, videos cannot be issued the "play" command outside the context of a user-driven or video event.

For example, "click" and "touch" events are user-driven, and video events include "pause" and "ended" (you can listen for these using player.addEventListener(eventType, callbackFn) described in the Events Documentation. Because of this restriction, you should avoid calling play() within a setTimeout callback or other asynchronous functions like XHR or JavaScript promises.

Please refer to Apple's Documentation for the reasons behind this behavior.

const player = document.getElementById("my-player");
const customPlayButton = document.getElementById("play-button");

// When our custom button is clicked, play the video.
customPlayButton.addEventListener("click", () => {
  player.play();
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // When our custom button is clicked, play the video.
  function handleClick() {
    if (player.current === null) { return; }
    player.current.play();
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Play</button>
  );
}

releaseControls(requesterName)

Registers that requesterName would like the controls to return to their normal behavior.

Parameters:

NameTypeDescription
requesterNamestringRequired. Name of the control which no longer needs the player controls to be visible.
const player = document.getElementById("my-player");
const customReleaseButton = document.getElementById("release-button");

// When our custom button is clicked, release the controls.
customReleaseButton.addEventListener("click", () => {
  player.releaseControls("my-control");
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // When our custom button is clicked, release the controls.
  function handleClick() {
    if (player.current === null) { return; }
    player.current.releaseControls("my-control");
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Release Controls</button>
  );
}

replaceWithMedia(mediaId, options)

🙌

Note: Before using this, you might want to see if embed and playlist links cover your use case.

Replaces the content of the current media with the media identified by the mediaId.

This media will be loaded with all its customizations, which can be overridden in the options object. This method can be used in conjunction with addToPlaylist(media, options, position) to create custom playlist implementations.

In addition to the normal embed options, you can set the transition option, which defines how to visually transition to the new video. Available values are "slide", "fade", "crossfade", and "none". By default, "fade" is used.

Parameters:

NameTypeDescription
mediaIdstringRequired. The ID of the new media to be shown in the player.
optionsobjectEmbed options to be set on the new media and the transition to be used.
const player = document.getElementById("my-player");
const customReplaceButton = document.getElementById('replace-video');

// When our custom button is clicked, replace the video.
customReplaceButton.addEventListener('click', () => {
  player.replaceWithMedia("def456", {
    playerColor: "00ff00",
    transition: "slide",
  });
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // When our custom button is clicked, replace the video.
  function handleClick() {
    if (player.current === null) { return; }
    player.current.replaceWithMedia("def456", {
      playerColor: "00ff00",
      transition: "slide",
    });
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Replace Video</button>
  );
}

requestControls(requesterName)

Registers that requesterName would like the controls to be visible.

Parameters:

NameTypeDescription
requesterNamestringRequired. Name of the control which would like the player controls to be visible.
const player = document.getElementById("my-player");
const customRequestButton = document.getElementById('request-button');

// When our custom button is clicked, request the controls.
customRequestButton.addEventListener("click", () => {
  player.requestControls("my-control");
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // When our custom button is clicked, request the controls.
  function handleClick() {
    if (player.current === null) { return; }
    player.current.requestControls("my-control");
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Request Controls</button>
  );
}

requestFullscreen()

Attempts to enter fullscreen mode.

🙌

Note: This method will only work if called in response to a user-initiated event, such as a click or a keyboard event. It will not work if called as part of an async operation, such as a timeout.

const player = document.getElementById("my-player");
const customFullscreenButton = document.getElementById('fullscreen-button');

// When our custom button is clicked, enter fullscreen.
customFullscreenButton.addEventListener("click", () => {
  player.requestFullscreen();
});

import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // When our custom button is clicked, enter fullscreen.
  function handleClick() {
    if (player.current === null) { return; }
    player.current.requestFullscreen();
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Request Fullscreen</button>
  );
}

Updated 8 days ago