MagicPlayer

MagicPlayer is a collection of components made to build a flexible, streaming ready media player for video as well as audio playback.

PreviewCode

<template>
  <div class="aspect-[16/9] w-full">
    <magic-player-provider
      id="magic-player-default-demo"
      :options="{
        src: 'https://stream.mux.com/3wVFr42nN3VqIVv01ugl00oSJTzKlhsZ01ep2yKz5vqeZ8.m3u8',
        srcType: 'hls',
      }"
    >
      <magic-player-video />
      <magic-player-poster>
        <magic-player-provider
          id="magic-player-default-demo-poster"
          :options="{
            src: 'https://stream.mux.com/kj7uNjRztuyNotBkAI55oUeVKSSN1C4ONrIYuYcRKxo/highest.mp4',
            autoplay: true,
            loop: true,
          }"
        >
          <magic-player-video />
          <magic-player-poster>
            <img
              src="https://image.mux.com/kj7uNjRztuyNotBkAI55oUeVKSSN1C4ONrIYuYcRKxo/thumbnail.png?time=0"
              alt="Poster"
            />
          </magic-player-poster>
        </magic-player-provider>
      </magic-player-poster>
      <magic-player-overlay />
      <magic-player-video-controls>
        <template #popover>
          <magic-player-mux-popover />
        </template>
      </magic-player-video-controls>
    </magic-player-provider>
  </div>
</template>

<style>
@import '@maas/vue-equipment/plugins/MagicPlayer/css/magic-player-video-controls.css';
</style>

Overview

Anatomy

vue

<template>
  <magic-player-provider id="your-player-id" src="your-src.m3u8">
    <magic-player-video />
    <magic-player-poster>
      <!-- your content -->
    </magic-player-poster>
    <magic-player-overlay />
    <magic-player-video-controls>
      <template #seek-popover>
        <magic-player-mux-popover />
      </template>
    </magic-player-video-controls>
  </magic-player-provider>
</template>

<script>
const { playerApi } = useMagicPlayer('your-player-id')
</script>

<style>
@import '@maas/vue-equipment/MagicPlayer/css/magic-player-video-controls.css';
</style>

Overview

Vue

If you are using Vue, import and add MagicPlayerPlugin to your app.

import { createApp } from 'vue'
import { MagicPlayerPlugin } from '@maas/vue-equipment/plugins/MagicPlayer'

const app = createApp({})

app.use(MagicPlayerPlugin)

Nuxt

The player is available as a Nuxt module. In your Nuxt config file add @maas/vue-equipment/nuxt to your modules and add MagicPlayer to the plugins in your configuration.

export default defineNuxtConfig({
  modules: ['@maas/vue-equipment/nuxt'],
  vueEquipment: {
    plugins: ['MagicPlayer'],
  },
})

Composable

In order to interact with the player from anywhere within your app, we provide a useMagicPlayer composable. Import it directly when needed.

import { useMagicPlayer } from '@maas/vue-equipment/plugins/MagicPlayer'

const { playerApi } = useMagicPlayer('your-player-id')

function handleClick() {
  playerApi.play()
}

TIP

If you have installed the component as a Nuxt module, the composable will be auto-imported and is automatically available in your Nuxt app.

Peer Dependencies

If you haven’t installed the required peer dependencies automatically, you’ll need to install the following packages manually.

Package
`@nuxt/kit`
`@vueuse/core`
`defu`
`hls.js`

Installation

pnpmnpmyarnbun

pnpm install @nuxt/kit @vueuse/core defu hls.js

npm install @nuxt/kit @vueuse/core defu hls.js

yarn add @nuxt/kit @vueuse/core defu hls.js

bun install @nuxt/kit @vueuse/core defu hls.js

API Reference

MagicPlayerProvider

The MagicPlayerProvider wraps the menu and configures all child components according to the provided options.

Props

Prop	Type	Required
`id`	`MaybeRef<string>`	`true`
`options`	`MagicPlayerOptions`	`false`

Options

To customize the player override the necessary options. Any custom options will be merged with the default options.

