Player API 开发指南 版本 : 1.0.5 日期 : 2014-10-24 北京梦之窗数码科技有限公司
目录 1. 概述... 1 2. 接 口... 1 3. 配置... 2 4. 插件介绍... 5 4.1 字幕插件... 5 4.2 弹幕插件... 6 附录 1. Flash 和 Javascript 交互... 7 附录 2. 播放器错误码... 9
1. 概述 利 用 Player API 与 CC 视频播放器进 行交互, 可以改变播放器界 面 实现 一些增值功能 目前仅限于 Flash 播放器,FlashPlayer 插件版本要求为 10.1 及以上, 播放器 页 面代码中必须允许播放器与 页 面脚本通信 2. 接 口 接 口分为两种类型 : 方法 回调 ; 方法 : 播放器开放的 JavaScript 函数, 播放器的句柄需要 用Object 标签的 id 属性或 embed 的 name 属性来获取 ; 回调 : 播放器运 行过程中尝试调 用 页 面JS 函数, 可理解为事件 使 用 方法可参考附录 1. Flash 与 JavaScript 交互 ; 接 口类型 start() 方法开始播放 pause() 方法暂停播放 resume() 方法恢复播放 seek(time) 方法 定位 至指定时间 参数 time 单位秒 getduration() 方法获取视频 片 长, 返回值单位秒 getposition() 方法获取当前播放时间, 返回值单位秒 getqualities() 方法 获取当前视频可 用清晰度列表, 返回类型 Array, 格式如下 : [ { value:"0", label:" 普通 ", { value:"1", label:" 清晰 " ] setquality(quality) 方法 设置清晰度 参数 quality 为 getqualities 方法获取的 value 值 setvolume(volume) 方法 设置 音量 参数 volume 取值范围 0-1 normalscreen() 方法退出全屏 setconfig(config) 方法 配置播放器 参数 config 为配置对象, 详 见3. 配置 on_cc_player_init(vid,swfid) 回调 播放器界 面元素初始化时 vid : 视频唯 一标识 swfid : 页 面中播放器的 id on_cc_player_pluginready(name) 回调 插件准备就绪, 意味着该插件相关接 口可 用 name : 插件名称 第 1 页共 9 页
3. 配置 播放器配置可以改变播放器的界 面, 开启更多的回调接 口, 还可以使 用 一些特殊的功能, 如 自定义全屏 字幕功能 配置的 方法是在回调接 口 on_cc_player_init 触发时, 调 用 setconfig 方法传递 一个 Object 对象, 此对象每个 key 都是 一个配置项, 对应的 value 就是所配置的值 播放器所 支持的配置项如下 : 第 2 页共 9 页
配置项 control_enable progressbar_enable loadingpic_enable loading_enable bigbutton_enable startbutton_enable resumebutton_enable tip_enable alert_enable recommend_enable keyboard_enable rightmenu_enable fullscreen_enable 是否显 示控制条默认 1, 设置为 0 则不显 示控制条 是否可操作进度条默认 1, 设置为 0 则进度条不可操作 是否启 用缓冲 片头默认 1, 设置为 0 则不会出现缓冲 片头 是否显 示 loading 图标默认 1, 设置为 0 则不显 示 loading 图标 是否显 示 非 自动播放时出现的开始按钮和暂停时的 大播放按钮默认 1, 设置为 0 则不显 示如需要单独控制请使 用 startbutton_enable,resumebutton_enable 是否显 示 非 自动播放时出现的开始按钮默认 1, 设置为 0 则不显 示 是否显 示暂停时的 大播放按钮默认 1, 设置为 0 则不显 示 是否可显 示播放器顶部的提 示条默认 1, 设置为 0 则不再出现提 示条 是否可显 示播放器中间的提 示 面板默认 1, 设置为 0 则不再出现提 示 面板 是否启 用播放结束后的推荐界 面默认 1, 设置为 0 则播放结束后不显 示推荐界 面 是否启 用按键操作默认 1, 设置为 0 则按键操作不可 用 是否启 用右侧菜单默认 1, 设置为 0 则不显 示右侧菜单 是否使 用 自定义全屏操作默认 0, 设置为 1 可以替代 Flash 全屏 play_start_time 设置开播的时间点, 单位秒, 如果超出视频时 长会按 0 处理, 此配置项能够使接着上次观看功能失效 fullscreen_function 替代 Flash 全屏的 JS 函数的名称, 需 fullscreen_enable 设置为 1, 这个函数需要返回 一个值以确定当前状态 (0: 正常,1: 全屏 ) video_marks 配置视频打点数据, 此配置项的值是 一个数组, 格式如下 : [ { time : time, desc : desc ] time 为视频时间, 单位秒 ;desc 为对应时间的打点 video_marks_json_url player_plugins on_player_stop 配置视频打点数据接 口地址, 优先级 高于 video_marks, 接 口必须返回 JSON 数据, 格式如下 : { value : [ { time : time, desc : desc ] 配置播放器插件, 详 见 4. 插件介绍 播放结束后回调 JS 函数的名称默认 on_spark_player_stop 第 3 页共 9 页
配置项 on_player_pause on_player_resume on_player_ready on_player_start on_player_seek on_player_buffering on_player_setquality on_player_volumechange on_player_playerror on_player_fullscreen 暂停播放时回调 JS 函数的名称默认 on_spark_player_pause 暂停后继续播放时回调 JS 函数的名称默认 on_spark_player_resume 播放器准备就绪回调 JS 函数的名称默认 on_spark_player_ready 开始播放时回调 JS 函数的名称默认 on_spark_player_start 指定时间定位时回调 JS 函数的名称回调时的参数 : from : 定位之前的时间点, 单位秒 to : 定位指定的时间点, 单位秒 缓冲开始或结束时回调 JS 函数的名称回调时的参数 : flag : 是否缓冲中 (0: 否,1: 是 ) 清晰度改变时回调 JS 函数的名称回调时的参数 : quality : 当前清晰度 音量改变时回调 JS 函数的名称回调时的参数 : vol : 当前 音量 ( 范围 0-1) 当播放失败时回调 JS 函数的名称回调时的参数 : code : 错误码, 详 见附录 2. 播放器错误码 全屏或退出全屏时回调 JS 函数的名称回调时的参数 : flag : 是否全屏 (0: 否,1: 是 ) 以下代码为配置 示例 第 4 页共 9 页
<script type="text/javascript"> function customfullscreen(){ //TODO 自定义全屏 function onplaypaused(){ // 已暂停播放 function on_cc_player_init( vid, swfid ){ var config = {; config.fullscreen_enable = 1; config.fullscreen_function = "customfullscreen"; // 设置 自定义全屏函数的名称 config.on_player_pause = "onplaypaused"; // 设置当暂停播放时的回调函数的名称 var player = getswf( swfid ); player.setconfig( config ); function getswf( swfid ) { if( window.document[ swfid ] ) { return window.document[ swfid ]; else if( navigator.appname.indexof( "Microsoft" ) == -1 ) { if( document.embeds && document.embeds[ swfid ] ) { return document.embeds[ swfid ]; else { return document.getelementbyid( swfid ); </script> 4. 插件介绍 插件是指基于播放器实现可插拔的独 立功能块, 用户通过播放器配置启 用插件, 从 而可以使 用相应的功能 要使 用插件时, 在 player_plugins 配置项中添加插件的名称和参数 4.1 字幕插件 字幕插件可使播放器在播放视频的同时显 示相关 文字, 启 用时在配置中添加插件名称 Subtitle, 参数如下 : 第 5 页共 9 页
参数 url 字幕 文件地址, 仅 支持 srt 格式的字幕 文件, 此参数为必需参数 size 字体 大 小, 默认 20 color surroundcolor font 字体颜 色, 默认 0xFFFFFF 文字环绕颜 色, 默认 0x000000 字体名称, 默认 Times New Roman bottom 文本与播放区域底部的距离占播放区域 高的百分 比, 默认 0.15 code 字幕 文件编码, 支持 utf-8 gbk, 默认 utf-8 注意事项 : 字幕 文件所在的服务器根 目录需要部署 一个安全策略 文件 ( crossdomin.xml ), 使播放器能够跨域访问字幕 文件 了解更多关于安全策略 文件可访问 http://help.adobe.com/zh_cn/as3/dev/ WS5b3ccc516d4fbf351e63e3d118a9b90204-7c85.html#WS5b3ccc516d4fbf351e63e3d118a9b90204-7e08 以下代码为字幕插件配置 示例 <script type="text/javascript"> function on_cc_player_init( vid, objectid ){ var config = {; config.player_plugins = { Subtitle : { url : "http://yourdomain/subtitle.srt", size : 20, color : 0xCCCCCC, surroundcolor : 0x0000FF, bottom : 0.15, font : " 微软雅 黑 ", code : "gbk" ; var player = getswf( objectid ); player.setconfig( config ); </script> 4.2 弹幕插件 启 用时在配置中添加插件名称 BulletCurtain, 参数如下 : 第 6 页共 9 页
参数 size 默认字体 大 小, 默认 30 color font 默认字体颜 色, 默认 0xFFFFFF 默认字体名称, 默认 Times New Roman duration 所有弹幕在展 示的时 长, 单位秒, 默认 10 alpha 所有弹幕的不透明度, 取值范围 0-1, 默认 1 visible 所有弹幕是否可 见,1 为可 见,0 不可 见, 默认 1 弹幕插件启 用后还开放有如下接 口 : 接 口 setbulletcurtainalpha(alpha) setbulletcurtainvisible(visible) addbullet(data, menu) 设置所有弹幕的不透明度 设置所有弹幕是否可 见 立刻显 示 一 行弹幕 参数 data 是 一个对象, 于此接 口有意义的 key 如下 : id : 唯 一标识符 text : 文字内容, 此为必要数据 type : 弹幕类型,0 为从右 至左,1 为顶端, 2 为底端, 默认 0 size : 字体 大 小 color : 字体颜 色 bordercolor : 边框颜 色, 默认 -1 不显 示边框 参数 menu 为 一个数组, 用来构建弹幕的右键菜单, 默认为空数组元素需为 一个对象 label : 菜单项显 示的 文字 callback : 菜单项点击后回调的 JS 函数名称, 回调时参数为 data removebullet(id) 移除 一 行弹幕 使 用弹幕插件时, 需了解此插件仅提供了把 文字渲染 至视频画 面上 ( 包括滚动和排列 ) 的功能, 播放器不管理各个弹幕与视频时间的对应关系, 调 用 addbullet 时在当前时刻显 示 一个弹幕并在 duration 秒之后 自动移除, 弹幕从画 面中移除后 ( 设置 alpha 和 visible 不会移除 ), 其相关数据都会丢弃, 所以 seek 到 一个之前播放过的时间点, 需要重新调 用 addbullet 以显 示之前出现过的弹幕, 另外只有对于正显 示着的弹幕调 用 removebullet 才有意义 附录 1. Flash 和 Javascript 交互 播放器的 HTML 代码中 allowscriptaccess 是 一个与 Javascript 交互所必需的属性, 其值必须为 always; object 标签中 id 属性是 IE 内核浏览器中获取播放器句柄的关键, 在 非 IE 内核浏览器中则是 embed 标签的 name 属性 ; 它们的值不能为空, 并且不能和 页 面其他元素重名 可使 用下例中的 getswf 函数来获取播放器句柄 ; 另外播放器回调接 口 on_cc_player_init 会传递参数 swfid, 在这个回调接 口中使 用 getswf( swfid ) 也可获取到播放器句柄 第 7 页共 9 页
<object... id="cc_a5feb0ea05f2100b9c33dc5901307461">... <param name="allowfullscreen" value="true" /> <param name="allowscriptaccess" value="always" /> <embed... name="cc_a5feb0ea05f2100b9c33dc5901307461" allowfullscreen="true" allowscriptaccess="always"... /> </object> <script type="text/javascript"> </script> function on_cc_player_init( vid, objectid ){ var player = getswf( objectid ); player.start(); function getswf( swfid ) { if( window.document[ swfid ] ) { return window.document[ swfid ]; else if( navigator.appname.indexof( "Microsoft" ) == -1 ) { if( document.embeds && document.embeds[ swfid ] ) { return document.embeds[ swfid ]; else { return document.getelementbyid( swfid ); 另外, 对于使 用 SWFObject 的 用户, 可参考以下代码把播放器嵌 入您的 网 页 // for 1.5 var swfobj = new SWFObject( [PlayerURL], [PlayerID], [PlayerWidth], [PlayerHeight], "10" ); // 如果 [PlayerURL] 不是带参数的, 就 至少必须增加以下参数 : swfobj.addvariable( "siteid", [UID] ); swfobj.addvariable( "vid", [VID] ); swfobj.addparam( "allowscriptaccess", "always" ); swfobj.addparam( "allowfullscreen", "true" ); swfobj.write( [ContainerID] ); // for 2.x var flashvars = { "siteid": [UID], "vid": [VID] ; var params = { "allowscriptaccess": "always", "allowfullscreen": "true" ; var attributes = { "name": [PlayerID], "id": [PlayerID] ; swfobject.embedswf( [PlayerURL], [ContainerID], [PlayerWidth], [PlayerHeight], "10.1.0", [ExpressInstallSwfurl], flashvars, params, attributes ); 第 8 页共 9 页
[PlayerURL] 播放器地址 ; [PlayerID] 指定 页 面上播放器的 id, 可 用于播放器 API 交互 ; [PlayerWidth] 播放器宽 ; [PlayerHeight] 播放器 高 ; [UID] 用户 ID; [VID] 视频 ID; [ContainerID] 将添加播放器的容器的 ID; [ExpressInstallSwfurl] 指定 express install SWF 的 URL 并激活 Adobe express install, 不指定时可 用 false 附录 2. 播放器错误码 代码 102 视频列表为空 103 无效的视频列表 108 列表模式视频信息加载失败 109 视频信息加载失败 110 视频审核中 111 用户流量 用尽 112 用户账号被锁 113 视频处理中 114 视频被屏蔽 115 视频信息错误 116 无视频 文件 205 当前域名不允许播放 207 授权播放验证未通过 304 测速失败 305 切换清晰度失败 306 播放中播放失败 第 9 页共 9 页