blob: 3ea70b2f4a87fde0ec088124e724c1d5d08aa427
| 1 | ==================================================== |
| 2 | Encours project: Real-time interactive presentations |
| 3 | ==================================================== |
| 4 | - Directly in your web browser! |
| 5 | - Shared slides visible by all. |
| 6 | - Embedded audio system. |
| 7 | - Shared "Laser" pointers. |
| 8 | - Chat interface with the audience. |
| 9 | - Can be connected to a phone server. |
| 10 | - Video replays of the presentation. |
| 11 | - Free/Libre software: Get, use, share and improve it! |
| 12 | |
| 13 | |
| 14 | ================= |
| 15 | TABLE OF CONTENTS |
| 16 | ================= |
| 17 | 0: QUICK GUIDE |
| 18 | 1: COMPILATION |
| 19 | 2: INSTALLATION |
| 20 | 3: USAGE |
| 21 | |
| 22 | |
| 23 | ================================ |
| 24 | -1: Quick test for the impatient |
| 25 | ================================ |
| 26 | |
| 27 | - In the "dist" subdirectory, type "./start-encours.sh" |
| 28 | - Point your browser to "http://127.0.01:8901/encours/" |
| 29 | - Tadaaa!!! |
| 30 | - If anything went wrong, or if you wish to connect Encours.org with an Asterisk phone server, or if you wish to use the native version of the Speex library, read the extended steps below. |
| 31 | - Otherwise skim through to the quick guide below and possibly even read 3: USAGE |
| 32 | |
| 33 | |
| 34 | ============================================== |
| 35 | 0: Quick Guide for the slightly less impatient |
| 36 | ============================================== |
| 37 | |
| 38 | Check the pre-compiled binary version works |
| 39 | ------------------------------------------- |
| 40 | - In the "dist" directory, type "./start-encours.sh" (you need Java installed for this to work) |
| 41 | - Point your web browser to "http://localhost:8901/encours" for the demo. |
| 42 | - Point your web browser to "http://localhost:8901/encours/index.html?lecturer=123" for the lecturer access. |
| 43 | - Please use separate browsers for connecting simultaneously as listener and lecturer, or deactivate cookies if you are using the same browser. |
| 44 | |
| 45 | How to install your own presentations |
| 46 | ------------------------------------- |
| 47 | - Create a directory with your presentation name, for example "demo", in "webroot/presentations/". |
| 48 | - Copy your presentation as a file named "slides.pdf" in that directory. |
| 49 | - Go in that directory and run "../../../tools/convert_slides.pl" (you need ImageMagick installed for this to work). |
| 50 | - Your presentation is now accessible as "http://localhost:8901/encours/index.html?presentation=demo" |
| 51 | - The corresponding lecturer link is "http://localhost:8901/encours/index.html?presentation=demo&lecturer=123". |
| 52 | |
| 53 | More configuration |
| 54 | ------------------ |
| 55 | - To change the presentation password, copy the file "presconfig/README.txt" as "presconfig/demo" and edit it. |
| 56 | - To change the web server port, edit the file "etc/jetty.xml" and change "8901" by the desired value. For information, if you choose port "80" you won't need to write it in the URL (i.e. http://localhost/encours) but you will then need to run "./start-encours.sh" as the root administrator (ex: use "sudo ./start-encours.sh"). |
| 57 | |
| 58 | Making a video replay |
| 59 | --------------------- |
| 60 | - One of the lecturers must start the recording (click on the corresponding button) during the presentation. The audio from the integrated system, together with all lecturer actions, are then stored in the directory "records/demo/". |
| 61 | - After the presentation, run "java -cp webapps/encours/WEB-INF/classes org.encours.tools.VideoMaker" with the requested arguments: record_file audio_file slidesdir. For example: "java -cp webapps/encours/WEB-INF/classes org.encours.tools.VideoMaker records/default/2009-07-07-00-03-08-464.rec records/default/2009-07-07-00-03-08-464.ogg webroot/presentations/demo" (you need to have the "ffmpeg" and optionally the "flvtool2" programs installed for this to work). |
| 62 | - This will generate "demo.ogv" and "demo.flv" in the "webroot/presentations/demo" directory. Finally call "tools/make_video_page.pl webroot/presentations/demo" to generate a "replay.html" file in your directory (you need oggz-info for this to work). |
| 63 | |
| 64 | Firewall considerations and more information |
| 65 | -------------------------------------------- |
| 66 | - Client side: People connecting to your server may do so from behind most firewalls on their side: if they can access the web even through a proxy they can see the slides moving. The audio uses plain UDP with a nice behavior for firewalls/nats. It might occasionally get blocked if people are in a paranoidly restrictive environment (work, campus...) but then they cannot do anything about it anyway: use the phone connection as a fallback if this ever happen. |
| 67 | - Server side: You obviously need to allow incoming connections to the web server (port 8901 in the above example, or port 80). The UDP ports used by the integrated audio server are defined in the file "webapps/encours/WEB-INF/web.xml" (you can change them to what you like). Make sure your firewall allows them through. |
| 68 | - Read the various README.txt files in the subdirectories to know what these directories are used for. |
| 69 | - Read the section below about the Asterisk connector if you wish to connect to your conferences by phone. Tip: some SIP providers on the internet (ex: SIPBroker), give you a phone to voice-over-IP gateway for free. |
| 70 | |
| 71 | |
| 72 | ============== |
| 73 | 1: COMPILATION |
| 74 | ============== |
| 75 | |
| 76 | 1.1: Compilation environment |
| 77 | ---------------------------- |
| 78 | - Get a recent JDK, OpenJDK version 6 or above is recommended. Check that the program "javac" is installed. |
| 79 | - If you wish to compile the native version of Speex (for lesser CPU usage) you will also need the "gcc" compiler. The sources of the speex codec are included here, so you do not need to download Speex again. |
| 80 | - If you wish to build the Asterisk connector (for accessing Encours.org by phone/SIP), then you will need to install the header files of Asterisk. |
| 81 | |
| 82 | 1.2: Compilation of the Jetty web service |
| 83 | ----------------------------------------- |
| 84 | - Compile anything under the "java" directory (ex: using Eclipse), or simply type "make webapp". |
| 85 | - The resulting binaries shall be available in "dist/webapps/encours/WEB-INF/classes". |
| 86 | |
| 87 | 1.3: Compilation of the Applet |
| 88 | ------------------------------ |
| 89 | - You may find the instructions in "tools/crypto/README.txt" useful for generating a key store. This is necessary only if you want to get the permission to use the participants microphone, so they can trust the applet from the certificate. (or, submit your changes to the main Encours.org project and if they are accepted we'll sign the applet for you with the main project certificate :) |
| 90 | - Type "make applet". This will produce a jar file in "dist/webapps/encours/encoursApplet.jar". Your default java key store is then used to sign the applet. Type "make KEYSTORE=/path/to/your/key_store" if you have a key store in a specific location. |
| 91 | |
| 92 | 1.4: Compilation of the Speex JNI library |
| 93 | ----------------------------------------- |
| 94 | - Type "make jni" to generate an optimised library for the system you are using. |
| 95 | |
| 96 | 1.5: Compilation of the Asterisk application |
| 97 | -------------------------------------------- |
| 98 | - Be sure the Asterisk development files are installed on your system. Ex: "apt-get install asterisk-dev" under a Debian distribution. |
| 99 | - Prefer a version of Asterisk above 1.6 if possible, as you will then get 16000Hz audio sampling rate. Encours.org uses 16000Hz internally. Actually compilation was not tested with asterisk 1.4. |
| 100 | - Type "make asterisk". |
| 101 | |
| 102 | |
| 103 | =============== |
| 104 | 2: INSTALLATION |
| 105 | =============== |
| 106 | |
| 107 | 2.1: Installation of the main application |
| 108 | ----------------------------------------- |
| 109 | - Copy the content of the "dist" directory that was generated by the "make distbase" process to some place of your choice. |
| 110 | - Sample jetty configuration files are included. You may copy and adapt them to your need. In particular, the file "etc/jetty.xml" points to the port 8901, so the server can be tested locally without interfering with the default web port 80 (change it back if you please). |
| 111 | - Adapt the "webapp/WEB-INF/web.xml" file to your needs (see the comments in that file). |
| 112 | - Run "./start-encours.sh" to start the Jetty web server and Encours.org. |
| 113 | |
| 114 | 2.2: Installation of the Asterisk connector |
| 115 | ------------------------------------------- |
| 116 | - Put "dist/lib/app_encours.so" in "/usr/lib/asterisk/modules/". |
| 117 | - Either restart Asterisk, or type "module load app_encours" in Asterisk's CLI. |
| 118 | - Type in "core show application Encours" in Asterisk's CLI to see how to connect to Encours.org from the dial plan. The syntax is: Encours(local_addr,local_port,server,port,confnum). |
| 119 | Where the arguments are: |
| 120 | - local_addr: The local interface (IP dot notation) to use for listening to UDP packets sent to us by the Encours.org server. Can be 0 to listen on all interfaces. |
| 121 | - local_port: The local port to use for listening to UDP packets sent to us by the Encours.org server. Can be 0 to use a random port. |
| 122 | - server: The Encours.org server to connect to (symbolic or IP dot notation). |
| 123 | - port: The port on the Encours.org server to connect to. |
| 124 | - confnum: The Encours.org conference to bridge this channel to. 0 is the default conference. This has nothing to do with MeetMe's conferencing scheme. See Encours.org 'presconfig' directory. |
| 125 | - flags: 0: Use raw 8000Hz. 16000Hz is preferable if you can (Encours.org works at 16000Hz internally), as resampling to 8000Hz in Encours.org incurs both a small algorithmic delay and some inevitable noise. 1: Use Speex between Asterisk and Encours.org. Raw data is preferable for local connections for both lower CPU and no incurred algorithmic delay, but distant connections are supported and might need compressed data. 2: Use raw 16000 Hz (Asterisk 1.6+). This is the recommended setup if you can. 3: Invalid for now (perhaps Asterisk will handle speex 16000Hz one day) |
| 126 | |
| 127 | Example: This will connect the caller to Encours's conference number 1, using 16000 Hz uncompressed audio data, on the local host. |
| 128 | exten => 1,1,Answer |
| 129 | exten => 1,n,Encours(0,0,127.0.0.1,1234,1,2) |
| 130 | exten => 1,n,Hangup |
| 131 | Tip: If you cannot or do not want to install Meetme, Encours.org can be used as the conferencing application: simply use the above example on incoming connections. Meetme is less CPU-intensive, but needs a timer source and specialised Linux kernel module. |
| 132 | Tip2: The Encours application exits if you specified a local port that is already used. You may take advantage of that to ensure the unicity of the Encours connection with a meetme application. |
| 133 | |
| 134 | |
| 135 | ======== |
| 136 | 3: USAGE |
| 137 | ======== |
| 138 | |
| 139 | 3.1: Making a new presentation |
| 140 | ----------------------------- |
| 141 | - In "webroot/presentations" (adapt if you changed the directory pointed by the "encours.presentations.serverPath" from the encours "WEB-INF/web.xml" file): create a subdirectory with your presentation name. |
| 142 | - Copy the presentation PDF as a file named "slides.pdf" in that directory. |
| 143 | - Run "/path/to/your/install/tools/convert_slides.pl" from that directory. The commands "pdfinfo", "pdftoppm" and "convert" from ImageMagick are needed at that point. |
| 144 | - (Optional) Read "dist/presconfig/README.txt". Copy that file to "dist/presconfig/your_presentation_name" and edit it. In particular pay attention to the conference number if you wish to connect Encours.org with Asterisk. You may also change the lecturer password in that file. |
| 145 | - The presentation should be available as "http://your_host/encours/index.html?presentation=XXX" where XXX is the directory name you created in the first step, and where "your_host" is the URL of the jetty web server (ex: "localhost:8901" for a jetty install on the local machine at the port 8901). The lecturer link should be "http://your_host/encours/index.html?presentation=XXX&lecturer=123" if you did not change the default lecturer password "123". |
| 146 | |
| 147 | 3.2: Making a video replay of the presentation (simple) |
| 148 | -------------------------------------------------- |
| 149 | - One of the lecturers must start the recording (click on the corresponding button) during the presentation. The audio from the integrated system, together with all lecturer actions, are then stored in the directory "records/your_presentation_name/" or the one that was specified by "encours.recording.serverPath" in the "WEB-INF/web.xml". |
| 150 | - After the presentation, run "java -cp webapps/encours/WEB-INF/classes org.encours.tools.VideoMaker" with the requested arguments: record_file audio_file slidesdir. For example: "java -cp webapps/encours/WEB-INF/classes org.encours.tools.VideoMaker records/your_presentation_name/2009-07-07-00-03-08-464.rec records/your_presentation_name/2009-07-07-00-03-08-464.ogg webroot/presentations/your_presentation_name" |
| 151 | - Note: you need to have the "ffmpeg" and the "flvtool2" programs installed for this to work. |
| 152 | - The output files are generated as "your_presentation_name.ogv" and "your_presentation_name.flv". Run "tools/make_video_page.pl" on the "webroot/presentations/your_presentation_name" directory to generate a file "webroot/presentations/replay.html". You need oggz-info from the oggz package for this to work. |
| 153 | |
| 154 | 3.3: Making a video replay (extended steps) |
| 155 | -------------------------------------- |
| 156 | - You may want to edit the audio after the presentation, ex: cut the initial discussions, etc. |
| 157 | - There are two ways to do this: before or after making the video. After making the video means that you edit the generated video file with a video editor, possibly loosing quality in the operation. Before making the video means that you edit the .rec and .ogg before making the video, therefore getting the optimal quality. |
| 158 | - With an audio editor (ex: Audacity), note the timing XXXX in ms from the beginning of the audio file that you wish to be the new conference starting point. Edit the file to remove anything before XXXX (so it is now 0). You can also cut discussions/talks at the end of the file. |
| 159 | - Use the script "tools/recedit.pl" with the ".rec" recorded file and the difference XXXX as arguments. Redirect or copy the output in another ".rec" file. |
| 160 | - Run the video maker tool as above on the edited rec and the edited audio file, now they are in sync. |
| 161 | - Note that this method can also be used to synchronise the rec file with an externally recorded audio file. You can even write yourself a ".rec" file from scratch for a conference that was never given with encours. |
| 162 | |
| 163 | |
| 164 | |
| 165 | ======================================== |
| 166 | 4: TODO: If you wish to help the project |
| 167 | ======================================== |
| 168 | - Make web frontends for importing slides and making video replays. |
| 169 | - Integrate Jetty 7 into Encours.org to make it a standalone application, and get rid of the useless webapp/xml infrastructure. |
| 170 | |
| 171 | |
| 172 | =================== |
| 173 | HAPPY CONFERENCING! |
| 174 | =================== |
| 175 | |
| 176 | Nicolas Brodu <nicolas.brodu@encours.org> |
| 177 | |
| 178 |
