mirror of https://github.com/OpenVidu/openvidu.git
258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
|
[![][KurentoImage]][Kurento]
|
|||
|
|
|
|||
|
|
Copyright © 2013-2016 [Kurento]. Licensed under [LGPL v2.1 License].
|
|||
|
|
|
|||
|
|
kurento-room
|
|||
|
|
============
|
|||
|
|
|
|||
|
|
Kurento Room is composed by several modules to offer group communications by
|
|||
|
|
means of WebRTC. These modules are:
|
|||
|
|
|
|||
|
|
* `kurento-room-sdk` - module that provides a management interface for
|
|||
|
|
developers of multimedia conferences (rooms) applications in Java
|
|||
|
|
* `kurento-room-server` - Kurento’s own implementation of a room API, it
|
|||
|
|
provides the WebSockets API for the communications between room clients and
|
|||
|
|
the server.
|
|||
|
|
* `kurento-room-client` - Java library that uses WebSockets and JSON-RPC to
|
|||
|
|
interact with the server-side of the Room API. Can be used to implement the
|
|||
|
|
client-side of a room application.
|
|||
|
|
* `kurento-room-client-js` - Javascript library that acts as wrapper for several
|
|||
|
|
JS APIs (WebRTC, WebSockets, Kurento Utils). Can be used to implement the
|
|||
|
|
client-side of a room application.
|
|||
|
|
* `kurento-room-demo` - demonstration project, contains the client-side
|
|||
|
|
implementation (HTML, Javascript, graphic resources) and embeds the room
|
|||
|
|
server to provide the functionality required for group communications
|
|||
|
|
* `kurento-room-test` - integration and functionality tests for the basic room
|
|||
|
|
server application
|
|||
|
|
* `kurento-room-demo-test` - integration and functionality tests for the demo
|
|||
|
|
application.
|
|||
|
|
|
|||
|
|
There is extensive documentation on each of these components together with a
|
|||
|
|
tutorial based on the Room demo. This documentation can be easily generated in
|
|||
|
|
HTML format from the [kurento-room-doc](./kurento-room-doc/README.md) project.
|
|||
|
|
|
|||
|
|
Dependencies
|
|||
|
|
------------
|
|||
|
|
|
|||
|
|
These are some of the design and architecture requirements that an application
|
|||
|
|
has to fulfill in order to integrate the Room API:
|
|||
|
|
|
|||
|
|
* include the SDK module to its dependencies list
|
|||
|
|
* create one of the two `RoomManager` types as a singleton instance by
|
|||
|
|
providing implementations for the following interfaces:
|
|||
|
|
* `RoomEventHandler`
|
|||
|
|
* `KurentoClientProvider`
|
|||
|
|
* develop the client-side of the application for devices that support WebRTC
|
|||
|
|
(*hint:* or use our *client-js* library and take a look at the demo's client
|
|||
|
|
implementation)
|
|||
|
|
* design a room signaling protocol that will be used between the clients and
|
|||
|
|
the server (*hint:* or use the WebSockets API from `kurento-room-server`)
|
|||
|
|
* implement a handler for clients' requests on the server-side, that will
|
|||
|
|
use the `RoomManager` to process these requests (*hint:* JSON-RPC handler
|
|||
|
|
from `kurento-room-server`)
|
|||
|
|
* choose a response and notification mechanism for the communication with the
|
|||
|
|
clients (*hint:* JSON-RPC notification service from `kurento-room-server`)
|
|||
|
|
|
|||
|
|
About the technology stacks that can or should be used to implement a Rooms
|
|||
|
|
application:
|
|||
|
|
|
|||
|
|
* WebSockets for the communications between the server and the clients
|
|||
|
|
* Spring and Spring Boot for the easy configuration and integration with some
|
|||
|
|
of Kurento's modules. It also provides a WebSockets library.
|
|||
|
|
|
|||
|
|
And of course, the main requirement is at least one installation of the Kurento
|
|||
|
|
Media Server, accessible to the room application.
|
|||
|
|
|
|||
|
|
Running the demo
|
|||
|
|
----------------
|
|||
|
|
|
|||
|
|
For a quick initial contact with the framework, we recommend running the demo
|
|||
|
|
application and observing the exchange of Websocket messages between the clients
|
|||
|
|
and the server.
|
|||
|
|
|
|||
|
|
Currently, the demo is only supported for Ubuntu 14.04 LTS 64bits.
|
|||
|
|
|
|||
|
|
After cloning the tutorial, it can be executed directly from the terminal by
|
|||
|
|
using Maven's `exec` plugin. To make sure the demo's
|
|||
|
|
build and execution works smoothly, a stable release (or tag) is checked out
|
|||
|
|
before proceeding with the build (prevents missing dependencies, given that in
|
|||
|
|
Kurento *master* is the development branch):
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
$ git clone git@github.com:Kurento/kurento-room.git
|
|||
|
|
$ cd kurento-room
|
|||
|
|
$ git checkout 6.1.0
|
|||
|
|
$ cd kurento-room-demo
|
|||
|
|
$ mvn compile exec:java
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Now open the following URL in a WebRTC-compatible browser and connect to a new
|
|||
|
|
room by providing the desired user and room names:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
http://localhost:8080
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Configuring the demo
|
|||
|
|
--------------------
|
|||
|
|
|
|||
|
|
There are a couple of interesting options or properties that might have to be
|
|||
|
|
modified for the demo to function properly.
|
|||
|
|
|
|||
|
|
The properties file, **kroomdemo.conf.json**, used in the demo's execution as
|
|||
|
|
described above, is located in the folder `src/main/resources` and its
|
|||
|
|
contents are the following:
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"kms": {
|
|||
|
|
"uris": ["ws://localhost:8888/kurento","ws://127.0.0.1:8888/kurento"]
|
|||
|
|
},
|
|||
|
|
"app": {
|
|||
|
|
"uri": "http://localhost:8080/"
|
|||
|
|
},
|
|||
|
|
"kurento": {
|
|||
|
|
"client": {
|
|||
|
|
//milliseconds
|
|||
|
|
"requestTimeout": 20000
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
"demo": {
|
|||
|
|
//mario-wings.png or wizard.png
|
|||
|
|
"hatUrl": "mario-wings.png"
|
|||
|
|
"hatCoords": {
|
|||
|
|
// mario-wings hat
|
|||
|
|
"offsetXPercent": -0.35F,
|
|||
|
|
"offsetYPercent": -1.2F,
|
|||
|
|
"widthPercent": 1.6F,
|
|||
|
|
"heightPercent": 1.6F
|
|||
|
|
|
|||
|
|
//wizard hat
|
|||
|
|
//"offsetXPercent": -0.2F,
|
|||
|
|
//"offsetYPercent": -1.35F,
|
|||
|
|
//"widthPercent": 1.5F,
|
|||
|
|
//"heightPercent": 1.5F
|
|||
|
|
},
|
|||
|
|
"loopback" : {
|
|||
|
|
"remote": false,
|
|||
|
|
//matters only when remote is true
|
|||
|
|
"andLocal": false
|
|||
|
|
},
|
|||
|
|
"authRegex": ".*",
|
|||
|
|
"kmsLimit": 10
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
These properties can be overwritten on the command-line when starting
|
|||
|
|
the demo server:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
$ mvn compile exec:java -Dkms.uris=[\"ws://192.168.1.99:9001/kurento\"]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
In this example, we've instructed the demo to use a different URI of a running
|
|||
|
|
KMS instance when creating the `KurentoClient` required by the Room API.
|
|||
|
|
|
|||
|
|
More details on the demo's configuration and execution can be found in the demo's
|
|||
|
|
[README page](./kurento-room-demo/README.md) or in the Room API
|
|||
|
|
[documentation](./kurento-room-doc/README.md) .
|
|||
|
|
|
|||
|
|
What is Kurento
|
|||
|
|
---------------
|
|||
|
|
|
|||
|
|
Kurento is an open source software project providing a platform suitable
|
|||
|
|
for creating modular applications with advanced real-time communication
|
|||
|
|
capabilities. For knowing more about Kurento, please visit the Kurento
|
|||
|
|
project website: http://www.kurento.org.
|
|||
|
|
|
|||
|
|
Kurento is part of [FIWARE]. For further information on the relationship of
|
|||
|
|
FIWARE and Kurento check the [Kurento FIWARE Catalog Entry]
|
|||
|
|
|
|||
|
|
Kurento is part of the [NUBOMEDIA] research initiative.
|
|||
|
|
|
|||
|
|
Documentation
|
|||
|
|
-------------
|
|||
|
|
|
|||
|
|
The Kurento project provides detailed [documentation] including tutorials,
|
|||
|
|
installation and development guides. A simplified version of the documentation
|
|||
|
|
can be found on [readthedocs.org]. The [Open API specification] a.k.a. Kurento
|
|||
|
|
Protocol is also available on [apiary.io].
|
|||
|
|
|
|||
|
|
Source
|
|||
|
|
------
|
|||
|
|
|
|||
|
|
Code for other Kurento projects can be found in the [GitHub Kurento Group].
|
|||
|
|
|
|||
|
|
News and Website
|
|||
|
|
----------------
|
|||
|
|
|
|||
|
|
Check the [Kurento blog]
|
|||
|
|
Follow us on Twitter @[kurentoms].
|
|||
|
|
|
|||
|
|
Issue tracker
|
|||
|
|
-------------
|
|||
|
|
|
|||
|
|
Issues and bug reports should be posted to the [GitHub Kurento bugtracker]
|
|||
|
|
|
|||
|
|
Licensing and distribution
|
|||
|
|
--------------------------
|
|||
|
|
|
|||
|
|
Software associated to Kurento is provided as open source under GNU Library or
|
|||
|
|
"Lesser" General Public License, version 2.1 (LGPL-2.1). Please check the
|
|||
|
|
specific terms and conditions linked to this open source license at
|
|||
|
|
http://opensource.org/licenses/LGPL-2.1. Please note that software derived as a
|
|||
|
|
result of modifying the source code of Kurento software in order to fix a bug
|
|||
|
|
or incorporate enhancements is considered a derivative work of the product.
|
|||
|
|
Software that merely uses or aggregates (i.e. links to) an otherwise unmodified
|
|||
|
|
version of existing software is not considered a derivative work.
|
|||
|
|
|
|||
|
|
Contribution policy
|
|||
|
|
-------------------
|
|||
|
|
|
|||
|
|
You can contribute to the Kurento community through bug-reports, bug-fixes, new
|
|||
|
|
code or new documentation. For contributing to the Kurento community, drop a
|
|||
|
|
post to the [Kurento Public Mailing List] providing full information about your
|
|||
|
|
contribution and its value. In your contributions, you must comply with the
|
|||
|
|
following guidelines
|
|||
|
|
|
|||
|
|
* You must specify the specific contents of your contribution either through a
|
|||
|
|
detailed bug description, through a pull-request or through a patch.
|
|||
|
|
* You must specify the licensing restrictions of the code you contribute.
|
|||
|
|
* For newly created code to be incorporated in the Kurento code-base, you must
|
|||
|
|
accept Kurento to own the code copyright, so that its open source nature is
|
|||
|
|
guaranteed.
|
|||
|
|
* You must justify appropriately the need and value of your contribution. The
|
|||
|
|
Kurento project has no obligations in relation to accepting contributions
|
|||
|
|
from third parties.
|
|||
|
|
* The Kurento project leaders have the right of asking for further
|
|||
|
|
explanations, tests or validations of any code contributed to the community
|
|||
|
|
before it being incorporated into the Kurento code-base. You must be ready to
|
|||
|
|
addressing all these kind of concerns before having your code approved.
|
|||
|
|
|
|||
|
|
Support
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
The Kurento project provides community support through the [Kurento Public
|
|||
|
|
Mailing List] and through [StackOverflow] using the tags *kurento* and
|
|||
|
|
*fiware-kurento*.
|
|||
|
|
|
|||
|
|
Before asking for support, please read first the [Kurento Netiquette Guidelines]
|
|||
|
|
|
|||
|
|
[documentation]: http://www.kurento.org/documentation
|
|||
|
|
[FIWARE]: http://www.fiware.org
|
|||
|
|
[GitHub Kurento bugtracker]: https://github.com/Kurento/bugtracker/issues
|
|||
|
|
[GitHub Kurento Group]: https://github.com/kurento
|
|||
|
|
[kurentoms]: http://twitter.com/kurentoms
|
|||
|
|
[Kurento]: http://kurento.org
|
|||
|
|
[Kurento Blog]: http://www.kurento.org/blog
|
|||
|
|
[Kurento FIWARE Catalog Entry]: http://catalogue.fiware.org/enablers/stream-oriented-kurento
|
|||
|
|
[Kurento Netiquette Guidelines]: http://www.kurento.org/blog/kurento-netiquette-guidelines
|
|||
|
|
[Kurento Public Mailing list]: https://groups.google.com/forum/#!forum/kurento
|
|||
|
|
[KurentoImage]: https://secure.gravatar.com/avatar/21a2a12c56b2a91c8918d5779f1778bf?s=120
|
|||
|
|
[LGPL v2.1 License]: http://www.gnu.org/licenses/lgpl-2.1.html
|
|||
|
|
[NUBOMEDIA]: http://www.nubomedia.eu
|
|||
|
|
[StackOverflow]: http://stackoverflow.com/search?q=kurento
|
|||
|
|
[Read-the-docs]: http://read-the-docs.readthedocs.org/
|
|||
|
|
[readthedocs.org]: http://kurento.readthedocs.org/
|
|||
|
|
[Open API specification]: http://kurento.github.io/doc-kurento/
|
|||
|
|
[apiary.io]: http://docs.streamoriented.apiary.io/
|