Audio Player

Audio Player is a component used to play audio files. It is based on the HTML5 audio element.

Usage

import { registerAudioPlayer } from '@vonage/vivid-api';

registerAudioPlayer('your-prefix');

<script type="module">
  import { registerAudioPlayer } from '@vonage/vivid-api';
  registerAudioPlayer('your-prefix');
</script>

<your-prefix-audio-player src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3"></your-prefix-audio-player>

<script setup lang="ts">
import { VAudioPlayer } from '@vonage/vivid-api-vue';
</script>
<template>
  <VAudioPlayer src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3" />
</template>

Audio Source

Use the src attribute to add an audio track to the Audio Player.

<script setup lang="ts">
  import {VAudioPlayer} from '@vonage/vivid-api-vue';
</script>
<template>
  <VAudioPlayer src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3" />
</template>

Current Time

Use the currentTime property change or get the Audio Player’s current time. The property accepts and returns a number representing the time in seconds.

<template>
  <VAudioPlayer ref="audioPlayer" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3" />

    <div class="container">
      <VButton label="Get current time" appearance="outlined" @click="getCurrentTime" />
      <VButton label="Skip to 30s" appearance="outlined" @click="skipTo30s" />
      <span>&nbsp; Current time: <span ref="outputSpan">0s</span></span>
    </div>

</template>

<script setup lang="ts">
import { ref } from 'vue';
import { VAudioPlayer, VButton } from '@vonage/vivid-api-vue';

const audioPlayer = ref<InstanceType<typeof VAudioPlayer> | null>(null);
const outputSpan = ref<HTMLSpanElement | null>(null);

const skipTo30s = () => {
  if (audioPlayer.value?.element && outputSpan.value) {
    audioPlayer.value.element.currentTime = 30;
    outputSpan.value.innerHTML = Math.floor(audioPlayer.value.element.currentTime) + 's';
  }
};

const getCurrentTime = () => {
  if (audioPlayer.value?.element && outputSpan.value) {
    outputSpan.value.innerHTML = Math.floor(audioPlayer.value.element.currentTime) + 's';
  }
};
</script>

<style scoped>
.container {
  display: inline-flex;
  gap: 4px;
  align-items: center;
}
</style>

<vwc-audio-player id="audio" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3"></vwc-audio-player>

<div class="container">
  <vwc-button id="current" label="Get current time" appearance="outlined"></vwc-button>
  <vwc-button id="skip" label="Skip to 30s" appearance="outlined"></vwc-button>
  <span>&nbsp; Current time: <span id="output">0s</span></span>
</div>

<script>
  const audio = document.getElementById('audio');
  const output = document.getElementById('output');

  document.getElementById('skip').addEventListener('click', () => {
    audio.currentTime = 30;
    output.innerHTML = Math.floor(audio.currentTime) + 's';
  });

  document.getElementById('current').addEventListener('click', () => {
    output.innerHTML = Math.floor(audio.currentTime) + 's';
  });
</script>

<style>
  .container {
    display: inline-flex;
    gap: 4px;
    align-items: center;
  }
</style>

Duration

The duration property indicates the duration of the loaded audio. The property is read only and returns a number representing the time in seconds.

<script setup lang="ts">
import { ref } from 'vue';
import { useTemplateRef } from 'vue';
import { VAudioPlayer, VButton } from '@vonage/vivid-api-vue';

const audioPlayer = useTemplateRef<InstanceType<typeof VAudioPlayer>>('audio-player');
const outputSpan = ref<HTMLSpanElement | null>(null);

const getDuration = () => {
if (audioPlayer.value?.element) {
outputSpan.value.innerHTML = parseInt(audioPlayer.value.element.duration.toString()) + 's';
}
};

</script>
<template>
  <VAudioPlayer ref="audio-player" notime src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3" />
  <VButton label="Get duration" appearance="outlined" @click="getDuration" />
  Duration of audio: <span ref="outputSpan"></span>
</template>

<vwc-audio-player notime id="audio" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3"></vwc-audio-player>

<vwc-button id="duration" label="Get duration" appearance="outlined"></vwc-button>
Duration of audio: <span id="output"></span>

<script>
  const audio = document.getElementById('audio');
  const output = document.getElementById('output');

  document.getElementById('duration').addEventListener('click', () => {
    output.innerHTML = parseInt(audio.duration) + 's';
  });
</script>

Duration Fallback

The duration-fallback attribute enables fallback logic to fetch and decode audio buffer for duration when metadata is missing.

<script setup lang="ts">
import { VAudioPlayer } from '@vonage/vivid-api-vue';
</script>
<template>
  <VAudioPlayer duration-fallback src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3" />
</template>

Paused

The paused property indicates if the player is currently paused or not. The property is read only and returns a boolean value.

<script setup lang="ts">
import { ref } from 'vue';
import { useTemplateRef } from 'vue';
import { VAudioPlayer, VButton } from '@vonage/vivid-api-vue';

const audioPlayer = useTemplateRef<InstanceType<typeof VAudioPlayer>>('audio-player');
const outputSpan = ref<HTMLSpanElement | null>(null);

