Overview

The medias module can connect to multiple media sources at the same time. It consists of three parts:

Manager: Integrated onvif device search function, the searched device can be further identified as a Device object, and a Media object can be created for the Device object; Manager provides Device objects management interface.

Device: Integrates the onvif device object and onvif media stream object. The Device object has a unique key identification. A Device object may be associated with multiple onvif media stream.

Media: Integrates the WebMedia server and onvif.Camera objects, and provides a control interface for the camera media source.

The medias module realizes the search, connection and control functions of multiple camera devices at the same time.

Medias module depends on @edgeros/jsre-onvif and WebMedia modules.

User can use the following code to import the medias module.

var medias = require('@edgeros/jsre-medias');

Support

The following shows medias module APIs avaliable for each permissions.

Media Class

new medias.Media(key, sid, app[, cam[, timeout]])

• key {String} Media id.
• sid {String} As the main part of media websocket server path. Data server path: /${sid}.media; Stream server path: /${sid}.
• app {WebApp} Web app object.
• cam {onvif.Camera} Onvif camera object. If cam unvalid, media.enableMove is false.
• timeout {Integer} Media server timeout. When there is no client access to media server, it will be closed after timeout. default: 18000000s.

Media is an encapsulation of WebMedia.MediaServer, and Media also provides a move control interface for onvif.Camera.

Media objects are usually created by Manager.

Media Object

media.ser

• {WebMedia.MediaServer} See WebMedia module.

media.source

• {WebMedia.MediaSource} See WebMedia module.

media.enableMove

• {Boolean} Whether it can control the movement of the camera.

NOTICE: some cameras support the ‘onvif.Camera interface, but do not have the movement function.

media.camLock

• {Boolean} Whether to lock camera movement.

If the media is locked, the move operation is invalid

media.camHome(cb)

• cb {Function} Callback.
  • err {Error} Error or null.

Call onvif.Camera.gotoHomePosition().

media.camMove(rx, ry, cb)

• rx {Number} Moving direction(x): -1, 0 or 1.
• • rx {Number} Moving direction(y): -1, 0 or 1.
• cb {Function} Callback.
  • err {Error} Error or null.

Call onvif.Camera.continuousMove().

media.camStop(cb)

• cb {Function} Callback.
  • err {Error} Error or null.

Call onvif.Camera.stop().

Media Events

start

• self {Media}

An start event is emitted whenmedia start.

stop

• self {Media}

An stop event is emitted whenmedia stop.

open

• self {Media}
• client {WebMedia.MediaClient} Media client object.

A client connect to media.

close

• self {Media}
• client {WebMedia.MediaClient} Media client object.

A client disconnect.

Device Object

The Device object is an integration of the onvif.device object, which is created by the Manager.

device.key

• {String} Identity of device.

device.dev

• {Object} Device information discovered by onvif. For details, please refer to @edgeros/jsre-onvif module.

device.cam

• {Cam} onvif.Cam object create by Manager. For details, please refer to @edgeros/jsre-onvif Cam.

device.streams

• {Object} A set of stream objects indexed by stream.token. The stream object records a stream media source information on device.Cam.

Stream object attributes:

• token {String} Stream token.
• url {String} The url of media source.
• profile {onvif.Cam.Profile} The profile of onvif.Cam.
• media {Media} The WebMedia server integration object. null - The media server had not been created.
• width {Integer} The width of the video resolution.
• height {Integer} The height of the video resolution.
• frameRate {Integer} The frame rate of video.

device.supportPtz

• {Boolean} Whether the device is controlled by PTZ.

device.mainStream

• {Stream} The main stream of device. You need to call device.mainStream in real time to determine whether to obtain the main stream.

Example

var stream = device.mainStream;
if (!stream) {
	console.log('The device have no main stream.');
}

device.isActive()

• returns {Boolean} Whether the device is active. true - At least one media server of Stream has been started.

device.findStream([token[, active]])

• token {String} Stream token. default to get first valid stream.
• active {Boolean} Whether stream is required to be activated, default to false. returns{Stream | undefined} require valid stream object.

Find stream object.

Example

var stream = device.findStream(token, true);

Manager Class

new medias.Manager(app, MediaClass, opts, srcOptionHandle)

