kurento-client-elements

{ "name": "elements", "version": "7.2.0", "kurentoVersion": "^7.1.0", "imports": [ { "name": "core", "version": "^7.1.0", "mavenVersion": "[7.1.0,8.0.0-SNAPSHOT)", "npmVersion": ">=7.1.0 <8.0.0" } ], "code": { "kmd": { "java": { "mavenGroupId": "org.kurento", "mavenArtifactId": "kms-api-elements", "mavenVersion": "7.2.0" } }, "api": { "java": { "packageName": "org.kurento.client", "mavenGroupId": "org.kurento", "mavenArtifactId": "kurento-client", "mavenVersion": "7.2.0" }, "js": { "nodeName": "kurento-client-elements", "npmDescription": "JavaScript Client API for Kurento Media Server", "npmGit": "https://github.com/Kurento/kurento-client-elements-js.git", "npmVersion": "7.2.0" } }, "implementation": { "cppNamespace": "kurento", "lib": "libkmselements" } }, "remoteClasses": [ { "name": "AlphaBlending", "doc": "A :rom:cls:`Hub` that mixes the :rom:attr:`MediaType.AUDIO` stream of its connected sources and constructs one output with :rom:attr:`MediaType.VIDEO` streams of its connected sources into its sink", "extends": "Hub", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the dispatcher belongs", "type": "MediaPipeline" } ], "doc": "Create for the given pipeline" }, "methods": [ { "params": [ { "name": "source", "doc": "The reference to the HubPort setting as master port", "type": "HubPort" }, { "name": "zOrder", "doc": "The order in z to draw the master image", "type": "int" } ], "name": "setMaster", "doc": "Sets the source port that will be the master entry to the mixer" }, { "params": [ { "name": "relativeX", "doc": "The x position relative to the master port. Values from 0 to 1 are accepted. The value 0, indicates the coordinate 0 in the master image.", "type": "float" }, { "name": "relativeY", "doc": "The y position relative to the master port. Values from 0 to 1 are accepted. The value 0, indicates the coordinate 0 in the master image.", "type": "float" }, { "name": "zOrder", "doc": "The order in z to draw the images. The greatest value of z is in the top.", "type": "int" }, { "name": "relativeWidth", "doc": "The image width relative to the master port width. Values from 0 to 1 are accepted.", "type": "float" }, { "name": "relativeHeight", "doc": "The image height relative to the master port height. Values from 0 to 1 are accepted.", "type": "float" }, { "name": "port", "doc": "The reference to the confingured port.", "type": "HubPort" } ], "name": "setPortProperties", "doc": "Configure the blending mode of one port." } ] }, { "name": "Composite", "doc": "A :rom:cls:`Hub` that mixes the :rom:attr:`MediaType.AUDIO` stream of its connected sources and constructs a grid with the :rom:attr:`MediaType.VIDEO` streams of its connected sources into its sink", "extends": "Hub", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the dispatcher belongs", "type": "MediaPipeline" }, { "name": "width", "doc": "screen width", "type": "int", "optional": true, "defaultValue": 800 }, { "name": "height", "doc": "screen height", "type": "int", "optional": true, "defaultValue": 600 }, { "name": "framerate", "doc": "frames per second", "type": "int", "optional": true, "defaultValue": 15 } ], "doc": "Create for the given pipeline" } }, { "name": "Dispatcher", "doc": "A :rom:cls:`Hub` that allows routing between arbitrary port pairs", "extends": "Hub", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the dispatcher belongs", "type": "MediaPipeline" } ], "doc": "Create a :rom:cls:`Dispatcher` belonging to the given pipeline." }, "methods": [ { "params": [ { "name": "source", "doc": "Source port to be connected", "type": "HubPort" }, { "name": "sink", "doc": "Sink port to be connected", "type": "HubPort" } ], "name": "connect", "doc": "Connects each corresponding :rom:enum:`MediaType` of the given source port with the sink port." } ] }, { "name": "DispatcherOneToMany", "doc": "A :rom:cls:`Hub` that sends a given source to all the connected sinks", "extends": "Hub", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the dispatcher belongs", "type": "MediaPipeline" } ], "doc": "Create a :rom:cls:`DispatcherOneToMany` belonging to the given pipeline." }, "methods": [ { "params": [ { "name": "source", "doc": "source to be broadcasted", "type": "HubPort" } ], "name": "setSource", "doc": "Sets the source port that will be connected to the sinks of every :rom:cls:`HubPort` of the dispatcher" }, { "params": [], "name": "removeSource", "doc": "Remove the source port and stop the media pipeline." } ] }, { "name": "HttpEndpoint", "doc": "Endpoint that enables Kurento to work as an HTTP server, allowing peer HTTP clients to access media.", "abstract": true, "extends": "SessionEndpoint", "methods": [ { "params": [], "return": { "type": "String", "doc": "The url as a String" }, "name": "getUrl", "doc": "Obtains the URL associated to this endpoint" } ] }, { "name": "HttpPostEndpoint", "doc": "An :rom:cls:`HttpPostEndpoint` contains SINK pads for AUDIO and VIDEO, which provide access to an HTTP file upload function\n\n This type of endpoint provide unidirectional communications. Its MediaSource are accessed through the HTTP POST method.", "extends": "HttpEndpoint", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the endpoint belongs", "type": "MediaPipeline" }, { "name": "disconnectionTimeout", "doc": "This is the time that an http endpoint will wait for a reconnection, in case an HTTP connection is lost.", "type": "int", "optional": true, "defaultValue": 2 }, { "name": "useEncodedMedia", "doc": "Feed the input media as-is to the Media Pipeline, instead of first decoding it.\n \n When this property is not enabled, the input media gets always decoded into a raw format before being processed by the rest of the Media Pipeline; this is done to ensure that Kurento is able to keep track of lost keyframes among other quality-control measurements. Of course, having to decode the media has a cost in terms of CPU usage, but ensures that the output streaming will be robust and reliable.\n \n \n When this property is enabled, the explained behavior gets disabled. Instead, The endpoint will provide any input media directly to the Media Pipeline, without prior decoding. Enabling this mode of operation could have a severe effect on stability, because lost video keyframes will not be regenerated; however, avoiding a full cycle of decoding and encoding can be very useful for certain applications, because it improves performance by greatly reducing the CPU processing load.\n \n \n Keep in mind that if this property is enabled, the original source media MUST already have an encoding format which is compatible with the destination target. For example: given a pipeline which uses this endpoint to read a file and then streams it to a WebRTC browser such as Chrome, then the file must already be encoded with a VP8 or H.264 codec profile which Chrome is able to decode. Note that for this example, most browsers don't support ANY combination of H.264 encoding options; instead, they tend to support only a very specific subset of the codec features (also known as 'profiles').\n \n \n We strongly recommend to avoid using this option, because correct behavior cannot be guaranteed.\n \n ", "type": "boolean", "optional": true, "defaultValue": false } ], "doc": "Builder for the :rom:cls:`HttpPostEndpoint`." }, "events": [ "EndOfStream" ] }, { "name": "Mixer", "doc": "A :rom:cls:`Hub` that allows routing of video between arbitrary port pairs and mixing of audio among several ports", "extends": "Hub", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the Mixer belongs", "type": "MediaPipeline" } ], "doc": "Create a :rom:cls:`Mixer` belonging to the given pipeline." }, "methods": [ { "params": [ { "name": "media", "doc": "The sort of media stream to be connected", "type": "MediaType" }, { "name": "source", "doc": "Source port to be connected", "type": "HubPort" }, { "name": "sink", "doc": "Sink port to be connected", "type": "HubPort" } ], "name": "connect", "doc": "Connects each corresponding :rom:enum:`MediaType` of the given source port with the sink port." }, { "params": [ { "name": "media", "doc": "The sort of media stream to be disconnected", "type": "MediaType" }, { "name": "source", "doc": "Audio source port to be disconnected", "type": "HubPort" }, { "name": "sink", "doc": "Audio sink port to be disconnected", "type": "HubPort" } ], "name": "disconnect", "doc": "Disonnects each corresponding :rom:enum:`MediaType` of the given source port from the sink port." } ] }, { "name": "PlayerEndpoint", "doc": "Retrieves content from external sources.\n\n PlayerEndpoint will access the given resource, read all available data, and\n inject it into Kurento. Once this is is done, the injected video or audio will\n be available for passing through any other Filter or Endpoint to which the\n PlayerEndpoint gets connected.\n\n\n The source can provide either seekable or non-seekable media; this will\n dictate whether the PlayerEndpoint is able (or not) to seek through the file,\n for example to jump to any given timestamp.\n\nThe Source URI supports these formats:\n<ul>\n <li>\n File: A file path that will be read from the local file system. Example:\n <ul>\n <li><code>file:///path/to/file</code></li>\n </ul>\n </li>\n <li>\n HTTP: Any file available in an HTTP server. Examples:\n <ul>\n <li><code>http(s)://host/path/to/file</code></li>\n <li>\n <code>\n http(s)://username:password@host:port/path/to/file\n </code>\n </li>\n </ul>\n </li>\n <li>\n RTSP: Typically used to capture a feed from an IP Camera. Examples:\n <ul>\n <li><code>rtsp://host</code></li>\n <li>\n <code>\n rtsp://username:password@host:port/path/to/file?key=value&key=value\n </code>\n </li>\n </ul>\n </li>\n <li>\n \n NOTE: Special characters must be\n <a href='https://en.wikipedia.org/wiki/Query_string#URL_encoding'>\n URL-encoded\n </a>\n in <code>username</code> and <code>password</code> fields.\n \n </li>\n</ul>\n\n Note that\n PlayerEndpoint requires read permissions to the source \n ; otherwise, the media server won't be able to retrieve any data, and an\n :rom:evt:`Error` will be fired. Make sure your application subscribes to this\n event, otherwise troubleshooting issues will be difficult.\n\n\nThe list of valid operations is:\n<ul>\n <li>\n <code>play</code>\n : Starts streaming media. If invoked after pause, it will resume playback.\n </li>\n <li>\n <code>stop</code>\n : Stops streaming media. If play is invoked afterwards, the file will be\n streamed from the beginning.\n </li>\n <li>\n <code>pause</code>\n : Pauses media streaming. Play must be invoked in order to resume playback.\n </li>\n <li>\n <code>seek</code>\n : If the source supports seeking to a different time position, then the\n PlayerEndpoint can:\n <ul>\n <li>\n <code>setPosition</code>\n : Allows to set the position in the file.\n </li>\n <li>\n <code>getPosition</code>\n : Returns the current position being streamed.\n </li>\n </ul>\n </li>\n</ul>\n<h2>Events fired</h2>\n<ul>\n <li>\n EndOfStreamEvent: If the file is streamed completely.\n </li>\n</ul>\n ", "extends": "UriEndpoint", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "The :rom:cls:`MediaPipeline` this PlayerEndpoint belongs to.", "type": "MediaPipeline" }, { "name": "uri", "doc": "URI pointing to the video. It has to be accessible to the KMS process.\n <ul>\n <li>Local resources: The user running the Kurento Media Server must have read permission over the file.</li>\n <li>Remote resources: Must be accessible from the server where the media server is running.</li>\n </ul>", "type": "String" }, { "name": "useEncodedMedia", "doc": "Feed an encoded media as-is to the Media Pipeline, instead of first decoding it.\n \n This property is disabled by default. The input media gets always decoded into\n a raw format upon receiving it, before being processed by the rest of the\n Media Pipeline. This is done to ensure that Kurento is able to keep track of\n lost keyframes among other quality-control measurements. Of course, having to\n decode the media has a cost in terms of CPU usage, but ensures that the output\n streaming will be more robust and reliable.\n \n \n When this property is enabled, Kurento simply passes the encoded media as-is\n to the rest of the Media Pipeline, without decoding. Enabling this mode of\n operation could have a severe effect on stability, because lost video\n keyframes will not be regenerated; however, not having to encode the video\n greatly reduces the CPU load.\n \n \n Keep in mind that if this property is enabled, the original source media MUST\n already be in a format that is compatible with the destination target. For\n example: Given a Pipeline that reads a file and then streams it to a WebRTC\n browser such as Chrome, the file must already be encoded with a VP8 or H.264\n codec profile, which Chrome is able to decode.\n \n \n Of special note is that you cannot feed any random combination of H.264\n encoding options to a web browser; instead, they tend to support only a very\n specific subset of the codec features (also known as 'profiles'). The most\n compatible config for H.264 is\n Constrained Baseline profile, level 3.1.\n \n Code examples:\n <pre><code>\n # Java\n PlayerEndpoint player = new PlayerEndpoint\n .Builder(pipeline, 'rtsp://localhost:5000/video')\n .useEncodedMedia()\n .build();\n </code></pre>\n <pre><code>\n # JavaScript\n let player = await pipeline.create('PlayerEndpoint', {\n uri: 'rtsp://localhost:5000/video',\n useEncodedMedia: true,\n });\n </code></pre>\n ", "type": "boolean", "optional": true, "defaultValue": false }, { "name": "networkCache", "doc": "RTSP buffer length.\n\n When receiving media from an RTSP source, the streamed video can suffer spikes\n or stuttering, caused by hardware or network issues. Having a reception buffer\n helps alleviate these problems, because it smoothes the stream of incoming\n data to the receiving endpoint.\n\n\n Finding a buffer length that works best for your connection might take some\n tweaking, which can be done with this optional property. Note that a longer\n buffer will be able to fix bigger network spikes, but at the cost of\n introducing more latency to the media playback.\n\n<ul>\n <li>Unit: milliseconds.</li>\n <li>Default: 2000.</li>\n</ul>\n ", "type": "int", "optional": true, "defaultValue": 2000 } ], "doc": "Create a PlayerEndpoint" }, "properties": [ { "name": "videoInfo", "doc": "Returns info about the source being played", "type": "VideoInfo", "readOnly": true }, { "name": "elementGstreamerDot", "doc": "Returns the GStreamer DOT string for this element's private pipeline", "type": "String", "readOnly": true }, { "name": "position", "doc": "Get or set the actual position of the video in ms. .. note:: Setting the position only works for seekable videos", "type": "int64" } ], "methods": [ { "params": [], "name": "play", "doc": "Starts reproducing the media, sending it to the :rom:cls:`MediaSource`. If the endpoint\n\n has been connected to other endpoints, those will start receiving media." } ], "events": [ "EndOfStream" ] }, { "name": "RecorderEndpoint", "doc": "Provides functionality to store media contents.\n\n RecorderEndpoint can store media into local files or send it to a remote\n network storage. When another :rom:cls:`MediaElement` is connected to a\n RecorderEndpoint, the media coming from the former will be muxed into the\n selected recording format and stored in the designated location.\n\n\n These parameters must be provided to create a RecorderEndpoint, and they\n cannot be changed afterwards:\n\n<ul>\n <li>\n Destination URI, where media will be stored. These formats\n are supported:\n <ul>\n <li>\n File: A file path that will be written into the local file system.\n Example:\n <ul>\n <li><code>file:///path/to/file</code></li>\n </ul>\n </li>\n <li>\n HTTP: A POST request will be used against a remote server. The server\n must support using the chunked encoding mode (HTTP header\n <code>Transfer-Encoding: chunked</code>). Examples:\n <ul>\n <li><code>http(s)://host/path/to/file</code></li>\n <li>\n <code>\n http(s)://username:password@host:port/path/to/file\n </code>\n </li>\n </ul>\n </li>\n <li>\n Relative URIs (with no schema) are supported. They are completed by\n prepending a default URI defined by property defaultPath. This\n property is defined in the configuration file\n /etc/kurento/modules/kurento/UriEndpoint.conf.ini, and the\n default value is <code>file:///var/lib/kurento/</code>\n </li>\n <li>\n \n NOTE: Special characters must be\n <a href='https://en.wikipedia.org/wiki/Query_string#URL_encoding'>\n URL-encoded\n </a>\n in <code>username</code> and <code>password</code> fields.\n \n </li>\n </ul>\n </li>\n <li>\n Media Profile (:rom:enum:`MediaProfileSpecType`), which\n determines the video and audio encoding. See below for more details.\n </li>\n <li>\n EndOfStream (optional), a parameter that dictates if the\n recording should be automatically stopped once the EOS event is detected.\n </li>\n</ul>\n\n Note that\n \n RecorderEndpoint requires write permissions to the destination\n \n ; otherwise, the media server won't be able to store any information, and an\n :rom:evt:`Error` will be fired. Make sure your application subscribes to this\n event, otherwise troubleshooting issues will be difficult.\n\n<ul>\n <li>\n To write local files (if you use <code>file://</code>), the system user that\n is owner of the media server process needs to have write permissions for the\n requested path. By default, this user is named '<code>kurento</code>'.\n </li>\n <li>\n To record through HTTP, the remote server must be accessible through the\n network, and also have the correct write permissions for the destination\n path.\n </li>\n</ul>\n\n Recording will start as soon as the user invokes the\n <code>record()</code> method. The recorder will then store, in the location\n indicated, the media that the source is sending to the endpoint. If no media\n is being received, or no endpoint has been connected, then the destination\n will be empty. The recorder starts storing information into the file as soon\n as it gets it.\n\n\n Recording must be stopped when no more data should be stored.\n This is done with the <code>stopAndWait()</code> method, which blocks and\n returns only after all the information was stored correctly.\n\n\n The source endpoint can be hot-swapped while the recording is taking place.\n The recorded file will then contain different feeds. When switching video\n sources, if the new video has different size, the recorder will retain the\n size of the previous source. If the source is disconnected, the last frame\n recorded will be shown for the duration of the disconnection, or until the\n recording is stopped.\n\n\n \n NOTE: It is recommended to start recording only after media arrives.\n \n For this, you may use the <code>MediaFlowInStateChanged</code> and\n <code>MediaFlowOutStateChanged</code>\n events of your endpoints, and synchronize the recording with the moment media\n comes into the Recorder.\n\n\n \n WARNING: All connected media types must be flowing to the RecorderEndpoint.\n \n If you used the default <code>connect()</code> method, it will assume both\n AUDIO and VIDEO. Failing to provide both kinds of media will result in the\n RecorderEndpoint creating an empty file and buffering indefinitely; the\n recorder waits until all kinds of media start arriving, in order to\n synchronize them appropriately. \n For audio-only or video-only recordings, make sure to use the correct,\n media-specific variant of the <code>connect()</code> method.\n\nFor example:\n<ol>\n <li>\n When a web browser's video arrives to Kurento via WebRTC, your\n WebRtcEndpoint will emit a <code>MediaFlowOutStateChanged</code> event.\n </li>\n <li>\n When video starts flowing from the WebRtcEndpoint to the RecorderEndpoint,\n the RecorderEndpoint will emit a <code>MediaFlowInStateChanged</code> event.\n You should start recording at this point.\n </li>\n <li>\n You should only start recording when RecorderEndpoint has notified a\n <code>MediaFlowInStateChanged</code> for ALL streams. So, if you record\n AUDIO+VIDEO, your application must receive a\n <code>MediaFlowInStateChanged</code> event for audio, and another\n <code>MediaFlowInStateChanged</code> event for video.\n </li>\n</ol>\n ", "extends": "UriEndpoint", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the endpoint belongs", "type": "MediaPipeline" }, { "name": "uri", "doc": "URI where the recording will be stored. It must be accessible from the media server process itself:\n <ul>\n <li>Local server resources: The user running the Kurento Media Server must have write permission over the file.</li>\n <li>Network resources: Must be accessible from the network where the media server is running.</li>\n </ul>", "type": "String" }, { "name": "mediaProfile", "doc": "Selects the media format used for recording.\n\n The media profile allows you to specify which codecs and media container will\n be used for the recordings. This is currently the only way available to tell\n Kurento about which codecs should be used.\n\n\n Watch out for these important remarks:\n\n<ul>\n <li>\n If the format of incoming media differs from the recording profile, media\n will need to be transcoded. Transcoding always incurs in noticeable CPU\n load, so it is always good trying to avoid it. For instance, if a\n VP8-encoded video (from WebRTC) is recorded with an MP4 recording profile\n (which means H.264 encoding), the video needs to be transcoded from VP8 to\n H.264. On the other hand, recording with the WEBM profile would allow to\n store the video as-is with its VP8 encoding.\n </li>\n <li>\n If you intend to record audio-only or video-only media, select the\n appropriate <code>_AUDIO_ONLY</code> or <code>_VIDEO_ONLY</code> profile.\n For example, to record a WebRTC screen capture (as obtained from a web\n browser's call to <code>MediaDevices.getDisplayMedia()</code>), choose\n <code>WEBM_VIDEO_ONLY</code> instead of just <code>WEBM</code>.\n </li>\n</ul>\n ", "type": "MediaProfileSpecType", "optional": true, "defaultValue": "WEBM" }, { "name": "stopOnEndOfStream", "doc": "Forces the recorder endpoint to finish processing data when an End Of Stream (EOS) is detected in the stream", "type": "boolean", "optional": true, "defaultValue": false } ], "doc": "Builder for the :rom:cls:`RecorderEndpoint`" }, "methods": [ { "params": [], "name": "record", "doc": "Starts storing media received through the sink pad." }, { "params": [], "name": "stopAndWait", "doc": "Stops recording and does not return until all the content has been written to the selected uri. This can cause timeouts on some clients if there is too much content to write, or the transport is slow" } ], "events": [ "Recording", "Paused", "Stopped" ] }, { "name": "RtpEndpoint", "doc": "\nEndpoint that provides bidirectional content delivery capabilities through the\nRTP or SRTP protocols.\n\n An :rom:cls:`RtpEndpoint` contains paired sink and source :rom:cls:`MediaPad`\n for audio and video. This endpoint inherits from :rom:cls:`BaseRtpEndpoint`.\n\n\n In order to establish RTP/SRTP communications, peers first engage in an SDP\n Offer/Answer negotiation process, where one of the peers (the offerer) sends\n an SDP Offer, while the other peer (the answerer) responds with an SDP Answer.\n This endpoint can work in both roles.\n\n<ul>\n <li>\n As offerer: The negotiation process is initiated by the media server.\n <ul>\n <li>\n Kurento generates the SDP Offer through the\n <code>generateOffer()</code> method. This offer must then be sent to the\n remote peer (the answerer) through the signaling channel.\n </li>\n <li>\n The remote peer process the SDP Offer, and generates an SDP Answer. This\n answer is then sent back to the media server.\n </li>\n <li>\n Upon receiving the SDP Answer, this endpoint must process it with the\n <code>processAnswer()</code> method.\n </li>\n </ul>\n </li>\n <li>\n As answerer: The negotiation process is initiated by the remote peer.\n <ul>\n <li>\n The remote peer, acting as offerer, generates an SDP Offer and sends it\n to this endpoint.\n </li>\n <li>\n This endpoint processes the SDP Offer with the\n <code>processOffer()</code> method. The result of this method will be a\n string, containing an SDP Answer.\n </li>\n <li>\n The SDP Answer must then be sent back to the offerer, so it can be\n processed by it.\n </li>\n </ul>\n </li>\n</ul>\n\n In case of unidirectional connections (i.e. only one peer is going to send\n media), the process is simpler, as only the sender needs to process an SDP\n Offer. On top of the information about media codecs and types, the SDP must\n contain the IP of the remote peer, and the port where it will be listening.\n This way, the SDP can be mangled without needing to go through the exchange\n process, as the receiving peer does not need to process any answer.\n\n<h2>Bitrate management</h2>\n\n Check the documentation of :rom:cls:`BaseRtpEndpoint` for detailed information\n about bitrate management.\n\n ", "extends": "BaseRtpEndpoint", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the endpoint belongs", "type": "MediaPipeline" }, { "name": "crypto", "doc": "SDES-type param. If present, this parameter indicates that the communication will be encrypted. By default no encryption is used.", "type": "SDES", "optional": true, "defaultValue": {} }, { "name": "useIpv6", "doc": "This configures the endpoint to use IPv6 instead of IPv4.", "type": "boolean", "optional": true, "defaultValue": false } ], "doc": "Builder for the :rom:cls:`RtpEndpoint`" }, "events": [ "OnKeySoftLimit" ] }, { "name": "WebRtcEndpoint", "doc": "\nEndpoint that provides bidirectional WebRTC capabilities for Kurento.\n\n This endpoint is one side of a peer-to-peer WebRTC communication, where the\n other peer is either of a WebRTC capable browser (using the\n RTCPeerConnection API), a native WebRTC app, or even another Kurento\n Media Server instance.\n\n\n In order to establish WebRTC communications, peers first engage in an SDP\n Offer/Answer negotiation process, where one of the peers (the offerer) sends\n an SDP Offer, while the other peer (the answerer) responds with an SDP Answer.\n This endpoint can work in both roles.\n\n<ul>\n <li>\n As offerer: The negotiation process is initiated by the media server.\n <ul>\n <li>\n Kurento generates the SDP Offer through the\n <code>generateOffer()</code> method. This offer must then be sent to the\n remote peer (the answerer) through the signaling channel.\n </li>\n <li>\n The remote peer process the SDP Offer, and generates an SDP Answer. This\n answer is then sent back to the media server.\n </li>\n <li>\n Upon receiving the SDP Answer, this endpoint must process it with the\n <code>processAnswer()</code> method.\n </li>\n </ul>\n </li>\n <li>\n As answerer: The negotiation process is initiated by the remote peer.\n <ul>\n <li>\n The remote peer, acting as offerer, generates an SDP Offer and sends it\n to this endpoint.\n </li>\n <li>\n This endpoint processes the SDP Offer with the\n <code>processOffer()</code> method. The result of this method will be a\n string, containing an SDP Answer.\n </li>\n <li>\n The SDP Answer must then be sent back to the offerer, so it can be\n processed by it.\n </li>\n </ul>\n </li>\n</ul>\n<h2>ICE candidates and connectivity checks</h2>\n\n SDPs are sent without ICE candidates, following the Trickle ICE optimization.\n Once the SDP negotiation is completed, both peers proceed with the ICE\n discovery process, intended to set up a bidirectional media connection. During\n this process, each peer...\n\n<ul>\n <li>\n Discovers ICE candidates for itself, containing pairs of IPs and ports.\n </li>\n <li>\n ICE candidates are sent via the signaling channel as they are discovered, to\n the remote peer for probing.\n </li>\n <li>\n ICE connectivity checks are run as soon as the new candidate description,\n from the remote peer, is available.\n </li>\n</ul>\n\n Once a suitable pair of candidates (one for each peer) is discovered, the\n media session can start. The harvesting process in Kurento, begins with the\n invocation of the <code>gatherCandidates()</code> method. Since the whole\n Trickle ICE purpose is to speed-up connectivity, candidates are generated\n asynchronously. Therefore, in order to capture the candidates, the user must\n subscribe to the event <code>IceCandidateFound</code>. It is important that\n the event listener is bound before invoking <code>gatherCandidates()</code>,\n otherwise a suitable candidate might be lost, and connection might not be\n established.\n\n\n It is important to keep in mind that WebRTC connection is an asynchronous\n process, when designing interactions between different MediaElements. For\n example, it would be pointless to start recording before media is flowing. In\n order to be notified of state changes, the application can subscribe to events\n generated by the WebRtcEndpoint. Following is a full list of events generated\n by WebRtcEndpoint:\n\n<ul>\n <li>\n <code>IceComponentStateChanged</code>: This event informs only about changes\n in the ICE connection state. Possible values are:\n <ul>\n <li><code>DISCONNECTED</code>: No activity scheduled</li>\n <li><code>GATHERING</code>: Gathering local candidates</li>\n <li><code>CONNECTING</code>: Establishing connectivity</li>\n <li><code>CONNECTED</code>: At least one working candidate pair</li>\n <li>\n <code>READY</code>: ICE concluded, candidate pair selection is now final\n </li>\n <li>\n <code>FAILED</code>: Connectivity checks have been completed, but media\n connection was not established\n </li>\n </ul>\n The transitions between states are covered in RFC5245. It could be said that\n it is network-only, as it only takes into account the state of the network\n connection, ignoring other higher level stuff, like DTLS handshake, RTCP\n flow, etc. This implies that, while the component state is\n <code>CONNECTED</code>, there might be no media flowing between the peers.\n This makes this event useful only to receive low-level information about the\n connection between peers. Even more, while other events might leave a\n graceful period of time before firing, this event fires immediately after\n the state change is detected.\n </li>\n <li>\n <code>IceCandidateFound</code>: Raised when a new candidate is discovered.\n ICE candidates must be sent to the remote peer of the connection. Failing to\n do so for some or all of the candidates might render the connection\n unusable.\n </li>\n <li>\n <code>IceGatheringDone</code>: Raised when the ICE gathering process is\n completed. This means that all candidates have already been discovered.\n </li>\n <li>\n <code>NewCandidatePairSelected</code>: Raised when a new ICE candidate pair\n gets selected. The pair contains both local and remote candidates being used\n for a component. This event can be raised during a media session, if a new\n pair of candidates with higher priority in the link are found.\n </li>\n <li><code>DataChannelOpened</code>: Raised when a data channel is open.</li>\n <li><code>DataChannelClosed</code>: Raised when a data channel is closed.</li>\n</ul>\n\n Registering to any of above events requires the application to provide a\n callback function. Each event provides different information, so it is\n recommended to consult the signature of the event listeners.\n\n<h2>Bitrate management and network congestion control</h2>\n\n Congestion control is one of the most important features of WebRTC. WebRTC\n connections start with the lowest bandwidth configured and slowly ramps up to\n the maximum available bandwidth, or to the higher limit of the allowed range\n in case no bandwidth limitation is detected.\n\n\n Notice that WebRtcEndpoints in Kurento are designed in a way that\n \n multiple WebRTC connections fed by the same stream, share the same bitrate\n limits.\n \n When a new connection is added, as it requires to start with low bandwidth, it\n will cause the rest of connections to experience a transient period of\n degraded quality, until it stabilizes its bitrate. This doesn't apply when\n transcoding is involved; transcoders will adjust their output bitrate based in\n the receiver requirements, but it won't affect the original stream.\n\n\n If an incoming WebRTC stream needs to be transcoded, for whatever reason, all\n WebRtcEndpoints fed from the transcoder output will share a separate quality\n than the ones connected directly to the original stream.\n\n\n \n Note that the default MaxVideoSendBandwidth is a VERY conservative\n value, and leads to a low maximum video quality. Most applications will\n probably want to increase this to higher values such as 2000 kbps (2 Mbps).\n \n Check the documentation of :rom:cls:`BaseRtpEndpoint` and\n :rom:cls:`RembParams` for detailed information about bitrate management.\n\n<h3>Keyframe requests (PLI/FIR)</h3>\n\n WebRTC allows receivers to emit keyframe requests for the senders, by means of\n RTCP Feedback messages called PLI (Picture Loss Indication) and/or FIR (Full\n Intra-frame Request). Kurento supports this mechanism: PLI and FIR requests\n that are emitted by a receiver will be forwarded to the sender. This way, the\n encoder of the video (e.g. a web browser) can decide if a new keyframe should\n be generated. Sometimes Kurento itself acts as encoder when transcoding is\n enabled, so in this case it is Kurento itself the one generating keyframes.\n\n\n On top of this, a common technique used for streaming is to forcefully request\n new keyframes. Either in fixed intervals, or explicitly by the application.\n Kurento doesn't support the former, but the latter is possible by calling\n <code>requestKeyframe()</code> from a subscribing element (i.e. an endpoint\n that sends data out from the Kurento Pipeline).\n\n<h2>WebRTC Data Channels</h2>\n\n DataChannels allow other media elements that make use of the DataPad, to send\n arbitrary data. For instance, if there is a filter that publishes event\n information, it will be sent to the remote peer through the channel. There is\n no API available for programmers to make use of this feature in the\n WebRtcElement. DataChannels can be configured to provide the following:\n\n<ul>\n <li>Reliable or partially reliable delivery of sent messages</li>\n <li>In-order or out-of-order delivery of sent messages</li>\n</ul>\n\n Unreliable, out-of-order delivery is equivalent to raw UDP semantics. The\n message may make it, or it may not, and order is not important. However, the\n channel can be configured to be partially reliable by specifying the\n maximum number of retransmissions or setting a time limit for retransmissions:\n the WebRTC stack will handle the acknowledgments and timeouts.\n\n\n The possibility to create DataChannels in a WebRtcEndpoint must be explicitly\n enabled when creating the endpoint, as this feature is disabled by default. If\n this is the case, they can be created invoking the createDataChannel method.\n The arguments for this method, all of them optional, provide the necessary\n configuration:\n\n<ul>\n <li>\n <code>label</code>: assigns a label to the DataChannel. This can help\n identify each possible channel separately.\n </li>\n <li>\n <code>ordered</code>: specifies if the DataChannel guarantees order, which\n is the default mode. If maxPacketLifetime and maxRetransmits have not been\n set, this enables reliable mode.\n </li>\n <li>\n <code>maxPacketLifeTime</code>: The time window in milliseconds, during\n which transmissions and retransmissions may take place in unreliable mode.\n This forces unreliable mode, even if <code>ordered</code> has been\n activated.\n </li>\n <li>\n <code>maxRetransmits</code>: maximum number of retransmissions that are\n attempted in unreliable mode. This forces unreliable mode, even if\n <code>ordered</code> has been activated.\n </li>\n <li>\n <code>Protocol</code>: Name of the subprotocol used for data communication.\n </li>\n</ul>\n ", "extends": "BaseRtpEndpoint", "constructor": { "params": [ { "name": "mediaPipeline", "doc": "the :rom:cls:`MediaPipeline` to which the endpoint belongs", "type": "MediaPipeline" }, { "name": "recvonly", "doc": "Single direction, receive-only endpoint", "type": "boolean", "optional": true, "defaultValue": false }, { "name": "sendonly", "doc": "Single direction, send-only endpoint", "type": "boolean", "optional": true, "defaultValue": false }, { "name": "useDataChannels", "doc": "Activate data channels support", "type": "boolean", "optional": true, "defaultValue": false }, { "name": "certificateKeyType", "doc": "Define the type of the certificate used in dtls", "type": "CertificateKeyType", "optional": true, "defaultValue": "RSA" }, { "name": "qosDscp", "doc": "DSCP value to be used in network traffic sent from this endpoint\n \n If this parameter is present with a value different to NO_VALUE, all traffic sent from this WebRTCEndpoint will be marked with the correspondent\n DSCP value according to the DiffServ architecture. This may provide better handling of network traffic according to its characteristics associated to\n its DSCP value. This better handling includes priority in forwarding traffic and probability of packet drop in case of network congestion.\n \n It must be taken into account that on Internet not all intermediate routers are guaranteed to enforce those DSCP values, even it is possible that\n certain routers just block traffic marked with specific DSCP values, as discussed here https://datatracker.ietf.org/doc/html/rfc8835#section-4.2.\n \n So, this feature must be managed with care and is mostly intended for private networks, where the network proprietor can configure and guarantee\n DSCP management in all routers.", "type": "DSCPValue", "optional": true, "defaultValue": "NO_VALUE" } ], "doc": "Builder for the :rom:cls:`WebRtcEndpoint`" }, "properties": [ { "name": "networkInterfaces", "doc": "Local network interfaces used for ICE gathering.\n\n If you know which network interfaces should be used to perform ICE (for WebRTC\n connectivity), you can define them here. Doing so has several advantages:\n\n<ul>\n <li>\n The WebRTC ICE gathering process will be much quicker. Normally, it needs to\n gather local candidates for all of the network interfaces, but this step can\n be made faster if you limit it to only the interface that you know will\n work.\n </li>\n <li>\n It will ensure that the media server always decides to use the correct\n network interface. With WebRTC ICE gathering it's possible that, under some\n circumstances (in systems with virtual network interfaces such as\n <code>docker0</code>) the ICE process ends up choosing the wrong local IP.\n </li>\n</ul>\n\n <code>networkInterfaces</code> is a comma-separated list of network interface\n names.\n\nExamples:\n<ul>\n <li><code>networkInterfaces=eth0</code></li>\n <li><code>networkInterfaces=eth0,enp0s25</code></li>\n</ul>\n ", "type": "String" }, { "name": "iceTcp", "doc": "Enable ICE-TCP candidate gathering.\n\n This setting enables or disables using TCP for ICE candidate gathering in the\n underlying libnice library:\n https://libnice.freedesktop.org/libnice/NiceAgent.html#NiceAgent--ice-tcp\n\n\n You might want to disable ICE-TCP to potentially speed up ICE gathering by\n avoiding TCP candidates in scenarios where they are not needed.\n\n<code>iceTcp</code> is either 1 (ON) or 0 (OFF). Default: 1 (ON).\n ", "type": "boolean" }, { "name": "stunServerAddress", "doc": "STUN server IP address.\nThe ICE process uses STUN to punch holes through NAT firewalls.\n\n <code>stunServerAddress</code> MUST be an IP address; domain names are NOT\n supported.\n\n\n You need to use a well-working STUN server. Use this to check if it works: \n https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/ \n From that check, you should get at least one Server-Reflexive Candidate (type\n <code>srflx</code>).\n\n ", "type": "String" }, { "name": "stunServerPort", "doc": "Port of the STUN server", "type": "int" }, { "name": "turnUrl", "doc": "TURN server URL.\n\n When STUN is not enough to open connections through some NAT firewalls, using\n TURN is the remaining alternative.\n\n\n Note that TURN is a superset of STUN, so you don't need to configure STUN if\n you are using TURN.\n\nThe provided URL should follow one of these formats:\n<ul>\n <li><code>user:password@ipaddress:port</code></li>\n <li>\n <code>user:password@ipaddress:port?transport=[udp|tcp|tls]</code>\n </li>\n</ul>\n\n <code>ipaddress</code> MUST be an IP address; domain names are NOT supported. \n <code>transport</code> is OPTIONAL. Possible values: udp, tcp, tls. Default: udp.\n\n\n You need to use a well-working TURN server. Use this to check if it works: \n https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/ \n From that check, you should get at le