Option	Type	Default
`src`	`string`	`–`
`mode`	`PlayerMode`	`video`
`srcType`	`string`	`native`
`preload`	`string`	`metadata`
`autoplay`	`boolean`	`false`
`playback`	`string[]`	`['viewport'] \| ['viewport', 'window']`
`loop`	`boolean`	`false`
`debug`	`boolean`	`false`
`transition.videoControls`	`string`	`magic-player-video-controls`
`transition.overlay`	`string`	`magic-player-overlay`
`transition.icons`	`string`	`magic-player-icons`

CSS Variables

Variable	Default
`--magic-player-provider-height`	`auto`
`--magic-player-provider-aspect-ratio`	`16 / 9`
`--magic-player-provider-background`	`#000`

MagicPlayerOverlay

CSS Variables

Variable	Default
`--magic-player-overlay-background`	`rgba(0, 0, 0, 0.3)`
`--magic-player-overlay-color`	`rgba(255, 255, 255, 1)`
`--magic-player-overlay-button-size`	`2rem`

MagicPlayerVideoControls

Props

Prop	Type	Required
`id`	`MaybeRef<string>`	`false`
`standalone`	`boolean`	`false`
`transition.overlay`	`string`	`false`
`transition.icons`	`string`	`false`

CSS

Due to their complexity and opinionated nature, we have externalized the styles for this component. Make sure to import them if needed. If not style the component manually.

css

@import '@maas/vue-equipment/MagicPlayer/css/magic-player-video-controls.css';

MagicPlayerMuxPopover

Props

Prop	Type	Required
`playbackId`	`string`	`false`

CSS Variables

Variable	Default
`--magic-player-popover-border-radius`	`0.25rem`

MagicPlayerAudioControls

Props

Prop	Type	Required
`id`	`MaybeRef<string>`	`false`

CSS

Due to their complexity and opinionated nature, we have externalized the styles for this component. Make sure to import them if needed. If not style the component manually.

css

@import '@maas/vue-equipment/MagicPlayer/css/magic-player-audio-controls.css';

MagicPlayerDisplayTime

This component is used internally by both the video and audio controls components. You are most likely not going to need it directly, unless you want to implement your own custom controls.

Props

Prop	Type	Required
`type`	`string`	`false`

Errors

Source	Error Code	Message
`MagicPlayerMuxPopover`	`missing_instance_id`	`MagicPlayerMuxPopover must be nested inside MagicPlayerProvider or a playbackId must be provided`
`MagicPlayerMuxPopover`	`missing_options`	`MagicPlayerMuxPopover must be nested inside MagicPlayerVideoControls`
`MagicPlayerMuxPopover`	`fetch_timeline_error`	`Failed to fetch timeline preview`
`MagicPlayerMuxPopover`	`initialize_timeline_error`	`Can not initialize timeline preview`
`MagicPlayerAudioControls`	`missing_instance_id`	`MagicPlayerAudioControls must be nested inside MagicPlayerProvider`
`MagicPlayerVideo`	`missing_instance_id`	`MagicPlayerVideo must be used within a MagicPlayerProvider`
`MagicPlayerVideo`	`missing_options`	`MagicPlayerVideo must be used within a MagicPlayerProvider`
`MagicPlayerPoster`	`missing_instance_id`	`MagicPlayerPoster must be nested inside MagicPlayerProvider`
`MagicPlayerOverlay`	`missing_instance_id`	`MagicPlayerOverlay must be nested inside MagicPlayerProvider`
`MagicPlayerTimeline`	`missing_instance_id`	`MagicPlayerTimeline must be nested inside MagicPlayerProvider`
`MagicPlayerDisplayTime`	`missing_instance_id`	`MagicPlayerDisplayTime must be nested inside MagicPlayerProvider`
`MagicPlayerVideoControls`	`missing_instance_id`	`MagicPlayerVideoControls must be nested inside MagicPlayerProvider`
`usePlayerMediaApi`	`play_promise_rejected`	`Play promise was rejected`
`usePlayerMediaApi`	`play_promise_aborted`	`The play() request was aborted`
`usePlayerMediaApi`	`play_promise_not_allowed`	`Autoplay was prevented, user interaction required`
`usePlayerMediaApi`	`play_promise_not_supported`	`Media format not supported`
`usePlayerMediaApi`	`media_element_error`	`Media element error`
`usePlayerMediaApi`	`media_element_aborted`	`Media loading was aborted by the user`
`usePlayerMediaApi`	`media_element_network`	`A network error occurred while loading the media`
`usePlayerMediaApi`	`media_element_decode`	`An error occurred while decoding the media`
`usePlayerMediaApi`	`media_element_src_not_supported`	`The media source is not supported`
`usePlayerRuntime`	`hls_network_error`	`HLS network error`
`usePlayerRuntime`	`hls_media_recovery_failed`	`HLS media recovery failed`
`usePlayerRuntime`	`hls_media_error`	`HLS media error`
`usePlayerRuntime`	`hls_fatal_error`	`HLS fatal error`
`usePlayerRuntime`	`player_initialization_failed`	`Player initialization failed`

