@byteark/byteark-player-vue

ByteArk Player Container for Vue.js

Table of Contents

• ByteArk Player Container for Vue.js
  • Demo
  • Features
  • Compatibility
  • Installation
  • Usage
  • ByteArkPlayerContainer Props
    • ByteArk Player Options
    • Source Object
  • Event Handling
  • Advanced Usages
    • Controlling Players
    • Using VideoJS Plugins
    • Request Media/Encryption with credentials
  • License

Demo

You can try on the demo page.

Features

• Remote player updates. No need to update your code for minor improvements.
• Show placeholder while waiting the player to be ready.
• Controls basic behaviours via props.
• Custom advanced callbacks to access ByteArk Player/VideoJS instance directly.

Compatibility

Since Vue 3 is not backward compatible, please make sure to install the correct ByteArk Player Container version based on your Vue version.

Vue Version	Package Version	Branch
2.x	3.x	master
3.x	4.x	main

Installation

This library is distributed via NPM. You may install from NPM, Yarn, PNPM.

# For NPM
npm install --save @byteark/byteark-player-vue
# For Yarn
yarn add @byteark/byteark-player-vue
# For PNPM
pnpm add @byteark/byteark-player-vue

Usage

1. Include and register ByteArkPlayerContainer in your project.

<template>
  <ByteArkPlayerContainer
    :options="playerOptions"
  />
</template>

<script setup lang="ts">
import ByteArkPlayerContainer from '@byteark/byteark-player-vue';
import type { ByteArkPlayerOptions } from '@byteark/byteark-player-vue';

const playerOptions: ByteArkPlayerOptions = {
  autoplay: 'any',
  fluid: true,
  aspectRatio: '16:9',
  poster: 'https://stream-image.byteark.com/image/video-cover-480p/7/K/7KPloVWgN.png',
  sources: [{
    src: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
    type: 'application/x-mpegURL',
    title: 'Big Buck Bunny',
    videoId: 'TZyZheqEJUwC',
    poster: 'https://stream-image.byteark.com/image/video-cover-480p/7/K/7KPloVWgN.png',
  }]
};
</script>

1. Include stylesheet in your project

// Inside your main SCSS file
@import '~@byteark/byteark-player-vue/dist/@byteark/byteark-player-vue.css';

// Or inside the component
<style lang="scss" scoped>
@import '~@byteark/byteark-player-vue/dist/@byteark/byteark-player-vue.css';
</style>

In case that you want to display videos inside a fix-sized container, use fill layout mode by passing fill: true in the player options.

playerOptions: {
  ...options,
  fill: true,
},

ByteArkPlayerContainer Props

Following properties are the properties that can be updated to the ByteArkPlayerContainer.

