vue-aliplayer-v2/README.en-US.md

vue-aliplayer-v2

English | 简体中文

A Vue 3 wrapper for the Aliyun Web Player Aliplayer SDK. v2 is rebuilt with Vue 3, TypeScript, and Vite. It supports URL playback, VID + PlayAuth, STS credentials, live streams, low-latency FLV, automatic format inference, License injection, extension component scripts, multiple player instances, and common player instance methods.

v2 no longer supports Vue 2. For Vue 2 projects, keep using vue-aliplayer-v2@1.x.

Demo

• Project demo: https://langyuxiansheng.github.io/vue-aliplayer-v2/
• Official Aliplayer demo: https://player.alicdn.com/aliplayer/index.html
• Official integration guide: https://help.aliyun.com/zh/vod/developer-reference/integration

Features

• Vue 3 component and plugin installation via app.use(VueAliplayerV2, options).
• TypeScript exports for props, options, events, player instances, and exposed ref methods.
• Loads Aliyun imp-web-player SDK 2.37.0 by default, with custom CSS/JS URL support.
• Supports source URLs, options.source, VID + PlayAuth, and STS credential playback.
• Infers mp4, m3u8, flv, mp3, and rtmp formats from source URLs.
• Adds an optional low-latency preset for FLV live streams.
• Supports License config for newer Aliplayer Web SDK versions.
• Supports multiple player instances while loading the SDK assets only once.
• Loads extra component scripts before player initialization for playlists, watermarks, marquees, and other Aliplayer extensions.
• Provides an optional blocker for known tracking requests.

Installation

npm install vue-aliplayer-v2

yarn add vue-aliplayer-v2

pnpm add vue-aliplayer-v2

Quick Start

Global Registration

import { createApp } from 'vue';
import App from './App.vue';
import VueAliplayerV2 from 'vue-aliplayer-v2';

const app = createApp(App);

app.use(VueAliplayerV2, {
    sdkVersion: '2.37.0'
});

app.mount('#app');

<template>
    <VueAliplayerV2
        source="//player.alicdn.com/video/aliyunmedia.mp4"
        :options="{ autoplay: true, useH5Prism: true }"
    />
</template>

Local Import

<template>
    <VueAliplayerV2
        ref="playerRef"
        :source="source"
        :options="options"
        :license="license"
        low-latency
        @ready="handleReady"
        @error="handleError"
        @sdk-error="handleSdkError"
    />
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import VueAliplayerV2, {
    type AliplayerLicense,
    type AliplayerOptions,
    type VueAliplayerV2Expose
} from 'vue-aliplayer-v2';

const playerRef = ref<VueAliplayerV2Expose | null>(null);

const source = ref('//player.alicdn.com/video/aliyunmedia.mp4');

const license = ref<AliplayerLicense | null>({
    domain: 'example.com',
    key: 'your-license-key'
});

const options = reactive<AliplayerOptions>({
    autoplay: true,
    isLive: false,
    useH5Prism: true,
    playsinline: true,
    width: '100%',
    height: '420px',
    controlBarVisibility: 'hover'
});

function handleReady() {
    playerRef.value?.play();
}

function handleError(error: unknown) {
    console.log('player error', error);
}

function handleSdkError(error: Error) {
    console.log('sdk load error', error.message);
}
</script>

Plugin Options

app.use(VueAliplayerV2, options) sets global defaults. Component props with the same names override these defaults per instance.

app.use(VueAliplayerV2, {
    sdkVersion: '2.37.0',
    cssLink: 'https://g.alicdn.com/apsara-media-box/imp-web-player/2.37.0/skins/default/aliplayer-min.css',
    scriptSrc: 'https://g.alicdn.com/apsara-media-box/imp-web-player/2.37.0/aliplayer-min.js',
    componentScripts: ['/aliplayer-components/watermark.js'],
    disableTracking: false,
    trackingUrlPatterns: ['newplayer/track']
});

