@viostream/viostream-player-vue

viostream-player-vue

Vue 3 SDK for the Viostream video player. Embed, control, and listen to player events with full TypeScript support.

Requirements

• Vue 3.3+
• A Viostream account key (found on the Settings > General page in Viostream)

Installation

npm install @viostream/viostream-player-vue

Quick Start

Component

Drop a <ViostreamPlayer> into any Vue component. The SDK loads the Viostream script automatically.

<script setup lang="ts">
import { ViostreamPlayer } from '@viostream/viostream-player-vue';
</script>

<template>
  <ViostreamPlayer
    account-key="vc-100100100"
    public-key="nhedxonrxsyfee"
    :display-title="true"
    :sharing="true"
    @play="console.log('playing')"
  />
</template>

Headless / Programmatic

Use createViostreamPlayer when you need full control without a component:

import { createViostreamPlayer } from '@viostream/viostream-player-vue';

const player = await createViostreamPlayer({
  accountKey: 'vc-100100100',
  publicKey: 'nhedxonrxsyfee',
  target: 'my-video-div', // element id or HTMLElement
  options: { displayTitle: true }
});

player.play();

<ViostreamPlayer> Component

Props

Required

Embed Options

All embed options are optional and passed directly to the Viostream embed API.

Events

Other Props

Slots

Getting the Player Instance

Use @player-ready to get a reference to the player for programmatic control:

<script setup lang="ts">
import { ref } from 'vue';
import { ViostreamPlayer } from '@viostream/viostream-player-vue';
import type { ViostreamPlayerInstance } from '@viostream/viostream-player-vue';

const player = ref<ViostreamPlayerInstance>();
</script>

<template>
  <ViostreamPlayer
    account-key="vc-100100100"
    public-key="nhedxonrxsyfee"
    @player-ready="(p) => (player = p)"
  />

  <button @click="player?.play()">Play</button>
  <button @click="player?.pause()">Pause</button>
</template>

Custom Loading and Error States

Use slots to replace the default loading/error UI:

<ViostreamPlayer
  account-key="vc-100100100"
  public-key="nhedxonrxsyfee"
>
  <template #loading>
    <p>Loading video...</p>
  </template>

  <template #error="{ message }">
    <div class="my-error">Something went wrong: {{ message }}</div>
  </template>
</ViostreamPlayer>

Cleanup

The player is destroyed automatically when the component unmounts. All event listeners are cleaned up and the player iframe is removed from the DOM.

createViostreamPlayer()

For use outside of Vue components or when you need full lifecycle control.

import { createViostreamPlayer } from '@viostream/viostream-player-vue';
import type { CreateViostreamPlayerOptions } from '@viostream/viostream-player-vue';

const player = await createViostreamPlayer({
  accountKey: 'vc-100100100',
  publicKey: 'nhedxonrxsyfee',
  target: 'my-video-div',       // element id (string) or HTMLElement
  options: {
    displayTitle: true,
    sharing: true,
    speedSelector: true
  }
});

Options

Player Instance API

Both the component (via @player-ready) and createViostreamPlayer() provide a ViostreamPlayerInstance with the following methods.

Playback Controls

player.play();
player.pause();
player.mute();
player.unmute();
player.setVolume(0.5);          // 0 to 1
player.setLoop(true);
player.setCurrentTime(30);      // seek to 30 seconds
player.setCurrentTime(30, true); // seek and auto-play
player.reload();                // reload the player
player.reload({ key: 'value' }); // reload with new settings

Getters (Promise-based)

All getters return promises. The SDK converts the underlying callback-based API to async/await.

const volume    = await player.getVolume();          // number (0-1)
const loop      = await player.getLoop();            // boolean
const time      = await player.getCurrentTime();     // number (seconds)
const paused    = await player.getPaused();          // boolean
const duration  = await player.getDuration();        // number (seconds)
const muted     = await player.getMuted();           // boolean
const ratio     = await player.getAspectRatio();     // number
const height    = await player.getHeight();          // number (pixels)

Events

Subscribe to player events with on(). It returns an unsubscribe function.

// Subscribe
const unsubscribe = player.on('timeupdate', (data) => {
  console.log(`${data.seconds}s / ${data.duration}s`);
});

// Unsubscribe later
unsubscribe();

// Or use off() directly
const handler = () => console.log('paused');
player.on('pause', handler);
player.off('pause', handler);

Available Events

Custom event names are also accepted via the string index signature:

player.on('my-custom-event', (data) => {
  console.log(data);
});

Destroy

When using createViostreamPlayer(), you are responsible for cleanup:

player.destroy();

After calling destroy():

• All event listeners are removed.
• The player iframe is removed from the DOM.
• Getter calls will reject with "Player has been destroyed".

TypeScript

Every export is fully typed. Import types alongside runtime exports:

import { ViostreamPlayer, createViostreamPlayer } from '@viostream/viostream-player-vue';
import type {
  ViostreamPlayerInstance,
  ViostreamPlayerProps,
  ViostreamPlayerEventProps,
  ViostreamEmbedOptions,
  ViostreamTimeUpdateData,
  ViostreamVolumeChangeData,
  ViostreamErrorData,
  ViostreamProgressData,
  ViostreamPlayerEventMap,
  ViostreamEventHandler,
  CreateViostreamPlayerOptions,
} from '@viostream/viostream-player-vue';

Full Example

A complete example showing the component with custom controls, event logging, and async getters:

<script setup lang="ts">
import { ref, computed } from 'vue';
import { ViostreamPlayer } from '@viostream/viostream-player-vue';
import type {
  ViostreamPlayerInstance,
  ViostreamTimeUpdateData,
} from '@viostream/viostream-player-vue';

const player = ref<ViostreamPlayerInstance>();
const currentTime = ref(0);
const duration = ref(0);
const paused = ref(true);
const log = ref<string[]>([]);

function addLog(msg: string) {
  log.value = [msg, ...log.value.slice(0, 49)];
}

function handleReady(p: ViostreamPlayerInstance) {
  player.value = p;
  p.getDuration().then((d) => (duration.value = d));
}

function handleTimeUpdate(data: ViostreamTimeUpdateData) {
  currentTime.value = data.seconds;
  duration.value = data.duration;
}

function format(s: number): string {
  return `${Math.floor(s / 60)}:${Math.floor(s % 60).toString().padStart(2, '0')}`;
}
</script>

<template>
  <ViostreamPlayer
    account-key="vc-100100100"
    public-key="nhedxonrxsyfee"
    :display-title="true"
    :sharing="true"
    :speed-selector="true"
    :hls-quality-selector="true"
    @play="() => { paused = false; addLog('play'); }"
    @pause="() => { paused = true; addLog('pause'); }"
    @ended="() => addLog('ended')"
    @time-update="handleTimeUpdate"
    @player-ready="handleReady"
  />

  <div>
    <button @click="paused ? player?.play() : player?.pause()">
      {{ paused ? 'Play' : 'Pause' }}
    </button>
    <button @click="player?.setCurrentTime(0)">Restart</button>
    <span>{{ format(currentTime) }} / {{ format(duration) }}</span>
  </div>

  <div>
    <button @click="async () => {
      const vol = await player?.getVolume();
      addLog(`volume: ${vol}`);
    }">Get Volume</button>
  </div>

  <pre>{{ log.join('\n') }}</pre>
</template>

Development

# Install dependencies
npm install

# Build (compile and bundle to dist/)
npm run build

# Type-check
npm run check

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

License

MIT