zwplayer

3.6.1 zwplayer媒体源地址输入url详细说明与示例

zwplayer是一款功能强大的播放器，可以支持多种协议自适应与多码流自适应，要支持这么多功能，单纯用传统的字符串形式的url来作为媒体源地址输入已经无法满足要求了，本手册用url这个名称来作为输入地址变量仅仅是为了兼顾约定俗成，应该把它理解为源输入地址。下面分应用场景来说明url参数的输入形式，以便于充分发挥zwplayer的功能。

# 1、简单的媒体播放地址

与传统的url一样，输入一个字符串类型的url，支持的url示例如下：

http://www.domain.com/move1.mp4
http://192.168.1.100:8080/move1.flv
http://192.168.1.100:8080/live/stream.flv
http://192.168.1.100:8080/live/stream.m3u8
http://192.168.1.100:8080/live/stream.mpd
http://192.168.1.100:8080/live/stream.rtc
http://192.168.1.100:8080/live/stream.ts
http://192.168.1.100:8080/live/stream.mp3

类似于以上的url，每种url必须带扩展名zwplayer播放器才能识别用何种解码器进行解码播放。如果媒体服务器不支持扩展名，zwplayer需要在url后面追加一个mime_type参数，例如假设要播放一个MP4文件，服务器端提供的url不带扩展名，请如下构造url：

http://www.domain.com/ c08ac56ae1145566f2ce54cbbea35fa3?mime_type=video_mp4

注意：这个mime_type参数并不与http协议里的mime类型值一致，在无扩展名的媒体流后增加mime_type参数是目前一些主流视频网站的做法。

zwplayer 支持的简单url的写法与主流标准一致，针对于url中的扩展名与媒体类型对照如下：

扩展名 媒体类型 mime_type值 流类型
mp4 mp4媒体文件 video_mp4 直播、点播
flv flv文件或http-flv直播流 video_flv 直播、点播
m3u8 Apple http live stream hls video_hls 直播、点播
mpd Mpeg dash流 video_dash 直播、点播
rtc webrtc 直播流 video_rtc 直播
mp3,m4a 音频文件流 直播、点播
ts mpeg2 ts流 直播

# 2、多码流节目支持与多码流源地址输入格式构造

当前绝大多数视频网站对视频播放都提供不同清晰度的码流供用户选择，例如打开某些视频节目时，播放器可能提供1080P、720P、480P与360P等不同清晰度的码流供用户选择，清晰度高的码流往往占用更多的网络带宽，清晰度低的码流往往更流畅。其实这些不同清晰度的码流分别由不同的媒体文件提供，对于直播节目，要实现多码流需要在服务器上同时编码输出多个码流。zwplayer对多码流节目提供了强力支持。

注意：支持多码流不仅仅要有播放器端的支持，媒体服务器端也需提供相关支持。

下图展示了一个正在播放多码流节目的zwplayer实例：

image-20240617105853558

对于多码流节目，zwplayer会创建一个多码流选择器，并在播放器控制条的按钮区添加一个HD标志的按钮，用户点击此按钮会弹出流选择菜单以便用户能够选择码流。

单纯用简单的string类型的url无法表单复杂的地址信息，因此要支持一个多码流节目，需要给媒体源地址url参数提供一个js数组而不是简单的字符串，数组里的每个成员为一个码流地址信息，以下为一个多码流节目媒体源地址url参数的js对象示例：

var live_murl = [
	{
		"name": "HD1",
		"url": "http://serverhost.com/media/stream-403296100071244460_hd.flv"
	},
	{
		"name": "SD1",
		"url": "http:// serverhost.com/media/stream-403296100071244460_ld.flv",
		"default": true
	},
	{
		"name": "SD2",
		"url": "http:// serverhost.com/media/stream-403296100071244460_sd.flv"
	}
];

如上代码所示，每个地址信息为一个js对象，包含属性name、url与default等属性。其中name为码流的标识，url为码流的实际地址，default 为一个boolean类型，表示是否为首选码流，如果为首选码流，可以设置为true，否则可以缺省或者设置为false。

一些第三方播放器的多码流源输入地址的单个地址为数组形式，zwplayer也是支持的，例如：

var live_urls2 = [
		[
			"http://serverhost.com/stream-115066362597212639_uhd.flv",
			"FULL_HD1"
		],
		[
			"http://serverhost.com /stream-115066362597212639_hd.flv",
			"HD1"
		],
		[
			"http://serverhost.com /stream-115066362597212639_ld.flv",
			"SD1"
		],
		[
			"http://serverhost.com /stream-115066362597212639_sd.flv",
			"SD2"
		]
	];

以上这个示例代码是一些第三方播放器源输入地址的写法，每个码流地址为数组，数组的第0个位置为url；第1个位置为流的名称name，可以缺省；第2个位置为mime类型，通常缺省。 流地址对象的name属性有的网络视频平台用英文标识作为值，zwplayer将在创建流选择器时用当前的语言替换为用户可读的词语，对应表如下：

标识 可读词语（简体中文） 日本语 英文
HD1 超清
SD1 高清
SD2 标清
HD 高清
FHD 全高清
BD 蓝光
BD 4M 蓝光4M
BD 8M 蓝光8M
FULL_HD1 原画

建议在构造源输入地址时，流的name的值能用如上简写就用简写，以便在支持多语言时播放将它翻译为用户可读词语。 流标识完全是可以自定义的，不一定得用上面的对应表，例如如下是一个自定义流标识的示例：

