kurento-client-filters/lib/GStreamerFilter.js

JavaScript Client API for Kurento Media Server

/* Autogenerated with Kurento Idl */

/*
 * (C) Copyright 2013-2015 Kurento (https://kurento.openvidu.io/)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

var inherits = require('inherits');

var kurentoClient = require('kurento-client');

var disguise = kurentoClient.disguise;

var checkType      = kurentoClient.checkType;
var ChecktypeError = checkType.ChecktypeError;


var Transaction = kurentoClient.TransactionsManager.Transaction;

var Filter = require('kurento-client-core').abstracts.Filter;


function noop(error, result) {
  if (error) console.trace(error);

  return result
};


/**
 * Create a {@link GStreamerFilter}.
 *
 * @classdesc
 *  A generic filter that allows injecting a single GStreamer element.
 *  <p>
 *    The current implementation of GStreamerFilter only allows single elements 
 *    to
 *    be injected; one cannot indicate more than one at the same time; use 
 *    several
 *    GStreamerFilters if you need to inject more than one element into the
 *    pipeline.
 *  </p>
 *  <p>
 *    Note that usage of some popular GStreamer elements requires installation 
 *    of
 *    additional packages. For example, overlay elements such as
 *    <em>timeoverlay</em> or <em>textoverlay</em> require installation of the
 *    <strong>gstreamer1.0-x</strong> package, which will also install the
 *    <em>Pango</em> rendering library.
 *  </p>
 *
 * @extends module:core/abstracts.Filter
 *
 * @constructor module:filters.GStreamerFilter
 */
function GStreamerFilter(){
  GStreamerFilter.super_.call(this);
};
inherits(GStreamerFilter, Filter);


//
// Public properties
//

/**
 * String used to instantiate the GStreamer element, as in gst-launch 
 * (https://gstreamer.freedesktop.org/documentation/tools/gst-launch.html).
 *
 * @alias module:filters.GStreamerFilter#getCommand
 *
 * @param {module:filters.GStreamerFilter~getCommandCallback} [callback]
 *
 * @return {external:Promise}
 */
GStreamerFilter.prototype.getCommand = function(callback){
  var transaction = (arguments[0] instanceof Transaction)
                  ? Array.prototype.shift.apply(arguments)
                  : undefined;

  var usePromise = false;
  
  if (callback == undefined) {
    usePromise = true;
  }
  
  if(!arguments.length) callback = undefined;

  callback = (callback || noop).bind(this)

  return disguise(this._invoke(transaction, 'getCommand', callback), this)
};
/**
 * @callback module:filters.GStreamerFilter~getCommandCallback
 * @param {external:Error} error
 * @param {external:String} result
 */


//
// Public methods
//

/**
 * Provide a value to one of the GStreamer element's properties.
 *
 * @alias module:filters.GStreamerFilter.setElementProperty
 *
 * @param {external:String} propertyName
 *  Name of the property that needs to be modified in the GStreamer element.
 *
 * @param {external:String} propertyValue
 *  Value that must be assigned to the property.
 *
 * @param {module:filters.GStreamerFilter~setElementPropertyCallback} [callback]
 *
 * @return {external:Promise}
 */
GStreamerFilter.prototype.setElementProperty = function(propertyName, propertyValue, callback){
  var transaction = (arguments[0] instanceof Transaction)
                  ? Array.prototype.shift.apply(arguments)
                  : undefined;

  //  
  // checkType('String', 'propertyName', propertyName, {required: true});
  //  
  // checkType('String', 'propertyValue', propertyValue, {required: true});
  //  

  var params = {
    propertyName: propertyName,
    propertyValue: propertyValue
  };

  callback = (callback || noop).bind(this)

  return disguise(this._invoke(transaction, 'setElementProperty', params, callback), this)
};
/**
 * @callback module:filters.GStreamerFilter~setElementPropertyCallback
 * @param {external:Error} error
 */


/**
 * @alias module:filters.GStreamerFilter.constructorParams
 *
 * @property {external:String} command
 *  String used to instantiate the GStreamer element, as in gst-launch 
 *  (https://gstreamer.freedesktop.org/documentation/tools/gst-launch.html).
 *
 * @property {external:FilterType} [filterType]
 *  Sets the filter as Audio, Video, or Autodetect.
 *
 * @property {module:core.MediaPipeline} mediaPipeline
 *  the {@link MediaPipeline} to which the filter belongs
 */
GStreamerFilter.constructorParams = {
  command: {
    type: 'String',
    required: true
  },
  filterType: {
    type: 'kurento.FilterType'  },
  mediaPipeline: {
    type: 'kurento.MediaPipeline',
    required: true
  }
};

/**
 * @alias module:filters.GStreamerFilter.events
 *
 * @extends module:core/abstracts.Filter.events
 */
GStreamerFilter.events = Filter.events;


/**
 * Checker for {@link module:filters.GStreamerFilter}
 *
 * @memberof module:filters
 *
 * @param {external:String} key
 * @param {module:filters.GStreamerFilter} value
 */
function checkGStreamerFilter(key, value)
{
  if(!(value instanceof GStreamerFilter))
    throw ChecktypeError(key, GStreamerFilter, value);
};


module.exports = GStreamerFilter;

GStreamerFilter.check = checkGStreamerFilter;