Detailed explanation of source address URL parameters

zwplayer is a powerful player that supports multi-protocol adaptation and multi-bitrate adaptation. To support these extensive features, using traditional string-type URLs as media source input is no longer sufficient. Using the name "url" as the input address variable is merely for convention compatibility; it should be understood as the source input address. Below, we explain the input forms of the url parameter by application scenario to fully leverage the capabilities of zwplayer.

1. Simple Media Address Configuration

1.1 Basic Format

Supports standard URL string format. The player automatically identifies the media protocol type through the file extension.

1.2 Supported Protocol Examples

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

In the above URLs containing extensions, zwplayer will automatically identify the media protocol type based on the extension and call the corresponding decoder for playback, without requiring separate configuration for each protocol.

1.3 Handling Addresses Without Extensions

When the URL returned by the server does not contain a file extension, the mime_type parameter must be added to explicitly specify the media type:

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

Note: This mime_type parameter is not consistent with the MIME type values in the HTTP protocol. Adding the mime_type parameter after extension-less media streams is currently the practice of some mainstream video websites.

1.4 Extension to Media Type Mapping

zwplayer supports simple URL writing consistent with mainstream standards. The mapping between extensions in the URL and media types is as follows:

1.5 Protocol Header Detection

1.6 Notes

1. 1. If the stream_type parameter is specified, the stream_type parameter value shall prevail.

2. 2. If the type cannot be determined through the stream_type parameter, protocol header, or extension, it will be treated as video_mp4.

2. Multi-bitrate Stream Configuration

2.1 Application Scenarios

Currently, the vast majority of video websites provide different quality bitrates for video playback for users to choose. For example, when opening certain video programs, the player may provide different quality bitrates such as 1080P, 720P, 480P, and 360P for users to select. Higher quality bitrates often consume more network bandwidth, while lower quality bitrates tend to be smoother. In fact, these different quality bitstreams are provided by different media files respectively. For live programs, to achieve multi-bitrate, multiple bitstreams need to be encoded and output simultaneously on the server. zwplayer provides strong support for multi-bitrate programs.

Note: Supporting multi-bitrate requires not only player-side support but also relevant support from the media server.

The image below shows a zwplayer instance playing a multi-bitrate program:

For multi-bitrate programs, zwplayer will create a multi-bitrate selector and add an HD icon button to the player control bar. When users click this button, a stream selection menu will pop up allowing users to select the bitrate.

2.2 Configuration Format 1: Object Array

Simply using a simple string-type URL cannot express complex address information. Therefore, to support a multi-bitrate program, the media source address url parameter needs to be provided as a js array rather than a simple string. Each member in the array is a bitrate address information. The following is an example of a js object for the url parameter of a multi-bitrate program media source address:

var live_murl = [
	{
		"name": "HD1",
		"url": "http://example.com/media/stream-hd.flv"
	},
	{
		"name": "SD1",
		"url": "http://example.com/media/stream-ld.flv",
		"default": true
	},
	{
		"name": "SD2",
		"url": "http://example.com/media/stream-sd.flv"
	}
];

As shown in the above code, each address information is a js object containing properties such as name, url, and default.

• name: Stream identifier,

• url: Actual address of the stream

• default: boolean type, indicating whether it is the preferred stream. If it is the preferred stream, it can be set to true; otherwise, it can be omitted or set to false.

2.3 Configuration Format 2: Compatible with Third-Party Player Formats

Some third-party players use array format for individual addresses in multi-bitrate source input. zwplayer also supports this. For example:

var live_urls2 = [
		[
			"http://example.com/stream-uhd.flv",
			"FULL_HD1"
		],
		[
			"http://example.com/stream-hd.flv",
			"HD1"
		],
		[
			"http://example.com/stream-ld.flv",
			"SD1"
		],
		[
			"http://example.com/stream-sd.flv",
			"SD2"
		]
	];

The above example code is the writing method for source input addresses of some third-party players. Each bitrate address is an array:

• Position 0 is the url;

• Position 1 is the stream name, which can be omitted;

• Position 2 is the mime type, usually omitted.

2.4 Stream Identifier Standardization Recommendations

Some web video platforms use English identifiers as values for the name property of stream address objects. zwplayer will replace these with user-readable terms in the current language when creating the stream selector. The mapping table is as follows:

It is recommended that when constructing source input addresses, if the stream name value can use the above abbreviations, please do so, so that when multi-language support is available, the player can translate it into user-readable terms. Stream identifiers can be completely customized and do not necessarily have to use the above mapping table. For example, here is an example of custom stream identifiers:

var live_murl = [
	{
		"name": "1080P",
		"url": "http://example.com/media/stream-hd.flv"
	},
	{
		"name": "720P",
		"url": "http://example.com/media/stream-ld.flv",
		"default": true
	},
	{
		"name": "480P",
		"url": "http://example.com/media/stream-sd.flv"
	}
];

As shown in the above example, 1080P, 720P, and 480P are custom identifier names. It should be noted that these custom identifier names are not processed during multi-language translation. Therefore, try not to use language-specific identifiers. For example, identifiers similar to Simplified Chinese "高清" (HD), "电脑观看" (PC View), "手机观看" (Mobile View) are not processed for translation. If in a Japanese environment, they will still be displayed in Chinese.

2.5 Recommended Configuration Format

zwplayer recommends using the following format to construct multi-bitrate program source input addresses. Examples are as follows:

var live_url = {
		..more properties..
		murls: {
			"FULL_HD1": "http://example.com/stream-or4.flv",
			"HD1": "http://example.com/stream-hd.flv",
			"SD1": "http://example.com/stream-ld.flv ",
			"SD2": "http://example.com/stream-sd.flv"
		},
		multistream: 4  // Number of streams (optional)
};

When using the above recommended format, the url parameter is an object. Besides the murls and multistream properties which are necessary for zwplayer, other properties can be freely extended.

• murls: js object (not array) type. Each stream address in this object is a property of the object. The property name in the object is the stream identifier, and the property value is the actual url address of the stream;

• multistream: Indicates the total number of streams for this source address, can be omitted.

Using this format, stream address objects are constructed more concisely and intuitively, so it is recommended.

2.6 HLS/DASH Protocol Multi-bitrate

Some protocols support embedded multi-bitrate in a single string-type url. For example, hls and dash protocols themselves can support multi-bitrate. These hls protocol streams and dash protocol streams containing embedded multi-bitrate are perfectly supported by zwplayer. zwplayer supports adaptive switching and manual switching for embedded multi-bitrate in hls and dash protocols.

For more technical information about embedded multi-bitrate in hls and dash, please refer to relevant documentation.

3. Multi-protocol Adaptive Address Configuration

The same media source supports multiple transmission protocols, and the player automatically selects the optimal protocol for playback.

3.1 Application Scenarios

With the development of streaming media technology, streaming media manufacturers support multiple protocol outputs for the same live program stream or recorded file program to support multi-terminal playback. For example, for live streaming, some streaming media server outputs simultaneously support http, httpflv, websocket, hls, and dash protocols; for VOD program streams, the same program may simultaneously support MP4, flv, hls, and dash protocol outputs; and as for how to play, streaming media server manufacturers are not responsible, requiring playback terminals to solve it themselves. For this situation, zwplayer provides comprehensive support, allowing different protocol stream addresses to be passed to the zwplayer player simultaneously, and letting zwplayer determine which protocol to use itself. This is what is called multi-protocol adaptive playback. To support multi-protocol playback addresses, a js object needs to be passed to zwplayer as the url parameter. Each property name of the js object represents the transmission protocol, and the property value represents the url address of that protocol.

3.2 Live Stream Multi-protocol Configuration

For live stream addresses, an example of multi-protocol playback address format is as follows:

{
  "httpflv": "http://example.com:8188/live/stream0020.flv",
  "rtc": "http://example.com:8188/live/stream0020.rtc",
  "wsflv": "ws://example.com:8188/live/stream0020.flv",
  "httpflv-n": "http://example.com:8189/live/stream0020.flv",
  "wsflv-n": "ws://example.com: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://example.com:8188/live/hls/stream0020/index.m3u8",
  "dash": "http://example.com:8188/live/dash/stream0020/index.mpd",
  "rtmp": "rtmp://example.com:1945/stream0020"
}

The multi-protocol address object properties supported by zwplayer for live and recorded programs are as follows:

For multi-protocol live addresses, having one or more of the above properties is sufficient; not every protocol listed needs to be supported. For example, the following example address input format is commonly used:

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

Most video websites' live streaming protocols only support httpflv and hls, so only these two properties need to be provided.

3.3 VOD Stream Multi-protocol Configuration

For VOD (recorded) streams, multi-protocol playback address urls can use the following format:

{
"type": "dvr",
"httpflv": "http://example.com:1936/vod/stream0020.flv",
"http": "http://example.com:8088/vod/mp4/movie001.mp4",
"hls": "http://example.com:8088/vod/hls/movie001/index.m3u8",
"dash": "http://example.com:8088/vod/dash/movie001/manifest.mpd"
}

In the above example, httpflv, http, hls, and dash are protocol names. At least one protocol must be provided.