VAS_VoD Streaming

1 VAS Intro

1.1 Brief Introduction

The development of live streaming nowadays finds it increasingly difficult to stand apart from homogenization competition. Live streaming platform focuses on new features as always, but attaches greater importance to re-purposing live streaming content as well. Some customers hope to loop play the recording of live streaming, especially the great sport event to maintain viewership on streamer rooms. In response to that demand, CDNetworks rolls out VoD (video-on-demand) streaming feature, with which the recorded files will be streamed to live room for the viewers.

1.2 Applicable Product Lines

• Media Acceleration Live Broadcast

1.3 Applicable Scenarios

• Operate at the same performance level as theater and TV program playback.
• Enlarge the event impact by loop playback after the event ends.
• Loop play the previous live streaming content to maintain the viewership on the streamer room when the great anchor is not online.

2 VAS Detail

2.1 Usage Specification

VoD streaming is that the service PoP requests for the VoD (Video-on-Demand) file specified by customer in loop order or sequential order and pushes stream of the file content to the address specified by the customer. For customer’s convenience, CDNetworks offers API for connection.

API has access permission control, and it will only be correctly called when the account has enabled CDNW service and inputs parameter with certain rules. Access control policy is determined by three parameters of n, r, k, whose detailed descriptions are as follows:

1. n: set to Portal platform account name by default;
2. r: a unique random character string; 10 characters at most; recommend using timestamp
3. k: md5 verification value.

MD5 calculation method is: k = md5(r+key), which means that a new string, equals to r plus key, will be hashed by MD5 and converted into a new value k.
Note: you can get key from our customer service staff.

For example:
1.Apply and get the key=012f37a3f2952
2.A random character string r=1409284800 is generated
3.Merge and generate a new character string=1409284800012f37a3f2952
4. Calculate the new string with MD5 to get the k value: b9fed80be752551834eec3e52fa94115

Real-time VoD streaming
Call API to start/terminate the VoD streaming immediately.
API:
http://livect.ossin.cdnetworks.com/api/cdn/v2/forwardRequest.action(Used for Asia area);
http://livect.osame.cdnetworks.com/api/cdn/v2/forwardRequest.action(Used for Europe and America area)

Calling method: POST

HTTP header: Content-Type:application/json
Body content:

Start VoD streaming

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "1",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
				"url": "http://www.video.com/live/abc.mp4"
			},
			{
				"url": "http://www.video.com/live/1.flv",
				"absofftime": "20181022153000-20181022155000"
			},
			{
				"url": "http://www.video.com/live/2.mp4",
				"relofftime": "300-500"
			}
		],
		"forward": [{
				"url": "rtmp://www.push1.com/live/test"
			},
			{
				"url": "rtmp://www.push2.com/live/test2"
			}
		],
		"extendParam": {
			"loop": "1",
			"index": "1",
			"callBackFileInfo": "0"
		}
	}]
}

Notes: after VoD streaming begins, the service PoP server will read the file in the loop order for VoD streaming. The VOD streaming task ends when the customer calls the interface to terminate the task.

Terminate VoD streaming

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "2",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": ""
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}]
	}]
}

Body parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
transcallbackurl	string	Callback address	No
cmd	string	VOD streaming command	Yes	cmd=1 start VoD streaming；cmd=2 terminate VoD streaming；cmd=3 update file list；cmd=5 Playback resuming
type	string	VoD streaming type	Yes	Fill in a fixed value, type = video
list	list	Push-stream list	Yes

list parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
id	string	Customer’s task identification (ID)	Yes	The unique task identification (ID). When there is the same ID existed, end the previous task first and then start VoD streaming
src	list	Pull-stream info	Yes	Please refer to the src parameter specification list below
forward	list	VoD streaming info	Yes	Please refer to forward specification list below
extendParam	Array	Extension parameter	No	Please refer to extendParam parameter specification

src parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
url	string	VoD file address	Yes	Support filling in multiple VoD file addresses, supports video file formats of flv, mp4, m3u8, but the m3u8file referencing to other m3u8 is not supported.
absofftime	string	VoD streaming time ranges, and use semicolon “;” to separate them when there are more than one	No	Time range when the content is read at VoD streaming, for example: 20181022153000-20181022155000, yyyymmddHHMMSS format. Priority of time is relofftime> absofftime.
relofftime	string	VoD streaming time ranges, and use semicolon “;” to separate them when there are more than one	No	The unit is second

forward parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
url	string	push-stream address	Yes	This field supports filling in multiple VoD-streaming addresses, and only rtmp stream pushing is supported

extendParam parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
loop	int	Loop counts of the file	No	Loop counts of VoD files. When there are multiple VoD files in src, play them in sequential order and then in loop order
index	int	Reading sequence of the file	No	When there are multiple files in src, start VoD file streaming from the first file by default.
callBackFileInfo	int	Whether to call back VoD streaming file info every time	No	0 means no need to call back the info of VOD streaming file every time; 1 is to call back the info of VOD streaming file every time; the default set is 0