Name	Type	Default	Description
sdkVersion	string	2.37.0	Aliyun Web Player SDK version. Used to generate official asset URLs when cssLink or scriptSrc is not provided.
cssLink	string	Official 2.37.0 CSS	Custom Aliplayer CSS URL.
scriptSrc	string	Official 2.37.0 JS	Custom Aliplayer JS URL.
componentScripts	string[]	[]	Extra component or business extension script URLs.
disableTracking	boolean	false	Enables the known Aliplayer tracking request blocker.
trackingUrlPatterns	Array<string | RegExp>	['newplayer/track']	URL fragments or regular expressions to block.

Props

Name	Type	Default	Description
source	string | null	null	Playback source URL. It has priority over options.source. Same-format changes prefer loadByUrl; cross-format changes recreate the player.
options	AliplayerOptions | null	null	Raw Aliplayer initialization options. The component adds id, source, license, format, and low-latency defaults when needed.
license	AliplayerLicense | null	null	Aliplayer License config. It has priority over options.license.
autoFormat	boolean	true	Infers format from source.
lowLatency	boolean	false	Enables the low-latency FLV live preset.
normalizeSourceUrl	boolean	true	Runs encodeURI on source URLs to handle Chinese characters, spaces, and other unencoded characters.
forbidFastForward	boolean	false	Prevents drag-to-fast-forward behavior.
sdkVersion	string	Global option	Overrides the SDK version for the current component.
cssLink	string	Global option	Overrides the CSS URL for the current component.
scriptSrc	string	Global option	Overrides the JS URL for the current component.
componentScripts	string[]	Global option	Extra scripts to load before initializing the current component.
disableTracking	boolean	Global option	Enables tracking request blocking for the current component.
trackingUrlPatterns	Array<string | RegExp>	Global option	Tracking URL rules for the current component.

Common AliplayerOptions Fields

options is passed through to the Aliplayer SDK, so official SDK fields can still be used. The package declares the common fields below and keeps an index signature for additional official or business fields.

Name	Type	Description
source	string	Playback source URL.
width	string	Player width, for example 100%.
height	string	Player height, for example 420px.
autoplay	boolean	Whether to autoplay.
isLive	boolean	Whether the stream is live.
format	string	Source format, such as mp4, m3u8, or flv.
license	AliplayerLicense	Aliplayer License config.
vid	string	VOD video ID.
playauth	string	VOD PlayAuth token.
authTimeout	number	Playback URL validity duration in seconds.
region	string	STS media region, for example cn-shanghai.
accessKeyId	string	Temporary STS AccessKey ID.
accessKeySecret	string	Temporary STS AccessKey Secret.
securityToken	string	STS security token.
components	unknown[]	Aliplayer custom component config.
enableStashBufferForFlv	boolean	Whether FLV stash buffer is enabled.
stashInitialSizeForFlv	number	FLV initial stash size.
rtsVersion	string	RTS SDK version.

Events

The component forwards common Aliplayer events and adds sdk-error.

Event	Payload	Description
ready	unknown	Player initialization completed.
play	unknown	Playback started.
pause	unknown	Playback paused.
canplay	unknown	Media can play.
playing	unknown	Media is playing.
ended	unknown	Playback ended.
liveStreamStop	unknown	Live stream stopped.
onM3u8Retry	unknown	M3U8 retry event.
hideBar	unknown	Control bar hidden.
showBar	unknown	Control bar shown.
waiting	unknown	Playback is waiting.
timeupdate	unknown	Playback time updated.
snapshoted	unknown	Snapshot completed.
requestFullScreen	unknown	Fullscreen requested.
cancelFullScreen	unknown	Fullscreen canceled.
error	unknown	Runtime player error.
startSeek	unknown	Seek started.
completeSeek	unknown	Seek completed.
sdk-error	Error	SDK CSS, JS, or extension script failed to load.

Ref Methods

Use ref<VueAliplayerV2Expose | null> to access exposed methods.