Examples

Audio Player

PreviewCode

Loveless

0:00

<template>
  <div class="w-full">
    <magic-player-provider
      id="magic-player-audio-demo"
      :options="{ mode: 'audio', src: '/demo/magic-player/loveless.mp3' }"
      class="bg-surface-high rounded-surface-sm flex flex-col gap-2 p-2"
    >
      <span
        class="bg-surface-base rounded-surface-sm-inset type-surface-callout-md block w-full p-4"
      >
        Loveless
      </span>
      <magic-player-audio-controls class="px-4" />
      <magic-player-audio />
    </magic-player-provider>
  </div>
</template>

<style>
@import '@maas/vue-equipment/plugins/MagicPlayer/css/magic-player-audio-controls.css';
</style>

Autoplay

PreviewCode

<template>
  <div class="aspect-[16/9] w-full">
    <magic-player-provider
      id="magic-player-autoplay-demo"
      :options="{
        autoplay: true,
        loop: true,
        src: 'https://stream.mux.com/kj7uNjRztuyNotBkAI55oUeVKSSN1C4ONrIYuYcRKxo/highest.mp4',
      }"
    >
      <magic-player-video />
    </magic-player-provider>
  </div>
</template>

Autoplay with Controls

PreviewCode

<template>
  <div class="aspect-[16/9] w-full">
    <magic-player-provider
      id="magic-player-autoplay-controls-demo"
      :options="{
        src: 'https://stream.mux.com/3wVFr42nN3VqIVv01ugl00oSJTzKlhsZ01ep2yKz5vqeZ8.m3u8',
        srcType: 'hls',
        autoplay: true,
      }"
    >
      <magic-player-video />
      <magic-player-overlay />
      <magic-player-video-controls>
        <template #popover>
          <magic-player-mux-popover />
        </template>
      </magic-player-video-controls>
    </magic-player-provider>
  </div>
</template>

<style>
@import '@maas/vue-equipment/plugins/MagicPlayer/css/magic-player-video-controls.css';
</style>

Controls without Overlay

PreviewCode

<template>
  <div class="aspect-[16/9] w-full">
    <magic-player-provider
      id="magic-player-omit-overlay-demo"
      :options="{
        src: 'https://stream.mux.com/3wVFr42nN3VqIVv01ugl00oSJTzKlhsZ01ep2yKz5vqeZ8.m3u8',
        srcType: 'hls',
      }"
    >
      <magic-player-video />

      <magic-player-video-controls>
        <template #popover>
          <magic-player-mux-popover />
        </template>
      </magic-player-video-controls>
    </magic-player-provider>
  </div>
</template>

<style>
@import '@maas/vue-equipment/plugins/MagicPlayer/css/magic-player-video-controls.css';
</style>

Standalone Controls

PreviewCode

<template>
  <div class="flex w-full flex-col">
    <magic-player-provider
      id="magic-player-standalone-controls-demo"
      :options="{
        src: 'https://stream.mux.com/3wVFr42nN3VqIVv01ugl00oSJTzKlhsZ01ep2yKz5vqeZ8.m3u8',
        srcType: 'hls',
      }"
    >
      <magic-player-video />
      <magic-player-poster>
        <img
          src="https://image.mux.com/3wVFr42nN3VqIVv01ugl00oSJTzKlhsZ01ep2yKz5vqeZ8/thumbnail.jpg?time=4"
          alt="Poster"
        />
      </magic-player-poster>
      <magic-player-overlay />
    </magic-player-provider>
    <div class="relative flex w-full items-center pt-4">
      <magic-player-video-controls
        id="magic-player-standalone-controls-demo"
        class="bg-black"
        standalone
      >
        <template #timeline-before>
          <magic-player-display-time type="current" />
        </template>
        <template #timeline-after>
          <magic-player-display-time type="duration" />
        </template>
      </magic-player-video-controls>
    </div>
  </div>
