VAS_VoD Streaming

Last update:2022-04-15 07:44:45

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.