Timed VoD streaming
Call API to set the configuration of start/termination time of VoD streaming, and start/terminate the VoD streaming at the set time.

API:
http://livect.ossin.cdnetworks.com/api/cdn/v2/forwardRequest.action(Used for Asia area);
http://livect.osame.cdnetworks.com/api/cdn/v2/forwardRequest.action(Used for Europe and America area)

Calling method:POST

HTTP header: Content-Type:application/json
Body content:

Timed termination

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "1",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": "http://www.video.com/live/abc.mp4"
		}, {
			"url": "http://www.video.com/live/1.flv",
			"absofftime": "20181022153000-20181022155000"
		}, {
			"url": "http://www.video.com/live/2.mp4",
			"relofftime": "300-500"
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}],
		"extendParam": {
			"loop": "1",
			"index": "1",
			"callBackFileInfo": "0"
		},
		"start": "1540216800000",
		"end": "1540220400000"
	}]
}

Notes: start VoD streaming at the set time point, and the service PoP server will read the file in the loop order for VoD streaming. And the VOD streaming will end at the set termination time or when customer calls the interface to terminate the task.

Body parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
transcallbackurl	string	Callback address	No
cmd	string	VOD streaming command	Yes	cmd=1 start VoD streaming；cmd=2 terminate VoD streaming；cmd=3 update file list；cmd=5 Playback resuming
type	string	VoD streaming type	Yes	Fill in a fixed value, type = video
list	list	Push-stream list	Yes

list parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
id	string	Customer’s task identification (ID)	Yes	The unique task identification (ID). When there is the same ID existed, end the previous task first and then start VoD streaming
src	list	Pull-stream info	Yes	Please refer to the src parameter specification list below
forward	list	VoD streaming info	Yes	Please refer to forward specification list below
start	int	Time to start VOD streaming	Yes	13-digit unix timestamp: when start is less than the current time, start VOD streaming at the current time immediately
end	int	Time to terminate VOD streaming	Yes	13-digit unix timestamp: end must more than 5 minutes later than start and the current time
extendParam	Array	Extension parameter	No	Please refer to extendParam parameter specification

src parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
url	string	VoD file address	Yes	Support filling in multiple VoD file addresses, supports video file formats of flv, mp4, m3u8, but the m3u8file referencing to other m3u8 is not supported.
absofftime	string	VoD streaming time ranges, and use semicolon “;” to separate them when there are more than one	No	Time range when the content is read at VoD streaming, for example: 20181022153000-20181022155000, yyyymmddHHMMSS format. Priority of time is relofftime> absofftime.
relofftime	string	VoD streaming time ranges, and use semicolon “;” to separate them when there are more than one	No	The unit is second; time priority is end>relofftime

forward parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
url	string	push-stream address	Yes	Supports filling in multiple VoD-streaming addresses, and only rtmp stream pushing is supported

extendParam parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
loop	int	Loop counts of the file	No	Loop counts of VoD files. When there are multiple VoD files in src, play them in sequential order and then in loop order Priority level: end>loop
index	int	Reading sequence of the file	No	When there are multiple files in src, start VoD file streaming from the first file by default.
callBackFileInfo	int	Whether to call back VoD streaming file info every time	No	0 means no need to call back the info of VOD streaming file every time; 1 is to call back the info of VOD streaming file every time; the default set is 0

Timed termination
After the timed VOD streaming is configured, call the VOD-streaming termination command to end task when its end time has not reached. Parameters start and end should not be contained in the VOD-streaming termination command.

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "2",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": ""
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}]
	}]
}

Update files
In the process of VOD streaming, VOD file can be updated through interface. Then use the newly-updated files for VoD streaming. Body content:

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "3",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": "http://www.video.com/live/d.mp4"
		}, {
			"url": "http://www.video.com/live/3.flv",
			"absofftime": "20181022153000-20181022155000"
		}, {
			"url": "http://www.video.com/live/4.mp4",
			"relofftime": "300-500"
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}],
		"extendParam": {
			"loop": "1",
			"index": "1",
			"callBackFileInfo": "0",
			"waitCrtUrlFinish": "0"
		}
	}]
}

Body parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
cmd	string	VOD streaming command	Yes	cmd=3 update file list;

extendParam parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
waitCrtUrlFinish	int	Whether the file update takes effect immediately	No	0 demonstrates that the file takes effect immediately, i.e.streaming the updated files; 1 demonstrates that the file takes effect after the current VOD streaming task ends,i.e. streaming the updated files after the current task ends. Default set is 0.

Notes:

1. Please refer to the parameter specification above for the other parameters in the file update command.
2. If the file list is updated before VOD streaming starts, then the updated file will be used in the VOD streaming.

