总局NGB-H媒体播放器规范

媒体播放模块消息
event. modifiers 媒体源路径有效。 媒体源路径无效。 开始播放成功。 开始播放失败。 步长设置成功。 步长设置失败。 设置播放时间点成功。 设置播放时间点失败。 暂停播放成功。 暂停播放失败。 恢复播放成功。 恢复播放失败。 停止播放成功。 停止播放失败。 消息说明
event.modifiers 值由中间件内部自动给出，其数据类型： ——“number” ，表示该值为消息描述字符串的 ID，可通过 Utility.getEventInfo()方法获取该消息描述字符串。 若“消息说明”定义了消息字符串 JSON 格式，则按格式取出消息内容。 65
H.3.2.3
方法 MediaPlayer
H.3.2.3.1
原型：MediaPlayer() 描述：构造方法，创建一个默认的 MediaPlayer 对象。 参数：无。 返回：无。 H.3.2.3.2 getPlayerInstanceID
原型：number getPlayerInstanceID() 描述：获取接收终端本地可用的播放器实例 ID，该 ID 由中间件内部自动分配。 参数：无。 返回：number 型，若成功则返回 0～255，若失败则返回-1。 H.3.2.3.3 bindPlayerInstance
GY/T XXX.3—XXXX H H
附 录 H （规范性附录） JavaScript-媒体处理单元 H.1 概述 本附录定义了与媒体处理相关的功能模块：媒体输入模块和媒体播放模块。 H.2 媒体输入模块 保留将来扩展。 H.3 媒体播放模块 本模块定义了与媒体播放相关的 JS 对象：MediaPlayer。 H.XX.3—XXXX H.3.2.3.5 setMediaSource
原型：number setMediaSource(mediaURL) 描述：异步方法，设置待播放媒体的 URL 地址。设置此参数后，中间件自动检测设置的 mediaURL 的合法性。 ——若 URL 合法，则向页面发送 MSG_MEDIA_URL_VALID 消息； ——若 URL 不合法，则向页面发送 MSG_MEDIA_URL_INVALID 消息。 页面只有接收到 MSG_MEDIA_URL_VALID 消息后，才可以调用 play()方法进行播放。 参数：mediaURL − string 型，以 URL 格式表示的媒体路径，URL 格式说明见表 H.5。 表H.5
媒体播放模块可能发给应用层的消息定义见表H.1。 表H.1
消息名称 MSG_MEDIA_URL_VALID MSG_MEDIA_URL_INVALID MSG_MEDIA_PLAY_SUCCESS MSG_MEDIA_PLAY_FAILED MSG_MEDIA_SETPACE_SUCCESS MSG_MEDIA_SETPACE_FAILED MSG_MEDIA_SEEK_SUCCESS MSG_MEDIA_SEEK_FAILED MSG_MEDIA_PAUSE_SUCCESS MSG_MEDIA_PAUSE_FAILED MSG_MEDIA_RESUME_SUCCESS MSG_MEDIA_RESUME_FAILED MSG_MEDIA_STOP_SUCCESS MSG_MEDIA_STOP_FAILED 保留 event.which 13001 13002 13003 13004 13005 13006 13007 13008 13009 13010 13011 13012 13013 13014 13015～13200
初 媒体来源 始 化 广播业务 互动电视 业务 IP-UDP 码流 68 √ √ 绑 定 √ √ 就 绪 √ √ 前进 √ √ 后退 N/A √ 快进 N/A √
媒体播放状态和步长表
播放 快退 N/A √ 慢进 N/A N/A 慢退 N/A N/A 暂停 停止 解除 绑定 √ √
√ √
√ √
√
√
√
√
原型：number unbindPlayerInstance(playerInstanceID) 描述：MediaPlayer 对象和当前播放器实例解除绑定，并释放播放器的相关资源。 参数：playerInstanceID − number 型，指示本地播放器实例 ID，取值范围 0～255。 返回：number 型，若成功则返回 0，若失败则返回-1。
H.3.2.1
媒体播放状态
媒体播放器存在以下播放状态：初始化、绑定、停止、播放（前进/后退/快进/慢进/快退/慢退） 、 暂停和解除绑定，状态转移示意图见图 H.2。
图H.2
媒体播放状态转移示意图
67
GY/T XXX.3—XXXX 图H.2中媒体播放的各种状态说明如下： ——初始化状态：当创建 MediaPlayer 对象，即进入初始化状态。 ——绑定状态：当 MediaPlayer 对象调用 bindPlayerInstance()方法后，即进入绑定状态。 ——停止状态：当 MediaPlayer 对象调用 setMediaSource()或 stop()方法后，即进入停止状态， 此时视音频停止播放，视频画面处于隐藏状态。 ——播放状态：当 MediaPlayer 对象调用 play()方法后，即进入播放状态，包括前进、后退、快 进、慢进、快退和慢退，播放步长与播放状态关系见表 H.2。 表H.2
N/A
N/A
N/A
N/A
N/A
√
√
√
GY/T XXX.3—XXXX
本地媒体 文件 √ √ √ √ √ √ √ √ √ √ √ √
H.3.2.2
属性
媒体播放对象的属性定义见表H.4。 表H.4 MediaPlayer 对象的属性
属性名称 location 类型 string 读写属性 只读 说明 表示媒体文件的定位器，格式见表 H.5。 表示当前 MediaPlayer 对象所绑定的播放器实例 ID。 若取值-1，则表示当前 MediaPlayer 对象尚未绑定任 playerInstanceID number 只读 何播放器实例。 例如在调用 bindPlayerInstance()方法之前，或在调 用 unbindPlayerInstance()方法之后，读取该属性， 应返回-1。
66
GY/T XXX.3—XXXX
//通过全局变量保留这个播放器实例标识以便跨页面时使用 GlobalVarManager.setItemValue(“PLAYER_INSTANCE_ID”, nativePlayerInstanceID); //MediaPlayer 对象与播放器实例绑定 mp1.bindPlayerInstance(nativePlayerInstanceID); mp1.setMediaSource(mediaURL); //设置媒体源 mp1.play(); //开始播放 ... mp1.setPace(2); ... mp1.setPace(1); ... mp1.pause(); //暂停播放 mp1.resume();//恢复播放 mp1.stop(); //停止播放 mp1.unbindPlayerInstance(nativePlayerInstanceID); //在下一个 Web 页面中，创建一个 MediaPlayer 对象 mp2 var mp2 = new MediaPlayer(); //通过全局变量获得上个页面的播放器实例 ID var nativePlayerInstanceID = GlobalVarManager.getItemValue(“PLAYER_INSTANCE_ID”); //根据上一个页面传递过来的播放器实例 ID ，绑定 MediaPlayer 对象和媒体播放实例 mp2.bindPlayerInstance(nativePlayerInstanceID); mp2.setMediaSource(mediaURL); //设置媒体源 mp2.play(); //开始播放 mp2.pause(); //暂停播放 mp2.resume();//恢复播放 mp2.stop(); //停止播放 mp2.unbindPlayerInstance(nativePlayerInstanceID); //恢复正常速度播放 //快进，2 倍速播放
GY/T XXX.3—XXXX
——“-”，表示event.modifiers为undefined。
H.3.2
MediaPlayer对象
MediaPlayer 对象为本地对象，需要先创建再使用。 该对象定义了在 Web 页面中进行媒体播放的属性和方法。 媒体源可以是电视广播、 声音广播或 NVOD， 也可以是一个 UDP 单播或组播流， 还可以是存储在接收终端本地的媒体文件。 本对象只需知道媒体类型 和媒体所在位置（URL）就可播放此媒体。 MediaPlayer 对象构造后只能在单个 Web 页面中使用，通过对象名来唯一标识；播放器实例对应于 接收终端的媒体解码资源，不和 Web 页面绑定，可以跨页面使用，通过播放器实例 ID 来唯一标识，播 放器实例 ID 由中间件内部自动产生。浏览器必须通过 MediaPlayer 对象提供的属性和方法，对播放器 实例进行控制实现媒体播放， 且一个 MediaPlayer 对象只能绑定一个播放器实例， 一个播放器实例同时 也只能被一个 MediaPlayer 对象绑定。MediaPlayer 对象和播放器实例之间的关系示意见图 H.1。
MediaPlayer对象 (对象名：mp2) MediaPlayer对象 （对象名：mp1）
bindPlayerInstance()
播放器实例 （硬件或软件解码资源）
图H.1 MediaPlayer 对象和媒体播放器实例之间的关系示意图
示例： Web 页面中创建的 MediaPlayer 对象，可控制接收终端上的播放器实例，播放器实例的生命周期是跨页面的。通过 MediaPlayer 对象的 playerInstanceID 属性来标识当前所绑定的播放器实例。 //在第一个 Web 页面中，创建一个 MediaPlayer 对象 mp1 var mp1 = new MediaPlayer(); //读取本地的媒体播放器实例 ID var nativePlayerInstanceID = mp1.getPlayerInstanceID();