From 565a29bdcf86378a9ae6ace131ede20a212735f2 Mon Sep 17 00:00:00 2001 From: pabloFuente Date: Mon, 12 Jun 2017 14:58:30 +0200 Subject: [PATCH] openvidu-insecure-js README updated --- openvidu-insecure-js/README.md | 163 +++++++++++++++++++++------------ 1 file changed, 106 insertions(+), 57 deletions(-) diff --git a/openvidu-insecure-js/README.md b/openvidu-insecure-js/README.md index a0c8d511..5c311921 100644 --- a/openvidu-insecure-js/README.md +++ b/openvidu-insecure-js/README.md @@ -1,78 +1,127 @@ # openvidu-insecure-js -This repository contains a group videoconference sample application implemented using OpenVidu. This application is a SPA page implemented in plain JavaScript (without any JavaScript framework). +This is the simplest demo you can try to get started with OpenVidu. It has the minimum set of features to make a video-call. You will only need a few minutes to get your first application working. -## Start OpenVidu Development Server +## Understanding this example -To develop a videoconference application with OpenVidu you first have to start an OpenVidu Development Server, that contains all needed services. OpenVidu Development Server is distributed in a single docker image. +

+ +

-To execute OpenVidu Development Server in your local development computer, you need to have docker software installed. You can [install it on Windows, Mac or Linux](https://docs.docker.com/engine/installation/). +OpenVidu is composed by the three modules displayed on the image above in its insecure version. -To start OpenVidu Development Server execute the following command (depending on your configuration it is is possible that you need to execute it with 'sudo'): +- **openvidu-browser**: JavaScript library for the browser. It allows you to manage your video-calls straight away from your clients +- **openvidu-server**: Java application that controls Kurento Media Server +- **Kurento Media Server**: server that handles low level operations of media flows transmission -
-docker run -p 8443:8443 --rm -e KMS_STUN_IP=193.147.51.12 -e KMS_STUN_PORT=3478 openvidu/openvidu-server-kms
-
+> You will only have to make use of **openvidu-browser** to get this sample app working. -And then wait to a log trace similar to this: +## Executing this example -
-INFO: Started OpenViduServer in 5.372 seconds (JVM running for 6.07)
-
+1. Clone the repo: -If you have installed Docker Toolbox in Windows or Mac, you need to know the IP address of your docker machine excuting the following command: + ```bash + git clone https://github.com/OpenVidu/openvidu-tutorials.git + ``` + +2. _openvidu-server_ and _Kurento Media Server_ must be up and running in your development machine. The easiest way is running this Docker container which wraps both of them (you will need [Docker CE](https://store.docker.com/search?type=edition&offering=community)): -
-docker-machine ip default
-
+ ```bash + docker run -p 8443:8443 --rm -e KMS_STUN_IP=193.147.51.12 -e KMS_STUN_PORT=3478 -e openvidu.security=false openvidu/openvidu-server-kms + ``` -Then, open in your browser and visit URL `https://127.0.0.1:8443` (or if you are using Docker Toolbox in Windows or Mac visit `https://:8443`). Then, browser will complain about insecure certificate. Please accept the selfsigned certificate as valid. +3. You will need an http web server installed in your development computer to execute the sample application. If you have _node.js_ installed, you can use [http-server](https://github.com/indexzero/http-server) to serve application files. It can be installed with: -Now you are ready to execute the sample application. + ```bash + npm install http-server -g + ``` -## Executing sample application +4. To run the sample application, execute the following command in the project: -In this repository you have a sample JavaScript application that use OpenVidu Development Server to allow videoconferences between a group of users. Please clone it with the following command (you need git installed in your development machine): + ```bash + cd openvidu-insecure-js/web + http-server + ``` -
-git clone https://github.com/OpenVidu/openvidu-sample-basic-plainjs
-
+5. Go to [`localhost:8080`](http://localhost:8080) to test the app. If it's the first time you use the docker container, an alert message will suggest you accept the self-signed certificate of _openvidu-server_ when you first try to join a video-call. -First, you need an http web server installed in your development computer to execute the sample application. If you have node.js installed in your development machine, you can use [http-server] to serve application files.(https://github.com/indexzero/http-server). It can be installed with: - -
-npm install http-server -g
-
- -To execute the sample application, execute the following command in the project: - -
-cd openvidu-sample-basic-plainjs
-http-server ./web
-
- -If you are using Docker Toolbox for Windows or Mac, you need to modify the sample application code. You have to change the following line in the file `web/app.js`: - -
-openVidu = new OpenVidu("wss://127.0.0.1:8443/");
-
- -You have to change `127.0.0.1` with the IP of the OpenVidu Development Server obtained in the previous step. - -Then you can go to `http://127.0.0.1:8080` to execute the sample application. - -As you can see, the user name and session is filled automatically in the form to make easier testing the app. - -If you open `http://127.0.0.1:8080` in two tabs, you can simulate two users talking together. You can open as tabs as you want, but you need a very powerful development machine to test 3 or more users. - -For now, it is not possible use the sample application from a different computer. - -## Sample application code +## Understanding the code This application is very simple. It has only 4 files: -* `OpenVidu.js`: OpenVidu client. You don't have to manipulate this file. -* `app.js`: Sample application main JavaScritp file. You can manipulate this file to adapt it to your necesities. -* `index.html`: HTML file. It contains the HTML code for the form to connect to a videoconference and for the videoconference itself. You can manipulate this file to adapt it to your necesities. -* `style.css`: Some CSS classes to style HTML. You can manipulate this file to adapt it to your necesities. +- `OpenVidu.js`: openvidu-browser library. You don't have to manipulate this file. +- `app.js`: sample application main JavaScritp file, which makes use of _OpenVidu.js_. You can manipulate this file to suit your needs. +- `index.html`: HTML code for the form to connect to a video-call and for the video-call itself. You can manipulate this file to adapt it to suit your needs. + It has two links to both JavaScript files: + ```html + + + ``` +- `style.css`: some CSS classes to style _index.html_. You can manipulate this file to suit your needs. + +Let's see how `app.js` uses `OpenVidu.js`: + +- First lines declare the two variables that will be needed in different points along the code. `OV` will be our OpenVidu object and `session` the video-call we will connect to: + + ```javascript + var OV; + var session; + ``` + +- Let's initialize a new session and configure our events: + + ```javascript + OV = new OpenVidu("wss://" + location.hostname + ":8443/"); + session = OV.initSession("apikey", sessionId); + ``` + Since we are in a local sample app, `OV` object is initialize with `localhost:8443` as its _openvidu-server_ URL. `session` object is initialize with `sessionId` param: this means we will connect to `sessionId` video-call. In this case, this parameter is retrieve from HTML input ``, which may be filled by the user. + + ```javascript + session.on('streamCreated', function (event) { + // Subscribe to the stream to receive it + var subscriber = session.subscribe(event.stream, 'subscriber'); + subscriber.on('videoElementCreated', function (event) { + // Add a new HTML element for the user's nickname + appendUserData(event.element, subscriber.stream.connection); + }); + }); + + session.on('streamDestroyed', function (event) { + // Delete the HTML element with the user's nickname + removeUserData(event.stream.connection); + }); + ``` + Here we subscribe to the events that interest us. In this case, we want to receive all videos published to the video-call, as well as displaying every user's nickname nex to its video. To achieve this: + - `streamCreated`: for each new Stream received by OpenVidu, we immediately subscribe to it so we can see its video. A new HTML video element will be appended to element with id 'subscriber'. + - `videoElementCreated`: event triggered by Subscriber object (returned by the previous `Session.subscribe` method). This allows us to add the participant nickname to the new video previously added in `streamCreated` event. Auxiliary method `appendUserData` is responsible for appending a new paragraph element just below the `event.element` video, containing `subscriber.stream.connection.data` field (which has the user's nickname). + - `streamDestroyed`: for each Stream that has been destroyed (which means a user has left the video-call), we remove the paragraph element with the user's nickname that we added in the previous event (`appendUserData` method created the element with an _id_ containing `event.stream.connection.connectionId` unique value, so we can now identify the right element to be removed). The video element is automatically deleted by default, so we don't need to do anything else. + +- Finally connect to the session and publish your webcam: + + ```javascript + session.connect(token, '{"clientData": "' + token + '"}', function (error) { + // If the connection is successful, initialize a publisher and publish to the session + if (!error) { + + // 4) Get your own camera stream with the desired resolution and publish it, if the user is supposed to do so + + var publisher = OV.initPublisher('publisher', { + audio: true, + video: true, + quality: 'MEDIUM' + }); + + // 5) Publish your stream + + session.publish(publisher); + + } else { + console.log('There was an error connecting to the session:', error.code, error.message); + } + }); + ``` + + `token` param is irrelevant when using insecure version of OpenVidu. Remember `videoElementCreated` event, when we added the user's nickname to the HTML? Well, second parameter is the actual value you will receive in `Stream.connection.data` property. So in this case it is a JSON formatted string with a "clientData" tag with "token" value, which is retrieved from HTML input `` (filled by the user). + + In the callback of `Session.connect` method, we check the connection has been succesful (`error` value must be _null_) and right after that we get a `Publisher` object with both audio and video activated and MEDIUM quality. This process will end with the addition of a new HTML video element showing your camera, as a child of element with _id_ 'publisher'. We then just have to publish this object through `Session.publish` method, and the rest of users will begin receiving our webcam. \ No newline at end of file