For Quasar CLI Vite apps, use the App Extension when possible:

quasar ext add @quasar/qmediaplayer

The App Extension registers QMediaPlayer for the app and imports the component styles. Install the UI package directly only when you want to register the component manually, use it outside the App Extension flow, or build a custom integration.

No. QMediaPlayer v3 targets Quasar CLI Vite 3 and requires @quasar/app-vite >=3.0.0-rc.3. If your app still uses @quasar/app-webpack, migrate the app to Quasar CLI Vite before installing QMediaPlayer v3.

The App Extension adds the stylesheet for you.

If you install the UI package directly, import the stylesheet in your boot file or app entry:

import '@quasar/quasar-ui-qmediaplayer/dist/index.css'

Quasar CLI projects can also centralize the stylesheet in quasar.config.ts:

// Note: using ~ tells Quasar the file resides in node_modules
css: [
  "app.scss",
  "~@quasar/quasar-ui-qmediaplayer/dist/index.css",
],

Yes. After the App Extension is installed, run:

quasar describe QMediaPlayer

The same generated API is shown on the Using QMediaPlayer page.

Use source when you have exactly one media URL:

<q-media-player type="video" source="/media/demo.mp4" />

Use sources when you want the browser to choose between multiple formats:

<q-media-player
  type="video"
  :sources="[
    { src: '/media/demo.webm', type: 'video/webm' },
    { src: '/media/demo.mp4', type: 'video/mp4' },
  ]"
/>

If source is set, it is applied directly to the media element and the sources array is ignored.

Browsers heavily restrict autoplay, especially when audio is enabled. If you use autoplay, also use muted for the most reliable behavior:

<q-media-player type="video" source="/media/demo.mp4" autoplay muted />

For anything that must play with sound, wait for the ready event and trigger playback from a user action such as a click or tap.

Yes. Set type="audio" and provide an audio source.

By default, QMediaPlayer may still use a video element for audio playback because it works better when dynamically switching between audio and video in the same component. If you need a real audio element, use no-video:

<q-media-player type="audio" source="/media/song.mp3" no-video />

QMediaPlayer wraps native HTML5 media playback, so it cannot play YouTube or Vimeo iframe embed URLs through its source or sources props. Use Quasar’s QVideo for embedded providers and keep QMediaPlayer for direct native audio/video sources.

If the browser can play the source through an HTML5 media element, QMediaPlayer can usually provide the UI around it.

Use native-controls when you need the browser’s built-in controls for platform behavior, accessibility testing, or debugging a media playback issue.

For a cohesive Quasar UI, leave native-controls off and use QMediaPlayer’s controls.

mobile-mode disables hover-driven control visibility. Instead, the user taps or clicks the video area to show and hide controls. This is useful on touch devices and on layouts where hover behavior feels too busy.

<q-media-player type="video" source="/media/demo.mp4" mobile-mode />

Use bottom-controls. This moves controls below the video area instead of overlaying them.

<q-media-player type="video" source="/media/demo.mp4" bottom-controls />

This is a good fit when captions, important visual content, or custom overlays need the full video surface.

Use dense for smaller controls. You can combine it with bottom-controls, hidden volume controls, or custom styles for tight card and sidebar layouts.

<q-media-player type="audio" source="/media/song.mp3" dense hide-volume-slider />

Use the tracks prop with WebVTT files. Each track should include src, kind, srclang, and label.

<q-media-player
  type="video"
  source="/media/demo.mp4"
  :tracks="[
    { src: '/media/demo-en.vtt', kind: 'subtitles', srclang: 'en', label: 'English' },
    { src: '/media/demo-fr.vtt', kind: 'subtitles', srclang: 'fr', label: 'French' },
  ]"
/>

Use track-language when you want a default track selected by label:

<q-media-player type="video" source="/media/demo.mp4" :tracks="tracks" track-language="French" />

Check that the track file is valid WebVTT, that the server returns it with a usable MIME type, and that the track label matches track-language exactly when selecting a default language.

For remote media and remote tracks, CORS can also matter. If needed, set cross-origin="anonymous" and make sure the media server allows it.

QMediaPlayer follows the active Quasar language and icon set. When the Quasar language or icon set changes, QMediaPlayer updates its player labels and icons as well.

If a language or icon set is missing, open an issue or PR so it can be added.

Yes. QMediaPlayer exposes slots for common control areas, including controls, play, volume, volumeSlider, settings, settingsMenu, fullscreen, displayTime, durationTime, positionSlider, spinner, bigPlayButton, overlay, and errorWindow.

Use slots when you need a branded experience but still want QMediaPlayer to manage the media element, timing, playback state, and events.

Fullscreen behavior is controlled by the browser and operating system. Some mobile browsers, especially iOS Safari, restrict or reshape fullscreen behavior for HTML5 video.

If fullscreen is unavailable or undesirable for your target device, hide the fullscreen button:

<q-media-player type="video" source="/media/demo.mp4" hide-fullscreen-btn />

Remote media can fail because of network availability, CORS, codec support, or server MIME types. Try the same URL directly in the browser first, then test with a local file or a known-good MP4/MP3 source.

The documentation examples use remote media, so they can occasionally load slowly or fail depending on network location.

Use GitHub Issues for bugs and feature requests. Use GitHub Discussions for broader questions, RFCs, or implementation discussion.