const checkPaused = () => {
if (audioPlayer.value?.element) {
outputSpan.value.innerHTML = audioPlayer.value.element.paused ? 'Yes' : 'No';
}
};

</script>
<template>
  <VAudioPlayer ref="audio-player" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3" />
  <VButton label="Is the audio paused?" appearance="outlined" @click="checkPaused" />
  &nbsp;<span ref="outputSpan"></span>
</template>

<vwc-audio-player id="audio" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3"></vwc-audio-player>

<vwc-button id="paused" label="Is the audio paused?" appearance="outlined"></vwc-button>

<span id="output"></span>

<script>
  const audio = document.getElementById('audio');
  const output = document.getElementById('output');

  document.getElementById('paused').addEventListener('click', () => {
    output.innerHTML = audio.paused ? 'Yes' : 'No';
  });
</script>

Play and Pause Methods

The audio can be played and paused programatically using the play() and pause() methods.

<script setup lang="ts">
import { ref } from 'vue';
import { useTemplateRef } from 'vue';
import { VAudioPlayer, VButton } from '@vonage/vivid-api-vue';

const audioPlayer = useTemplateRef<InstanceType<typeof VAudioPlayer>>('audio-player');
const buttonLabel = ref('Play');

const togglePlayPause = () => {
  if (audioPlayer.value?.element) {
    if (audioPlayer.value.element.paused) {
      audioPlayer.value.play();
      buttonLabel.value = 'Pause';
    } else {
      audioPlayer.value.pause();
      buttonLabel.value = 'Play';
    }
  }
};
</script>
<template>
  <VAudioPlayer ref="audio-player" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3" />
  <VButton :label="buttonLabel" appearance="outlined" @click="togglePlayPause" />
</template>

<vwc-audio-player id="audio" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3"></vwc-audio-player>

<vwc-button id="control" label="Play" appearance="outlined"></vwc-button>

<script>
  const audio = document.getElementById('audio');
  const control = document.getElementById('control');

  control.addEventListener('click', () => {
    if (audio.paused) {
      audio.play();
      control.label = 'Pause';
    } else {
      audio.pause();
      control.label = 'Play';
    }
  });
</script>

Styles

Inline Size (Width)

By default, Audio Player’s max-inline-size is100%. You can specify a different value with setting max-inline-size on the vwc-audio-player.

<script setup lang="ts">
import { VAudioPlayer } from '@vonage/vivid-api-vue';
</script>
<template>
  <VAudioPlayer playback-rates="0.75, 1, 1.5" skip-by="5" class="audio-player" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3" />
</template>

<style scoped>
.audio-player {
  max-inline-size: 350px;
}
</style>

<vwc-audio-player playback-rates="0.75, 1, 1.5" skip-by="5" class="audio-player" src="https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_2MB_MP3.mp3"></vwc-audio-player>

<style>
  .audio-player {
    max-inline-size: 350px;
  }
</style>

API Reference

Properties

Property	Type	Description
connotation	`'accent' \| 'cta'`	Sets the color of the audio player
currentTime	`number`
disabled	`boolean`	Sets the disabled state of the audio player
duration	`number`
durationFallback	`boolean`	Enables fallback logic to fetch and decode audio buffer for duration when metadata is missing.
notime	`boolean`	Hides the time stamp
pauseButtonAriaLabel	`string`
paused	`boolean`
playButtonAriaLabel	`string`
playbackRate	`number`
playbackRates	`string`	Comma-separated string of numbers to define playback speeds
skipBackwardButtonAriaLabel	`string`
skipBy	`'0' \| '5' \| '10' \| '30'`	Allows the audio to skip back or forward
skipForwardButtonAriaLabel	`string`
sliderAriaLabel	`string`
src	`string`	Sets the audio source URL

Property	Type	Description
connotation	`'accent' \| 'cta'`	Sets the color of the audio player
currentTime (property only)	`number`
disabled	`boolean`	Sets the disabled state of the audio player
duration (property only)	`number`
duration-fallback	`boolean`	Enables fallback logic to fetch and decode audio buffer for duration when metadata is missing.
notime	`boolean`	Hides the time stamp
pause-button-aria-label	`string`
paused (property only)	`boolean`
play-button-aria-label	`string`
playbackRate (property only)	`number`
playback-rates	`string`	Comma-separated string of numbers to define playback speeds
skip-backward-aria-label	`string`
skip-by	`'0' \| '5' \| '10' \| '30'`	Allows the audio to skip back or forward
skip-forward-aria-label	`string`
slider-aria-label	`string`
src	`string`	Sets the audio source URL

Events

Name	Type	Description
pause	`CustomEvent<undefined>`	Fires when the audio playback is paused.
play	`CustomEvent<undefined>`	Fires when the audio playback is started.

Name	Type	Description
pause	`CustomEvent<undefined>`	Fires when the audio playback is paused.
play	`CustomEvent<undefined>`	Fires when the audio playback is started.

Methods

Name	Params	Returns	Description
pause		`void`
play		`void`