var live_murl = [
	{
		"name": "1080P",
		"url": "http://serverhost.com/media/stream-403296100071244460_hd.flv"
	},
	{
		"name": "720P",
		"url": "http:// serverhost.com/media/stream-403296100071244460_ld.flv",
		"default": true
	},
	{
		"name": "480P",
		"url": "http:// serverhost.com/media/stream-403296100071244460_sd.flv"
	}
];

如以上示例，1080P，720P与480P是自定义的标识名，需要注意的是，这些自定义的标识名在多语言翻译时是不做处理的，因此尽量不要用特定语言的标识，例如，类似简体中文“高清”、“电脑观看”，“手机观看”等标识不做翻译处理的，如果在日语环境中还是显示中文。

zwplayer推荐采用如下格式构造多码流节目源的输入地址格式，示例如下：

var live_url = {
		..more properties..
		murls: {
			"FULL_HD1": "http://serverhost.com/stream-7298596124380760882_or4.flv",
			"HD1": "http://serverhost.com/stream-7298596124380760882_hd.flv",
			"SD1": "http://serverhost.com/stream-7298596124380760882_ld.flv ",
			"SD2": "http://serverhost.com/stream-7298596124380760882_sd.flv"
		},
		multistream: 4
};

采用如上推荐的格式时，url参数为一个对象，除了murls与multistream两个属性对于zwplayer来说是必要的之外，其它属性可以随意扩展。在这个推荐的地址格式中，murls为一个普通js对象（非数组）类型，该对象中的每个流地址为该对象的一个属性，对象中的属性名为流的标识，属性的值为流的实际url地址；multistream属性标识这个源地址总共有多少个流，可以省略。采用该格式，流地址对象构造起来较为简洁直观，因此推荐使用。

某些协议的单个字符串形式的url就支持多码流，例如hls 与 dash协议本身是可以支持多码流。这些内含多码流的hls协议流与dash协议流的url能被zwplayer完美支持，zwplayer支持hls协议与 dash协议多码流自适应切换与手动切换。

关于hls与dash支持多码流的更多技术请参考相关文档。

# 3、多协议自适应地址

随着流媒体技术的发展，流媒体厂家为了支持多终端播放，对于同一个直播节目流或者录播文件节目，支持多种协议输出。例如，对于直播，有些流媒体服务器的输出同时支持rtmp、http、websocket、hls与dash等协议；对于录播节目流，同一个节目可能同时支持MP4、hls与dash等协议输出；而至于如何播放，流媒体服务器厂家并不负责，需要播放终端自己解决。针对这种情况，zwplayer提供了全面支持，可以同时将不同协议的流地址传输给zwplayer播放器，由zwplayer自行判断采用何种协议，这就是所谓的多协议自适应播放。 为了支持多协议播放地址，需要给zwplayer传递一个js对象作为url参数，js对象的每一个属性名表示传输协议，属性的值表示该协议的url地址。

对于直播流地址，一个多协议播放地址格式的示例如下：

{
		"httpflv": "http://192.168.1.136:8188/live/stream0020.flv",
		"rtc": "http://192.168.1.136:8188/live/stream0020.rtc",
		"wsflv": "ws://192.168.1.136:8188/live/stream0020.flv",
		"httpflv-n": "http://192.168.1.136:8189/live/stream0020.flv",
		"wsflv-n": "ws://192.168.1.136:8189/live/stream0020.flv",
		"httpflv-n6": "http://[2408:8207:1858::332f:e4e8]:8189/live/stream0020.flv",
		"wsflv-n6": "ws://[ 2408:8207:1858::332f:e4e8]:8189/live/stream0020.flv",
		"hls": "http://192.168.1.136:8188/live/hls/stream0020/index.m3u8",
		"dash": "http://192.168.1.136:8188/live/dash/stream0020/index.mpd",
		"rtmp": "rtmp:// 192.168.1.136:1945/stream0020"
}

zwplayer已经支持的用于直播与录播节目的多协议地址对象属性如下：

属性名称（协议） 协议说明
httpflv 用http、https协议输出的 flv 流
rtc 用webrtc协议输出的直播流
wsflv 用websocket（ws）、websocket ssl（wss）协议输出的 flv 流
httpflv-n 用http、https协议输出的 flv 流（对于采用多端口的服务器有用）
wsflv-n 用ws、wss协议输出的 flv 流（对于采用多端口的服务器有用）
httpflv-n6 基于ipv6的http、https协议输出的 flv 流
wsflv-n6 基于ipv6的ws、wss协议输出的 flv 流
hls 采用Apple http live stream协议输出的直播流
dash 采用MPEG DASH协议输出的直播流
rtmp adobe rtmp 协议，注意：基于html5的zwplayer不支持rtmp播放
htt****p 以http协议输出的任何文件格式地址

对于多协议直播地址，须具备以上属性的一种或多种即可，不是所列的每种协议都要支持。例如如下示例地址的输入格式为常用的输入：

{
		"httpflv": "http://192.168.1.136:8188/live/stream0020.flv",
		"hls": "http://192.168.1.136:8188/live/hls/stream0020/index.m3u8"
}

大多数视频网站的直播协议仅支持httpflv与hls，因此仅需提供这两个属性即可。

对于点播（录播）流，多协议播放地址url可以采用如下格式：

{
"type": "dvr",
"rtmp": "rtmp://192.168.1.202:1936/vod/movie001.mp4",
"http": "http://192.168.1.202:8088/vod/mp4/movie001.mp4",
"hls": "http://192.168.1.202:8088/vod/hls/movie001/index.m3u8",
"dash": "http://192.168.1.202:8088/vod/dash/movie001/manifest.mpd"
}

以上示例，rtmp、http、hls与dash为协议名，至少提供一种协议即可。

上次更新: 2024/9/14 09:30:11

3.6.2 用zwplayer播放多码流节目