playerRef.value?.play();
playerRef.value?.pause();
playerRef.value?.seek(30);
playerRef.value?.setVolume(0.8);
playerRef.value?.loadByUrl('//player.alicdn.com/video/aliyunmedia.mp4');
playerRef.value?.requestFullScreen();
playerRef.value?.retry();

Method	Description
getPlayer()	Returns the underlying Aliplayer instance.
init()	Loads the SDK and initializes the player.
initPlayer()	Creates a player instance with current props/options.
reload(nextSource?)	Reloads the player, optionally with a new source.
retry(nextSource?)	Business-friendly retry method after playback failure.
play()	Starts playback.
pause()	Pauses playback.
replay()	Replays from the beginning.
seek(time)	Seeks to a time in seconds.
getCurrentTime()	Returns current playback time.
getDuration()	Returns media duration.
getVolume()	Returns current volume.
setVolume(volume)	Sets volume.
loadByUrl(url, time?)	Switches source by URL.
replayByVidAndPlayAuth(vid, playauth)	Replays with VID + PlayAuth.
replayByVidAndAuthInfo(...)	Replays with MPS auth info.
setPlayerSize(width, height)	Sets player size.
setSpeed(speed)	Sets playback speed.
setSanpshotProperties(width, height, rate)	Sets snapshot options. The method name follows the SDK spelling.
requestFullScreen()	Enters fullscreen.
cancelFullScreen()	Exits fullscreen.
getIsFullScreen()	Returns fullscreen state.
getStatus()	Returns player status.
setLiveTimeRange(beginTime, endTime)	Sets the playable live time-shift range.
setRotate(rotate)	Sets video rotation.
getRotate()	Returns video rotation.
setImage(image)	Sets video mirror mode.
dispose()	Disposes the player.
setCover(cover)	Sets cover image.
setProgressMarkers(markers)	Sets progress markers.
setPreviewTime(time)	Sets preview duration.
getPreviewTime()	Returns preview duration.
isPreview()	Returns whether the player is in preview mode.
off(eventName, handler)	Removes a listener from the underlying player.

Usage Examples

URL Playback

<VueAliplayerV2
    source="//player.alicdn.com/video/aliyunmedia.mp4"
    :options="{
        autoplay: true,
        useH5Prism: true,
        width: '100%',
        height: '420px'
    }"
/>

VID + PlayAuth

<VueAliplayerV2
    :options="{
        vid: '<your-video-id>',
        playauth: '<your-playauth>',
        authTimeout: 7200,
        width: '100%',
        height: '420px'
    }"
/>

VID + PlayAuth is an initialization mode, so source is not required. To switch after the player has been created, call:

playerRef.value?.replayByVidAndPlayAuth(vid, playauth);

STS

<VueAliplayerV2
    :options="{
        vid: '<your-video-id>',
        region: 'cn-shanghai',
        accessKeyId: '<temporary-access-key-id>',
        accessKeySecret: '<temporary-access-key-secret>',
        securityToken: '<temporary-security-token>',
        width: '100%',
        height: '420px'
    }"
/>

FLV Live and Low Latency

<VueAliplayerV2
    source="//example.com/live.flv"
    low-latency
    :options="{
        isLive: true,
        autoplay: true,
        width: '100%',
        height: '420px'
    }"
/>

When low-latency is enabled and the current source is FLV with options.isLive = true, the component adds:

{
    enableStashBufferForFlv: false,
    stashInitialSizeForFlv: 128
}

You can override these values directly in options.

Live Time Shift

playerRef.value?.setLiveTimeRange('2026/05/23 10:00:00', '2026/05/23 12:00:00');

You can also pass official time-shift options during initialization:

<VueAliplayerV2
    source="//example.com/live.m3u8"
    :options="{
        isLive: true,
        liveStartTime: '2026/05/23 10:00:00',
        liveOverTime: '2026/05/23 12:00:00'
    }"
/>

Multiple Players

<template>
    <VueAliplayerV2
        v-for="item in sources"
        :key="item"
        :source="item"
        :options="options"
    />
</template>