</template>

<style>
@import '@maas/vue-equipment/plugins/MagicPlayer/css/magic-player-video-controls.css';
</style>

Native Controls

PreviewCode

<template>
  <div class="aspect-[16/9] w-full">
    <magic-player-provider
      id="magic-player-native-controls-demo"
      :options="{
        src: 'https://stream.mux.com/3wVFr42nN3VqIVv01ugl00oSJTzKlhsZ01ep2yKz5vqeZ8.m3u8',
        srcType: 'hls',
      }"
    >
      <magic-player-video controls />
    </magic-player-provider>
  </div>
</template>

Poster Image

PreviewCode

<template>
  <div class="aspect-[9/16] w-full">
    <magic-player-provider
      id="magic-player-image-poster-demo"
      :style="{ '--magic-player-provider-aspect-ratio': '9/16' }"
      :options="{
        src: 'https://stream.mux.com/PniSBG6rbyou2x5jExB9EwYQAgBXGyqxXA023GC6JeXQ/highest.mp4',
      }"
    >
      <magic-player-video />
      <magic-player-poster>
        <img
          src="https://image.mux.com/PniSBG6rbyou2x5jExB9EwYQAgBXGyqxXA023GC6JeXQ/thumbnail.jpg?time=8"
          alt="Poster"
        />
      </magic-player-poster>
      <magic-player-overlay />
    </magic-player-provider>
  </div>
</template>

Composable

PreviewCode

<template>
  <div class="flex w-full flex-col items-center gap-4">
    <div class="aspect-[16/9] w-full">
      <magic-player-provider
        id="magic-player-composable-demo"
        :options="{
          autoplay: true,
          loop: true,
          src: 'https://stream.mux.com/kj7uNjRztuyNotBkAI55oUeVKSSN1C4ONrIYuYcRKxo/highest.mp4',
        }"
      >
        <magic-player-video />
      </magic-player-provider>
    </div>
    <div class="flex gap-4">
      <m-button @click="playerApi.videoApi.togglePlay()">
        Toggle Play
      </m-button>
    </div>
  </div>
</template>

<script lang="ts" setup>
import { useMagicPlayer } from '@maas/vue-equipment/plugins/MagicPlayer'
const playerApi = useMagicPlayer('magic-player-composable-demo')
</script>

MagicPlayer ​

Overview ​

Anatomy ​

Overview ​

Vue ​

Nuxt ​

Composable ​

Peer Dependencies ​

Installation ​

API Reference ​

MagicPlayerProvider ​

Props ​

Options ​

CSS Variables ​

MagicPlayerOverlay ​

CSS Variables ​

MagicPlayerVideoControls ​

Props ​

CSS ​

MagicPlayerMuxPopover ​

Props ​

CSS Variables ​

MagicPlayerAudioControls ​

Props ​

CSS ​

MagicPlayerDisplayTime ​

Props ​

Errors ​

Examples ​

Audio Player ​

Autoplay ​

Autoplay with Controls ​

Controls without Overlay ​

Standalone Controls ​

Native Controls ​

Poster Image ​

Composable ​

MagicPlayer

Overview

Anatomy

Overview

Vue

Nuxt

Composable

Peer Dependencies

Installation

API Reference

MagicPlayerProvider

Props

Options

CSS Variables

MagicPlayerOverlay

CSS Variables

MagicPlayerVideoControls

Props

CSS

MagicPlayerMuxPopover

Props

CSS Variables

MagicPlayerAudioControls

Props

CSS

MagicPlayerDisplayTime

Props

Errors

Examples

Audio Player

Autoplay

Autoplay with Controls

Controls without Overlay

Standalone Controls

Native Controls

Poster Image

Composable