Name	Type	Default	Description
options	ByteArkPlayerOptions	-	An options pass to ByteArk Player (See ByteArk Player Options Object)
customClass	String	-	Add custom css class to ByteArkPlayerContainer component
lazyload	Boolean	-	The player loads its asset files once it got rendered on the webpage. By passing this prop, the player then loads its asset files once the user clicked on the player instead.
playerEndpoint	String	-	Endpoint to the video player (without version part).
playerSlugId	String	-	SlugId of player created via api player server service
playerVersion	String	v2	Custom version of the player.
playerJsFileName	String		File name of player's JS.
playerCssFileName	String		File name of player's CSS.
setupPlayerFunction	(options: ByteArkPlayerOptions, loadScriptOrStyleFunction: (id: string, url: string, type: 'script' | 'style') => Promise	-	This function call to before create player function
createPlayerFunction	(node: HTMLMediaElement, options: ByteArkPlayerOptions, onReady: () => void) => ByteArkPlayer	-	This function should return a VideoJS's player instance.
onPlayerLoaded	() => void	-	Callback function to be called when loaded player's resources.
onPlayerLoadError	(error: ByteArkPlayerContainerError, originalError: ByteArkPlayerError | unknown) => void	-	Callback function to be called when there're an error about loading player.
onPlayerSetup	() => void	-	Callback function to be called when player is setup.
onPlayerSetupError	(error: ByteArkPlayerContainerError, originalError: ByteArkPlayerError | unknown) => void	-	Callback function to be called when there're an error when setup player.
onPlayerCreated	(player: ByteArkPlayer) => void	-	Callback function to be called when a player instance is created.
onPlayerReady	(player: ByteArkPlayer) => void	-	Callback function to be called when a player instance is ready.

ByteArk Player Options

You have to pass options object to ByteArkPlayerContainer in order to create ByteArk Player instance.

Name	Type	Default	Description
autoplay	Boolean/String	-	Autoplay the video after the player is created. (Seee VideoJS's autoplay options)
aspectRatio	String	-	Use with fluid layout mode, to inform expected video's aspect ratio
controls	Boolean	true	Show the controls bar.
fill	Boolean	-	Use fill layout mode.
fluid	Boolean	-	Use fluid layout mode.
loop	Boolean	-	Replay the video after ending
muted	Boolean	-	Play the video without sounds.
playbackRate	Number	1.0	Playback speed. 1.0 means original speed.
playsinline	Boolean	true	Should be true so custom controls available on all platforms, including iOS.
poster	String	-	Image to show before playing the video.
preload	String	-	Preload the video before playing. (none / metadata / auto)
responsive	Boolean	-	Auto show/hide controls depending on the screen size.
seekButtons	Boolean	-	Show 10 seconds seek buttons and allow double-tap to seek on mobile.
sources	Array	-	Array of video source object to be played. (See Source Object)
volume	Number	-	Video's volume between 0 and 1.
plugins	Array	-	Videojs's plugins

You can also use other props not listed here, but appear as VideoJS's options. However, changing props will not effective after the player is created.

Source Object

The sources object has 2 required fields.

Name	Type	Required	Description
src	String	true	URL to the video.
type	String	true	Video content type.
title	String	false	Video title to display on the player.
videoId	String	false	Video's ID, usually used by analytical applications.
poster	String	false	Image to show before playing the video.

To provide multiple version of sources, you can use array of source objects.

Event Handling

ByteArkPlayerContainer emits events that you can use to trigger your custom functions.

Event Name	Callback Parameters	Trigger Condition
loaded	-	When loaded player's resources.
loaderror	(error: ByteArkPlayerContainerError, originalError: ByteArkPlayerError | unknown): void	When there're an error about loading player's resources.
setup	-	When player is setup.
setuperror	(error: ByteArkPlayerContainerError, originalError: ByteArkPlayerError | unknown): void	When there're an error when setup player.
created	(player: ByteArkPlayer)	When the player instance was created.
ready	(player: ByteArkPlayer)	When the player instance was ready to play.
firstplay	(player: ByteArkPlayer)	When the video played for the first time.
play	(player: ByteArkPlayer, currentTime: number)	When the video played or the user hit play. (Value of currentTime is a number in seconds)
pause	(player: ByteArkPlayer, currentTime: number)	When the video played or the user hit pause. (Value of currentTime is a number in seconds)
ended	(player: ByteArkPlayer)	When the video ended.
timeupdate	(player: ByteArkPlayer, currentTime: number)	When the current playback time changed. (Value of currentTime is a number in seconds)
seeking	(player: ByteArkPlayer, currentTime: number)	When the the user seeked the video. (Value of currentTime is a number in seconds)
seeked	(player: ByteArkPlayer, currentTime: number)	When the the user seeked the video. (Value of currentTime is a number in seconds)
waiting	(player: ByteArkPlayer)	When the player is waiting for the video.
stalled	(player: ByteArkPlayer)	When the player is waiting for the video.
fullscreenchange	(player: ByteArkPlayer, isFullscreen: boolean)	When the user entered or exited the full screen mode. (Value of isFullscreen is True or False)
volumechange	(player: ByteArkPlayer, volume: number)	When the user adjusted the volume. (Value of volume is between 0 - 1)
ratechange	(player: ByteArkPlayer, playbackSpeed: number)	When the user adjusted the playback speed. (Value of playbackSpeed is a number)
enterpictureinpicture	(player: ByteArkPlayer)	When the user entered Picture-in-Picture mode.
leavepictureinpicture	(player: ByteArkPlayer)	When the user exited Picture-in-Picture mode.
error	(error: ByteArkPlayerError | MediaError | unknown | null)	When there was an error while loading player.

For an example of implementing these events, please see Controlling Players Section.

Advanced Usages

Controlling Players

You may access the player instance from onReady callback parameter.

<template>
  <ByteArkPlayerContainer
    @ready="onReady"
    @firstplay="onFirstPlay"
    @play="onPlay"
    @pause="onPause"
    @ended="onVideoEnded"
    @timeupdate="onTimeUpdated"
    @seeking="onVideoSeeking"
    @seeked="onVideoSeeked"
    @fullscreenchange="onToggleFullScreen"
    @volumechange="onVolumeChange"
    @ratechange="onPlaybackSpeedChanged"
    @enterpictureinpicture="onPIPEntered"
    @leavepictureinpicture="onPIPExited"
    :options="playerOptions" />
  <button @click="player.value?.play()">Play</button>
  <button @click="player.value?.pause()">Pause</button>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import ByteArkPlayerContainer from '@byteark/byteark-player-vue'
import type { ByteArkPlayerOptions, ByteArkPlayer } from '@byteark/byteark-player-vue'

const playerRef = ref<ByteArkPlayer | null>(null)

const playerOptions: ByteArkPlayerOptions = {
  autoplay: 'any',
  fluid: true,
  aspectRatio: '16:9',
  poster: 'https://stream-image.byteark.com/image/video-cover-480p/7/K/7KPloVWgN.png',
  sources: [{
    src: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
    type: 'application/x-mpegURL',
    title: 'Big Buck Bunny',
    videoId: 'TZyZheqEJUwC',
    poster: 'https://stream-image.byteark.com/image/video-cover-480p/7/K/7KPloVWgN.png',
  }]
}

const onReady = (player: ByteArkPlayer) => {
  // The player is ready! save player instance
  playerRef.value = player
}

const onFirstPlay = (player: ByteArkPlayer) => {
  // Do something...
}

const onPlay = (player: ByteArkPlayer, currentTime: number) => {
  // Do something...
}

const onPause = (player: ByteArkPlayer, currentTime: number) => {
  // Do something...
}

const onVideoEnded = () => {
  // Do something...
}

const onTimeUpdated = (player: ByteArkPlayer, currentTime: number) => {
  // Do something...
}

const onVideoSeeking = (player: ByteArkPlayer, currentTime: number) => {
  // Do something...
}

const onVideoSeeked = (player: ByteArkPlayer, currentTime: number) => {
  // Do something...
}

const onToggleFullScreen = (player: ByteArkPlayer, isFullscreen: boolean) => {
  // Do something...
}

const onVolumeChange = (player: ByteArkPlayer, volume: number) => {
  // Do something...
}

const onPlaybackSpeedChanged = (player: ByteArkPlayer, playbackSpeed: number) => {
  // Do something...
}

const onPIPEntered = (player: ByteArkPlayer,) => {
  // Do something...
}

const onPIPExited = (player: ByteArkPlayer,) => {
  // Do something...
}
</script>

Using VideoJS Plugins

<template>
  <ByteArkPlayerContainer
    @ready="onReady"
    :options="playerOptions"
  />
</template>

<script setup lang="ts">
import ByteArkPlayerContainer from '@byteark/byteark-player-vue'
import type { ByteArkPlayerOptions, ByteArkPlayer } from '@byteark/byteark-player-vue'

const playerOptions: ByteArkPlayerOptions = {
  autoplay: 'any',
  fluid: true,
  aspectRatio: '16:9',
  poster: 'https://stream-image.byteark.com/image/video-cover-480p/7/K/7KPloVWgN.png',
  sources: [{
    src: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
    type: 'application/x-mpegURL',
    title: 'Big Buck Bunny',
    videoId: 'TZyZheqEJUwC',
    poster: 'https://stream-image.byteark.com/image/video-cover-480p/7/K/7KPloVWgN.png',
  }]
}

const onReady = (player: ByteArkPlayer) => {
  // The player is ready! Initialize plugins here.
  player.somePlugin()
}
</script>

Request Media/Encryption with credentials

<template>
  <ByteArkPlayerContainer
    :options="playerOptions"
  />
</template>

<script setup lang="ts">
import ByteArkPlayerContainer from '@byteark/byteark-player-vue'
import type { ByteArkPlayerOptions, ByteArkPlayer } from '@byteark/byteark-player-vue'

const playerOptions: ByteArkPlayerOptions = {
  autoplay: 'any',
  fluid: true,
  aspectRatio: '16:9',
  poster: 'https://stream-image.byteark.com/image/video-cover-480p/7/K/7KPloVWgN.png',
  sources: [{
    src: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
    type: 'application/x-mpegURL',
    title: 'Big Buck Bunny',
    videoId: 'TZyZheqEJUwC',
    poster: 'https://stream-image.byteark.com/image/video-cover-480p/7/K/7KPloVWgN.png',
  }],
  html5: {
    hlsjs: {
      xhrSetup: function(xhr, url) {
        xhr.withCredentials = true;
      },
    },
  },
}
</script>

License

MIT © ByteArk Co. Ltd.

Changelog

4.1.1 (2024-11-12)

Bug Fixes

• fixed typo in example (32d5b0b)
• fixed undefined class name (a808f0f)

Code Refactoring

• refactor code base from javascript to typescript
• change code style to vue.js composition api

Build System

• change build tools to vite
• change to pnpm

Documentation

• update readme.md