Aqua Basis

The AqVoicePlayer component enhances the user experience by providing intuitive controls for playing audio content, such as voice notes or recorded clips. It supports core features like play, pause, progress tracking, and duration display.

The AqVoicePlayer component is useful for integrating short audio interactions into an interface, allowing users to consume content quickly without leaving the application.

<aq-voice-player
  width="500px"
  audio-source="<https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3>"
  reset-on-end
>
</aq-voice-player>

Props and Attributes

Prop / Attr	Type	Default	Description
`audioSource`	`string	source`	`''`
`format`	`string[]`	`['mp3','wav','ogg']`	Accepted audio formats.
`resetOnEnd`	`boolean`	`false`	Resets progress to `0` when playback ends.
`showCurrentTime`	`boolean`	`true`	Displays the current playback time.
`isAutoPlay`	`boolean`	`false`	Automatically plays on load.

PlayGround

You can interact with the component and experiment with its attributes and properties directly in this playground.

In the Code tab, the generated code snippet is available.

In addition to the interactive examples in this documentation, you can explore the full playground with all supported options and advanced configurations at the following link:

👉 Open full playground

https://aqua-ds-playground.masivianlabs.com/doc-storybook/index.html?path=/story/components-actions-aqvoiceplayer--default&nav=0

<aside> ⚠️

Important: The code shown is in Web Component format. If you are using a specific framework (Vue, React, Angular), you must adapt it to the framework’s conventions before using it.

</aside>

Events

Event	Description	Emitted when	React	Angular	Vue	Vanilla JS
`audioPlay`	Provides the current playback time.	Audio starts playing.	`<AqAudioPlayer onAudioPlay={(e) => ...} />`	`(audioPlay)="onAudioPlay($event)"`	`@audioPlay="onAudioPlay"`	`el.addEventListener('audioPlay', e => ...)`
`audioPause`	Provides the current playback time.	Audio is paused.	`<AqAudioPlayer onAudioPause={(e) => ...} />`	`(audioPause)="onAudioPause($event)"`	`@audioPause="onAudioPause"`	`el.addEventListener('audioPause', e => ...)`
`audioEnded`	Provides the final playback time.	Audio has finished playing.	`<AqAudioPlayer onAudioEnded={(e) => ...} />`	`(audioEnded)="onAudioEnded($event)"`	`@audioEnded="onAudioEnded"`	`el.addEventListener('audioEnded', e => ...)`
`audioError`	Provides the error code.	An error occurs during audio playback.	`<AqAudioPlayer onAudioError={(e) => ...} />`	`(audioError)="onAudioError($event)"`	`@audioError="onAudioError"`	`el.addEventListener('audioError', e => ...)`
`loadedAudio`	Provides the duration of the audio.	Audio metadata is loaded.	`<AqAudioPlayer onLoadedAudio={(e) => ...} />`	`(loadedAudio)="onLoadedAudio($event)"`	`@loadedAudio="onLoadedAudio"`	`el.addEventListener('loadedAudio', e => ...)`
`positionChange`	Provides the current playback time.	User seeks or playback position changes.	`<AqAudioPlayer onPositionChange={(e) => ...} />`	`(positionChange)="onPositionChange($event)"`	`@positionChange="onPositionChange"`	`el.addEventListener('positionChange', e => ...)`

Event Types

Event	React/Angular/Vue
`audioPlay`	`(e:CustomEvent<{currentTime:number}>)`
`audioPause`	`(e:CustomEvent<{currentTime:number}>)`
`audioEnded`	`(e:CustomEvent<{currentTime:number}>)`
`audioError`	`(e:CustomEvent<{currentTime:number}>)`
`loadedAudio`	`(e:CustomEvent<{currentTime:number}>)`
`positionChange`	`(e:CustomEvent<{currentTime:number}>)`

Component API

| --- | --- | --- | --- | --- | --- | --- | --- |

In Frameworks

Web Components

<aq-voice-player
  id="aq-voice-player-1"
  label="This is a label"
  is-required
  info="This is a tooltip"
  tooltip-width="90px"
  helper-text="This is a helper text"
  audio-source="<https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3>"
>
</aq-voice-player>
<script>
  const player = document.getElementById('aq-voice-player-1');

  // Fired when playback starts
  player.addEventListener('audioPlay', (event) => {
    console.log('▶️ Play at:', event.detail.currentTime);
  });
  
  // Voice player API
  document.getElementById("playPause").addEventListener("click", () => {
    player.audioPlayPause();
  });
</script>

Vue

<script lang="ts">
import { AqVoicePlayer, AqButton } from '@aqua-ds/vue';
import { defineComponent, ref, onMounted } from 'vue';

export default defineComponent({
  components: {
    AqVoicePlayer,
    AqButton,
  },
  setup() {
    const aqVoicePlayerRef = ref();

    // 🔹 Voice Player API
    const playPause = async () => {
      if (aqVoicePlayerRef.value) {
        await aqVoicePlayerRef.value.audioPlayPause();
      }
    };

    return {
      aqVoicePlayerRef,
      playPause,
      getCurrentTime,
      getDuration
    };
  }
});
</script>

<template>
  <div class="section">
    <div class="section-title">VoicePlayer</div>
    <div class="components">
      <aq-voice-player
        ref="aqVoicePlayerRef"
        label="This is a label"
        is-required
        info="This is a tooltip"
        tooltip-width="90px"
        helper-text="This is a helper text"
        audio-source="<https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3>"
        @audioPlay="(e: CustomEvent) => console.log('▶️ Audio play:', e.detail)"
        @audioPause="(e: CustomEvent) => console.log('⏸️ Audio pause:', e.detail)"
        @audioEnded="(e: CustomEvent) => console.log('🏁 Audio ended:', e.detail)"
      >
      </aq-voice-player>

      <div class="flex gap-2 mt-4">
        <aq-button @click="playPause()" is-outline type="button">Play / Pause</aq-button>
        <aq-button @click="getCurrentTime()" is-outline type="button">Get Current Time</aq-button>
        <aq-button @click="getDuration()" is-outline type="button">Get Duration</aq-button>
      </div>
    </div>
  </div>
</template>

React

import { AqVoicePlayer, AqButton } from '@aqua-ds/react';
import { useRef } from 'react';

export const VoicePlayerSet = () => {
  const aqVoicePlayerRef = useRef<any>(null);

  // 🔹 Component API
  const playPause = async () => {
    if (aqVoicePlayerRef.current !== null) {
      await aqVoicePlayerRef.current.audioPlayPause();
    }
  };

  return (
    <div className="section">
      <div className="section-title">Voice Player</div>
      <div className="components">
        <AqVoicePlayer
          ref={aqVoicePlayerRef}
          label="This is a label"
          is-required
          info="This is a tooltip"
          tooltip-width="90px"
          helper-text="This is a helper text"
          audio-source="<https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3>"
          onAudioPlay={(e: CustomEvent) => console.log('▶️ Audio play:', e.detail)}
          onAudioPause={(e: CustomEvent) => console.log('⏸️ Audio pause:', e.detail)}
          onAudioEnded={(e: CustomEvent) => console.log('🏁 Audio ended:', e.detail)}
        >
        </AqVoicePlayer>

        <div className="flex gap-2 mt-4">
          <AqButton onClick={async () => await playPause()} is-outline type="button">
            Play / Pause
          </AqButton>
          <AqButton onClick={async () => await getCurrentTime()} is-outline type="button">
            Get Current Time
          </AqButton>
          <AqButton onClick={async () => await getDuration()} is-outline type="button">
            Get Duration
          </AqButton>
        </div>
      </div>
    </div>
  );
};