• app {WebApp}
• MediaClass {Media | null} Users can implement their own Media class which inherit to Media.
• opts{Object}
  • nets {Array} Select networks to search onvif devices. default: [{ifname: 'br5', localPort: 0}].
    • ifname {String} networks.
    • localPort {Integer} 0 - auto assign port. default: 0.
  • mediaTimeout {Integer} Media server timeout. When there is no client access to media server, it will be closed after timeout. default: 18000000s.
  • searchCycle {Integer} Onvif search device cycle, . default: 30000.
  • autoGetCamera {Boolean} true - Auto create camera object when searched a device. default: true.
• srcOptionHandle {Function} This callback function is used to dynamically create the MediaSource construction selection. It receives a media options, and the returned object contains the inOpts, outOpts options, and the name of MediaSource .
  • opts {Object} Media options:
    • host {String} Media source hostname.
    • port {Integer} Media source port.
    • user {String} Media source user name.
    • pass {String} Media source password.
    • path {String} Media source path.
  • returns {Object}
    • source {String} Media source name.
    • inOpts {Object} Media source input options.
    • outPuts {Object} Media source output options.

Manager Object

mgr.destroy()

Destroy Manager object.

mgr.search()

Perform a search device operation.

mgr.addDev(devInfo[, cam])

• devInfo {Object} Onvif searched device object.
• cam {onvif.Cam} Onvif Cam object.
• returns{Object} Onvif device object.

Add onvif device.Users generally do not need to use this interface, the Manager object will automatically search for and add devices.

mgr.removeDev(dev)

• dev {onvif.device | String} Onvif device object or device key.

Remove onvif device. Users generally do not need to call this interface, the Manager object will automatically clear the devices that cannot be searched and are not activated.

mgr.findDev(key)

• key {String} Onvif device key.
• returns {Device | undefined} Found Device object.

Find onvif device by key.

mgr.iterDev(cb)

• cb {Function} Iter callback. Arguments:
  • key {String} Device key.
  • dev {Device} Device object.
• returns {Boolean} Whether there is a device object.

Iterative devices.

mgr.createStream(key[, opt[, cb]])

• key {String} Device key.
• opt {Object} Options:
  • username {String} Account user of onvif device, default to 'admin'.
  • password {String} Account password of onvif device, default to 'admin'.
• cb {Function} Callback function. Arguments:
  • error {Error | null} Return error object if operation failed.
  • streams {Object} Refer to device.streams. The media of each stream had not been created.
• returns {Promise} Promise resolve return device.streams.

Lookup device streams and register device stream objects.

Example

mgr.createStream(key, {username: 'user name', password: 'user password'}, (err, streams) => {
	if (err) {
		console.log('No stream.');
	}
});

mgr.iterStream(key, cb)

• key {String} Device key.
• cb {Function} Iter callback. Arguments:
  • token {String} Stream token.
  • stream {Object} Stream object.

Iterative device streams.

mgr.createMedia(key, token, [opt [, cb]])

• key {String} Device key.
• token {String} Device stream token.
• opt {Object} options:
  • username {String} Account user of device stream, default to device username.
  • password {String} Account password of device stream, default to device password.
• cb {Function} Callback, arguments:
  • error {Error | null} Return error object if operation failed.
  • media {Media} Media object.
• returns {Promise} Promise resolve return Media object.

Create media object.

Example

mgr.createMedia(key, token, null, (err, media) => {
	if (err) {
		console.log('Create media fail.');
	}
});

mgr.destroyMedia(key, token, [, cb])

• key {String} Device key.
• token {String} Device stream token.
• cb {Function} Callback, arguments: ret {Boolean} Destroy success or not.

Destroy meida object.

mgr.findMedia(key, token)

• key {String} Device key.
• token {String} Device stream token.
• returns *{Media | undefined}

Find media. Return undefined if media not exits.

Manager Events

open

• Media {Media}

A media object is created and started.

close

• media {Media}

A media object stopped.

Example

function srcHandle(opts) {
	return {
		source: 'source-name', // User defined source.
		inOpts: { 
			// User source defined options.
		},
		outOpts: {
			// User source defined options.
		}
	}
}

var mediaMgr = new Manager(app, null, null, srcHandle);
mediaMgr.on('open', (media) => {
	media.on('open', (media, client) => {
		client.on('camera-move', (client, x, y, cb) => { // User defined event.
			media.camMove(x, y, (err) => {
				if (err) {
					cb({ result: false, msg: err.message });
				} else {
					cb({ result: true, msg: 'ok' });
				}
			});
		});

		client.on('camera-stop', (client, cb) => { // User defined event.
			media.camStop((err) => {
				if (err) {
					cb({ result: false, msg: err.message });
				} else {
					cb({ result: true, msg: 'ok' });
				}
			});
		});
	});
});