售前咨询
点播云
接入指引
更新时间：2023-01-04 15:40:44
快速开始
播放组件提供原生js组件，React组件，Vue2/Vue3组件。可以通过NPM使用或者在页面引入的方式引入。
如何使用
NPM方式接入
npm i @kwai-video-team/kwai-player-web
import KwaiPlayer from '@ks-video-team/kwai-player-web';
player = new KwaiPlayer('#player', {
src: 'http://xxxx.mp4',
autoplay: true,
});
在页面中引入
- 引入js
<script src="https://cdn.jsdelivr.net/npm/@kwai-video-team/kwai-player-web/full/kwai-player-web-full.umd.js"></script>
- 提供挂载元素
<body>
<div id="player"></div>
</body>
- 实例化
<script>
const player = new KwaiPlayer.default('#player', {
src: 'http://xxxx.mp4',
autoplay: true,
});
//...
</script>
导出包类型
推荐使用 默认导出（full）或各框架对应的导出包含了大部分常用插件，
基础导出（basic）减少了基本控件以外的插件，对于不需要使用过多功能的情况使用
| 类型 | npm引用 | script引用 |
|---|---|---|
| full | @kwai-video-team/kwai-player-web | https://cdn.jsdelivr.net/npm/@kwai-video-team/kwai-player-web/full/kwai-player-web-full.umd.js |
| basic | @kwai-video-team/kwai-player-web/basic | https://cdn.jsdelivr.net/npm/@kwai-video-team/kwai-player-web/basic/kwai-player-web-basic.umd.js |
| Vue2 | @kwai-video-team/kwai-player-web/vue2 | https://cdn.jsdelivr.net/npm/@kwai-video-team/kwai-player-web/vue2/kwai-player-web-vue2.umd.js |
| Vue3 | @kwai-video-team/kwai-player-web/vue3 | https://cdn.jsdelivr.net/npm/@kwai-video-team/kwai-player-web/vue3/kwai-player-web-vue3.umd.js |
| React | @kwai-video-team/kwai-player-web/react | https://cdn.jsdelivr.net/npm/@kwai-video-team/kwai-player-web/react/kwai-player-web-react.umd.js |
各包包含插件情况、详见插件文档
组件示例
原生js
import KwaiPlayer from '@ks-video-team/kwai-player-web';
player = new KwaiPlayer('#player', {
src: 'http://xxxx.mp4',
autoplay: true,
});
<body>
<div id="player"></div>
</body>
React
import KwaiPlayerReact from '@ks-video-team/kwai-player-web/react';
function App() {
const videoRef = useRef(null);
useEffect(() => {
if (videoRef.current) {
videoRef.current.play();
}
}, [videoRef]);
function onLoadedMetadata(){
const duration = videoRef?.current?.duration//总时长
const videoheight = videoRef?.current?.videoHeight//视频资源的高度
const videowidth = videoRef?.current?.videoWidth//视频资源的宽度
console.log(duration, videoheight, videowidth)
}
function onerror(val){
console.log(val)
}
function onTimeUpdate() {
console.log(videoRef?.current?.currentTime);//打印当前时间
}
return (
<div className="App">
<KwaiPlayerReact
className="kwai-player-react"
ref={videoRef}
src={'http://xxxx.mp4'}
autoPlay={true}
controls={true}
onTimeUpdate={onTimeUpdate}
preload="auto"
onError={onerror}
onLoadedMetadata={onLoadedMetadata}
></KwaiPlayerReact>
</div>
);
}
Vue2
import KwaiPlayerVue2 from '@ks-video-team/kwai-player-web/vue2';
import poster from '../xxxx@2x.png'
export default {
name: 'App',
data() {
return {
src: 'http://xxxx.mp4',
autoplay: true,
controls:true,
loop:true,
poster:poster
};
},
components: {
'kwai-player-vue2': KwaiPlayerVue2,
},
methods:{
error(val){
console.log(val)
},
loadedmetadata(){
let duration = this.$refs['videoRef'].getDuration()
let videoheight = this.$refs['videoRef'].getVideoHeight()
let videowidth = this.$refs['videoRef'].getVideoWidth()
},
timeupdate(){
console.log(this.$refs['videoRef'].getCurrentTime())//当前时间
}
}
};
<kwai-player-vue2
class="player"
:src="src"
:controls="controls"
:autoplay="autoplay"
:loop="loop"
:poster="poster"
@error="error"
@loadedmetadata="loadedmetadata"
@timeupdate="timeupdate"
>
</kwai-player-vue2>
Vue3
import KwaiPlayerVue3 from '@ks-video-team/kwai-player-web/vue3';
import poster from '../xxxx@2x.png'
import {ref} from'vue'
export default {
name: "demo",
components: {
'kwai-player-vue3': KwaiPlayerVue3,
},
setup(){
const src = ref('https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8')
const autoplay = ref(true)
const controls = ref(true)
const loop = ref(true)
const videoRef = ref(null)
const timeupdate = ()=>{
console.log(videoRef._value.getCurrentTime())//当前时间
}
const loadedmetadata = ()=>{
const duration = videoRef._value.getDuration()
const videoheight = videoRef._value.getVideoHeight()
const videowidth = videoRef._value.getVideoWidth()
}
const error = (val)=>{
console.log(val)
}
return{
videoRef,
src,
autoplay,
controls,
poster,
timeupdate,
loadedmetadata,
error
}
}
}
<kwai-player-vue3
class="player"
:src="src"
:controls="controls"
:autoplay="autoplay"
:loop="loop"
:poster="poster"
@error="error"
@loadedmetadata="loadedmetadata"
@timeupdate="timeupdate"
/>
需要参考的文档：
播放组件的属性、API及事件参考了HTMLVideoElement的实现。
Server-side-rendering (SSR)
可以安全地在Node中require此库
CORS
视频资源必须允许GET请求，且包含CORS响应头。
播放H.265/KVC/VVC说明
面向普通用户的场景不推荐使用wasm解码器。如果要使用H.265/AV1编码，推荐采用快手web端H.265整体解决方案，更多咨询问题请联系我们。
浏览器不支持H.265/KVC/VVC解码时，会采用wasm解码器。
采用wasm解码器时，上层业务是无感知的。
wasm解码器兼容性：
chrome 67+
wasm解码器性能优化
播放组件在使用wasm解码器器时支持多线程解码及SIMD，且会根据浏览器能力开启对应的加速解码功能。
多线程解码用到了SharedArrayBuffer，chrome 92+需要对播放页增加两个响应头，推荐添加
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
播放页中的部分标签可能需要添加crossorigin属性
页面增加这两个头会导致无法加载跨域资源。以下是以图片为例的解决方案。
- 解决方案A：在图片的响应头中添加：Cross-Origin-Resource-Policy: cross-origin;
- 解决方案B：img标签中增加crossorigin属性