import{_ as i,c as a,o as n,ak as l}from"./chunks/framework.xxfEszSJ.js";const g=JSON.parse('{"title":"Installation and Usage","description":"","frontmatter":{},"headers":[],"relativePath":"en/index.md","filePath":"en/index.md","lastUpdated":1755403790000}'),p={name:"en/index.md"};function t(e,s,h,k,r,E){return n(),a("div",null,s[0]||(s[0]=[l(`

Installation and Usage ​

Installation ​

bash
npm install artplayer
bash
yarn add artplayer
bash
pnpm add artplayer
html
<script src="path/to/artplayer.js"></script>

CDN ​

bash
https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.js
bash
https://unpkg.com/artplayer/dist/artplayer.js

Usage ​

html
<html>
    <head>
        <title>ArtPlayer Demo</title>
        <meta charset="UTF-8" />
        <style>
            .artplayer-app {
                width: 400px;
                height: 300px;
            }
        </style>
    </head>
    <body>
        <div class="artplayer-app"></div>
        <script src="path/to/artplayer.js"></script>
        <script>
          const art = new Artplayer({
              container: '.artplayer-app',
              url: 'path/to/video.mp4',
          });
        </script>
    </body>
</html>

Warning

The player's size depends on the size of the container container, so your container container must have a size.

You can find more usage examples at the link below

/packages/artplayer-template

Vue.js ​

vue
<script>
import Artplayer from 'artplayer'

export default {
  props: {
    option: {
      type: Object,
      required: true,
    },
  },
  data() {
    return {
      instance: null,
    }
  },
  mounted() {
    this.instance = new Artplayer({
      ...this.option,
      container: this.$refs.artRef,
    })

    this.$nextTick(() => {
      this.$emit('get-instance', this.instance)
    })
  },
  beforeUnmount() {
    if (this.instance && this.instance.destroy) {
      this.instance.destroy(false)
    }
  },
}
</script>

<template>
  <div ref="artRef" />
</template>
vue
<script>
import Artplayer from './Artplayer.vue'

export default {
  components: {
    Artplayer,
  },
  data() {
    return {
      option: {
        url: 'path/to/video.mp4',
      },
      style: {
        width: '600px',
        height: '400px',
        margin: '60px auto 0',
      },
    }
  },
  methods: {
    getInstance(art) {
      console.info(art)
    },
  },
}
</script>

<template>
  <Artplayer :option="option" :style="style" @get-instance="getInstance" />
</template>

Artplayer Not Responsive：

Modifying option directly in Vue.js will not change the player

React.js ​

jsx
import Artplayer from 'artplayer'
import { useEffect, useRef } from 'react'

export default function Player({ option, getInstance, ...rest }) {
  const artRef = useRef()

  useEffect(() => {
    const art = new Artplayer({
      ...option,
      container: artRef.current,
    })

    if (getInstance && typeof getInstance === 'function') {
      getInstance(art)
    }

    return () => {
      if (art && art.destroy) {
        art.destroy(false)
      }
    }
  }, [])

  return <div ref={artRef} {...rest}></div>
}
jsx
import React from 'react'
import Artplayer from './ArtPlayer.jsx'

function App() {
  return (
    <div>
      <Artplayer
        option={{
          url: 'https://artplayer.org/assets/sample/video.mp4',
        }}
        style={{
          width: '600px',
          height: '400px',
          margin: '60px auto 0',
        }}
        getInstance={art => console.info(art)}
      />
    </div>
  )
}

export default App

Non-responsive Artplayer

In React.js, directly modifying the option will not change the player

TypeScript ​

Importing Artplayer will automatically import artplayer.d.ts

Vue.js ​

vue
<script setup>
import Artplayer from 'artplayer';
const art = ref<Artplayer>(null);
art.value = new Artplayer();
</script>

React.js ​

jsx
import Artplayer from 'artplayer';
const art = useRef<Artplayer>(null);
art.current = new Artplayer();

Option ​

You can also use the option type

ts
import Artplayer from 'artplayer';

const option: Artplayer['Option'] = {
    container: '.artplayer-app',
    url: './assets/sample/video.mp4',
};

option.volume = 0.5;

const art = new Artplayer(option);

Complete TypeScript Definitions

packages/artplayer/types

JavaScript ​

Sometimes your js file may lose the TypeScript type hints, in this case, you can manually import the types

Variables:

js
/**
 * @type {import("artplayer")}
 */
let art = null;

Parameters:

js
/**
 * @param {import("artplayer")} art
 */
function getInstance(art) {
  //
}

Properties:

js
export default {
  data() {
    return {
      /**
       * @type {import("artplayer")}
       */
      art: null,
    }
  }
}

Options:

js
/**
 * @type {import("artplayer/types/option").Option}
 */

const option = {
    container: '.artplayer-app',
    url: './assets/sample/video.mp4',
};

option.volume = 0.5;

const art8 = new Artplayer(option);

Ancient Browsers ​

The production build of artplayer.js is only compatible with the latest major version of Chrome: last 1 Chrome version

For ancient browsers, you can use the artplayer.legacy.js file, which is compatible up to: IE 11

js
import Artplayer from 'artplayer/dist/artplayer.legacy.js'
bash
https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.legacy.js
bash
https://unpkg.com/artplayer/dist/artplayer.legacy.js

If you need to support even older browsers, please modify the following configuration and then build it yourself:

Build configuration: scripts/build.js

Refer to documentation: browserslist

ECMAScript Module ​

ESM Demo:

https://artplayer.org/esm.html

Starting from 5.2.6, artplayer and all plugins will also provide an ESM version of mjs, such as:

html
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>ArtPlayer ESM with Import Map</title>
    <style>
        #player {
            width: 640px;
            height: 360px;
            margin: 50px auto;
            border: 1px solid #ccc;
        }
    </style>
    <script type="importmap">
    {
        "imports": {
            "artplayer": "https://unpkg.com/artplayer/dist/artplayer.mjs"
        }
    }
    </script>
</head>

<body>
    <div id="player"></div>
    <script type="module">
        import Artplayer from 'artplayer';

        const art = new Artplayer({
            container: '#player',
            url: '/assets/sample/video.mp4',
        });
    </script>
</body>

</html>

Custom userAgent ​

Currently, the determination of mobile devices is not accurate. Sometimes, you may want to adjust the player UI by changing the userAgent. Therefore, starting in version 5.2.4, we added a new globalThis.CUSTOM_USER_AGENT global variable.

html
<html>
    <head>
        <title>ArtPlayer Demo</title>
        <meta charset="UTF-8" />
        <style>
            .artplayer-app {
                width: 400px;
                height: 300px;
            }
        </style>
    </head>
    <body>
        <div class="artplayer-app"></div>
        <script>globalThis.CUSTOM_USER_AGENT = 'iphone'</script>
        <script src="path/to/artplayer.js"></script>
        <script>
          const art = new Artplayer({
              container: '.artplayer-app',
              url: 'path/to/video.mp4',
          });
        </script>
    </body>
</html>

Warning

You need to modify it before import the Artplayer for it to take effect

`,50)]))}const c=i(p,[["render",t]]);export{g as __pageData,c as default};