<script setup lang="ts">
import { reactive } from 'vue';

const sources = [
    '//player.alicdn.com/video/aliyunmedia.mp4',
    '//yunqivedio.alicdn.com/user-upload/nXPDX8AASx.mp4'
];

const options = reactive({
    autoplay: false,
    width: '100%',
    height: '300px'
});
</script>

v2 reuses SDK CSS/JS loading promises, so multiple players do not insert duplicate SDK tags for the same assets.

Custom Components and Marquees

Aliplayer custom components often require extra scripts. Use componentScripts to load extension scripts before player initialization.

<VueAliplayerV2
    :source="source"
    :component-scripts="['/aliplayer-components/marquee.js']"
    :options="{
        components: [
            {
                name: 'MarqueeComponent',
                type: window.MarqueeComponent,
                args: {
                    text: 'vue-aliplayer-v2'
                }
            }
        ]
    }"
/>

Playlist, watermark, marquee, and similar features depend on the Aliplayer custom component scripts you provide.

Forbid Fast Forward

<VueAliplayerV2
    :source="source"
    forbid-fast-forward
/>

This is implemented by watching playback progress and seeking back when a forward jump is detected. It is useful as a lightweight business restriction. Stronger anti-bypass requirements should be combined with server-side authorization, preview limits, or encrypted playback.

Retry After Failure

Aliplayer error pages are rendered by the SDK itself. Business code can listen to error and call retry() or reload() for local recovery.

function handleError() {
    playerRef.value?.retry();
}

Optional Tracking Request Blocking

<VueAliplayerV2
    :source="source"
    disable-tracking
    :tracking-url-patterns="['newplayer/track', /\/logstores\//]"
/>

This only blocks URLs matching the configured rules and is intended as a wrapper-level fallback. In production, prefer official Aliyun settings, console-side configuration, or your own compliant analytics strategy.

SSR and Nuxt

The Aliplayer SDK depends on browser window and DOM APIs. In SSR projects, render the player only on the client. For Nuxt:

<ClientOnly>
    <VueAliplayerV2 :source="source" />
</ClientOnly>

TypeScript

The package entry exports these types:

import type {
    AliplayerEventName,
    AliplayerInstance,
    AliplayerLicense,
    AliplayerOptions,
    AliplayerV2Props,
    VueAliplayerV2Expose,
    VueAliplayerV2Options
} from 'vue-aliplayer-v2';

Migration

From 1.x to 2.x

• v2 supports Vue 3 only and no longer keeps Vue 2 compatibility.
• The build toolchain is Vite, with ESM and UMD library outputs.
• Global registration now uses Vue 3 app.use(VueAliplayerV2, options).
• Component refs should use ref<VueAliplayerV2Expose | null>.
• The default SDK path now uses Aliyun imp-web-player 2.37.0.
• New configs include license, lowLatency, normalizeSourceUrl, componentScripts, and disableTracking.
• For legacy Vue 2 projects, pin vue-aliplayer-v2@1.x.

FAQ

The player is not visible

Make sure the player is rendered only in the browser and check the sdk-error event. Common causes include blocked SDK assets, missing License config, source CORS issues, and a container height of 0.

The new SDK reports a License error

Apply for a Web Player License in the Aliyun console and pass it through the license prop or options.license:

<VueAliplayerV2
    :source="source"
    :license="{ domain: 'example.com', key: 'your-license-key' }"
/>

URLs with Chinese characters or spaces fail to play

normalizeSourceUrl = true runs encodeURI on source URLs by default. If your business code already encodes URLs, disable it explicitly:

<VueAliplayerV2
    :source="source"
    :normalize-source-url="false"
/>

Should I update source or call loadByUrl when switching sources?

For normal Vue usage, update source. The component handles same-format and cross-format changes. For imperative workflows, call playerRef.value?.loadByUrl(url).

Local Development

npm install
npm run dev

Type check:

npm run type-check

Build the demo:

npm run build

Build the library:

npm run lib

License

MIT