Playback resuming
Call the VOD streaming termination command to end the VOD streaming, and the system will record the playback time of the current file (with the validity period of 48 hours). When the interface is called to resume the playback, the VOD streaming PoPs will resume from the last end time.
Body content:

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "5",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": "http://www.video.com/live/d.mp4"
		}, {
			"url": "http://www.video.com/live/3.flv",
			"absofftime": "20181022153000-20181022155000"
		}, {
			"url": "http://www.video.com/live/4.mp4",
			"relofftime": "300-500"
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2",
			"resetUrl": "rtmp://www.push3.com/live/test3"
		}]
	}]
}

Body parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
cmd	string	VOD streaming command	Yes	cmd=5 playback resuming

extendParam parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
resetUrl	string	VOD streaming address changing	No	Change to which push-stream address when resuming playback, no changes by default

Notes:

1. Please refer to the parameter specification above for other parameters in the playback resuming command.
2. If VOD streaming ends spontaneously and is followed by playback resuming, then the situation is not the “termination” of cmd=2, but the situation of cmd=1.
3. Playback resuming command does not support fops and extendParam parameters, meaning that transcoding cannot be implemented in playback resume file;
4. The validity period of playback resuming time record is 48 hours, meaning that the file cannot resume playback after 48 hours.

Transcoding or watermarking
Through interface, VOD streaming is implemented. And transcoding and watermarking on the VOD streaming is supported through the interface after adding the corresponding transcoding and watermarking parameters.
Body content:

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "1",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": "http://www.video.com/live/d.mp4",
			"wmimage": "http://ws.test.com/live/picture1.jpg",
			"wmposition": "TOP_LEFT"
		}, {
			"url": "http://www.video.com/live/3.flv",
			"absofftime": "20181022153000-20181022155000"
		}, {
			"url": "http://www.video.com/live/4.mp4",
			"relofftime": "300-500"
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}],
		"fops": {
			"bps": "1200",
			"res": "25",
			"fps": "1280x640",
			"vcodec": "libx265",
			"acodec": "libmp3lame"
		}
	}]
}

list parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
fops	Array	Encoding parameter

fops parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
bps	string	Bit-rate (bps)	No	1200
res	string	Resolution	No	420x720 (the inline “x” is the low case letter “x”)
fps	string	frame rate(fps)	No	25
vcodec	string	Video encoding scheme	No	Libx264, supported schemes: libx264, libx265, libvpx, etc. The filling is fixed to libx264 when watermarking is required
acodec	string	Audio encoding scheme	No	Libfaac, support schemes: libmp3lame, libfaac, libvorbis, etc.

src parameter specification

Field name	Field type	Field meaning	Required field	Example to further demonstrate
wmimage	string	Url address of watermark image	No	If there is & in url, then url character escaping is needed
wmposition	string	Watermark position	No	TOP_LEFT top left corner; TOP_CENTER top center; TOP_RIGHT top right corner; CENTER_LEFT center left; CENTER center; CENTER_RIGHT center right; BOTTOM_LEFT Bottom left corner; BOTTOM_CENTER Bottom center; BOTTOM_RIGHT Bottom right corner.

Notes: Please refer to the parameter specification above for other parameters in the transcoding and watermarking command.

Interface response info

{
	"http_code": "200",
	"msg": "receive task success!",
	"call_time": 1479952114000
}

Return status code specification:
200: successful interface calling;
400: request parameter error (such as parameter missing, time format error)
403: no request permission;

Callback info of VOD streaming

{
	"msg": "Start pushing!",
	"code": "0",
	"srcurl": "[{\"url\":\"http://www.video.com/live/abc.mp4\"}]",
	"cmd": "1",
	"id": "124",
	"forwardurl": "rtmp://www.push1.com/live/test"
}

Field name	Field type	Field meaning	Required field
id	String	Customer task identification (ID)	Customer ID will show in the callback info if there is
srcurl	String	Pull-stream info list
forwardurl	String	VOD streaming info list
cmd	String	VOD streaming command	cmd=1 start VOD streaming; cmd=2 terminate VOD streaming
code	String	VOD streaming result	0: success; 1: failure; 2: warning
msg	String	Callback information

Notes: after VOD streaming callback, peer interface server returns 200 status code and body content. The body content may not be detailed, but cannot be empty.

3 Notices

1. Support configuring multiple VOD file addresses and multiple streams for VOD streaming.
2. If transcoding is used in the VOD streaming, which means if transcoding parameters such as bps, res, fps are configured, then the corresponding vcodec parameter should be filled.
3. If timeout occurs when obtaining VOD file or pushing stream, the server will retry. Timeout waiting time is 10S, and retry counts are 3 by default.
4. When you need to terminate a certain VOD streaming task, the parameters of id and forward in the task should be consistent with that in the VOD streaming start command. For example, if id is 123, VOD streaming address is A when streaming begins, then the id should be 123, address be A when streaming ends. When there are multiple VOD streaming addresses, you can terminate the task for one or more addresses.
5. The input values src and forward for interface calling are without quotation mark, and they are in ArrayList format; and the response values of srcurl and forwardurl in callback are with quotation mark and in string format.