项目作者: valeriansaliou

项目描述 :
:telephone_receiver: Giggle Jingle library for XMPP, implementation of XEP-0166.
高级语言: JavaScript
项目地址: git://github.com/valeriansaliou/giggle.git
创建时间: 2013-06-18T10:49:38Z
项目社区:https://github.com/valeriansaliou/giggle

开源协议:Mozilla Public License 2.0

下载


Giggle.js

Giggle library, implementation of XEP-0166 (Jingle). XMPP audio/video chat in your Web browser!

To be used with JSJaC from Stefan Strigler, available there: sstrigler/JSJaC
Giggle is pluggable to other third-party XMPP libraries, please refer to ./src/giggle.plug.js. We’ll happily accept your Pull Requests (PR).

🇫🇷 Crafted in Brest, France.

How To Build It?

Only Giggle.js raw sources are provided in this repository. Those are not usable out-of-the-box for production purposes. You first need to build the library components on your local machine.

Important: our automated build system requires that you have NodeJS, NPM, GruntJS, Bower (+ bower-installer) and Java on your machine. UNIX systems (MacOS, Linux) are recommended to proceed build.

If you already have NodeJS and NPM installed, you can simply install GruntJS and Bower:

npm install -g grunt-cli bower bower-installer

Deploy the library in one simple command:

./tools/deploy.sh

Testing Giggle

Please first clone Giggle on your local environment, and access it over your local HTTP server. Serving example pages over HTTP is a requirement for WebRTC to work.

One-to-one calls (aka Single)

You can try Giggle.js one-to-one calls using the page: giggle/examples/single_client.html

Open it on 2 separate tabs or 2 different computers, and login with 2 different XMPP accounts. Then, paste the full JID of the other connected account in the call field.

The call should then be initiated, and after a while the video will come.

Multiparty calls (aka Muji)

You can try Giggle.js multiparty calls using the page: giggle/examples/muji_client.html

Open it on 3+ separate tabs or 3+ different computers, and login with 3+ different XMPP accounts. Then, join the same conference room (you can enter any room even if it doesn’t exist, on any open MUC server).

The multiparty conference call should take some time to initiate.

Note: depending on how powerful your CPU is and how much bandwidth your network can allocated, performances may degrade with many participants.

Notes About Security

Jingle could have been implemented in a dirty-way there, so that “It just works”. But it’s NOT the case. Giggle.js has been thought as secure on its basis.

We wanted to avoid such possible security exploits: imagine a friend of you wants to disturb your call, and send you a session-terminate with a wrong SID. In a quick-and-dirty implementation, the request would have been dropped because the call is already ongoing, but the client-side handlers would still have been fired, thus modifying the UI.

Giggle.js simply DOES NOT fire the custom event handlers that you may have defined, so that you don’t have to check yourself that each incoming packet is safe, thus to ensure your client implementation of Jingle is rock-solid (safe: session is authorized AND stanza sender is authorized AND the Jingle session flow is respected).

Multiparty call can be password-protected, in a completely transparent fashion. Giggle.js can handle the password generation process, and then transmit it to other potential call participants through the Muji call invites you send to them.

Usage

The API documentation is available in: ./doc/. You must first build Giggle to view it, please refer to the upper section about building Giggle.

We assume your XMPP Web client is using a supported XMPP library and has an active connection, stored in the GIGGLE_CONNECTION global object.

  1. /*
  2. * Giggle.js Implementation Example
  3. */
  4. // 1. Ensure you are loading the following libraries:
  5. // > jQuery
  6. // > JSJaC (or any other supported XMPP library)
  7. // > Giggle.js
  8. // 2. Define configuration generators
  9. var single_config_generator = function() {
  10. // Return single configuration object
  11. // Refer to single_client.js source for more
  12. return {};
  13. };
  14. var muji_config_generator = function() {
  15. // Return muji configuration object
  16. // Refer to muji_client.js source for more
  17. return {};
  18. };
  19. // 3. Initiate the listener
  20. // Note: here using 'JSJaCConsoleLogger' from JSJaC as a console wrapper
  21. Giggle.listen({
  22. plug: GIGGLE_PLUG_JSJAC,
  23. connection: GIGGLE_CONNECTION,
  24. debug: (new JSJaCConsoleLogger(4)),
  25. // Receive a one-to-one (Single) call
  26. single_initiate: function(stanza) {
  27. var config = single_config_generator();
  28. // Configuration values
  29. config.to = stanza.from() || null;
  30. config.local_view = $('#video_local')[0];
  31. config.remote_view = $('#video_remote')[0];
  32. // Handle call request
  33. session = Giggle.session(GIGGLE_SESSION_SINGLE, config);
  34. session.handle(stanza);
  35. },
  36. // Receive a multiparty (Muji) call
  37. muji_invite: function(stanza, args) {
  38. // Note: auto-accepting call there
  39. // you should ask the user before accepting like this
  40. var config = muji_config_generator();
  41. // Session values
  42. config.to = args.jid;
  43. config.media = (args.media == GIGGLE_MEDIA_VIDEO) ? GIGGLE_MEDIA_VIDEO : GIGGLE_MEDIA_AUDIO;
  44. config.local_view = $('#video_local')[0];
  45. if(args.password) {
  46. config.password = args.password;
  47. }
  48. // Handle conference invite
  49. session = Giggle.session(GIGGLE_SESSION_MUJI, config);
  50. session.join();
  51. }
  52. });
  53. // 4. Configure our disco#info handler to reply with Giggle.js features
  54. var handle_disco_info = function(iq) {
  55. // Do the parse work there...
  56. // Get my client feature map
  57. var client_map = [ /* Features here... */ ];
  58. // Get the Giggle.js feature map
  59. var Giggle_map = Giggle.disco();
  60. // Concatenate feature maps
  61. var final_map = client_map.concat(Giggle_map);
  62. // Ensure uniqueness of feature map values there...
  63. // Send back your response stanza there...
  64. };

One-to-one calls

The one-to-one demo client source code can be found at the following URL: giggle/examples/single_client.html

Here’s a sum up on how to use the Giggle/Single API:

  1. /*
  2. * Giggle.Single.js API Example
  3. */
  4. // Single call launcher
  5. var launch_single_call = function(to, target) {
  6. var config = single_config_generator();
  7. // Session values
  8. config.to = to;
  9. config.media = (target == 'call_audio') ? GIGGLE_MEDIA_AUDIO : GIGGLE_MEDIA_VIDEO;
  10. config.video_source = (target == 'call_screen') ? GIGGLE_VIDEO_SOURCE_SCREEN : GIGGLE_VIDEO_SOURCE_CAMERA;
  11. config.local_view = $('#video_local')[0];
  12. config.remote_view = $('#video_remote')[0];
  13. // Send call request
  14. session = Giggle.session(GIGGLE_SESSION_SINGLE, config);
  15. session.initiate();
  16. };
  17. // Attach form submit event
  18. $('form#launch_single_call').submit(function() {
  19. var to = $(this).find('input[name="to"]').val();
  20. var target = ($(this).find('input[name="target"]').val() || 'call_video');
  21. if(to && target) {
  22. // Launch call...
  23. var session = launch_single_call(to, target);
  24. // Send session info (client ringing & more)...
  25. session.info(GIGGLE_SESSION_INFO_RINGING);
  26. // Mute/Unmute audio in call...
  27. session.mute(GIGGLE_MEDIA_AUDIO);
  28. session.umute(GIGGLE_MEDIA_AUDIO);
  29. // Terminate call...
  30. session.terminate(GIGGLE_REASON_SUCCESS);
  31. }
  32. return false;
  33. });

Multiparty calls

The multiparty demo client source code can be found at the following URL: giggle/examples/muji_client.html

Here’s a sum up on how to use the Giggle/Muji API:

  1. /*
  2. * Giggle.Muji.js API Example
  3. */
  4. // Muji call launcher
  5. var launch_muji_call = function(room, target) {
  6. var config = muji_config_generator();
  7. // Session values
  8. config.to = room;
  9. config.media = (target == 'call_audio') ? GIGGLE_MEDIA_AUDIO : GIGGLE_MEDIA_VIDEO;
  10. config.video_source = GIGGLE_VIDEO_SOURCE_CAMERA;
  11. config.local_view = $('#video_local')[0];
  12. // Join conference room
  13. session = Giggle.session(GIGGLE_SESSION_MUJI, config);
  14. session.join();
  15. return session;
  16. };
  17. // Attach form submit event
  18. $('form#launch_muji_call').submit(function() {
  19. var room = $(this).find('input[name="room"]').val();
  20. var target = ($(this).find('input[name="target"]').val() || 'call_video');
  21. if(room && target) {
  22. // Launch conference...
  23. var session = launch_muji_call(room, target);
  24. // Send a message to conference...
  25. session.send_message('Hello World!');
  26. // Mute/Unmute audio in conference...
  27. session.mute(GIGGLE_MEDIA_AUDIO);
  28. session.umute(GIGGLE_MEDIA_AUDIO);
  29. // Invite people to conference...
  30. session.invite([
  31. 'romeo@shakespeare.lit/Phone',
  32. 'juliet@capulet.com/Tablet'
  33. ]);
  34. // Leave conference...
  35. session.leave();
  36. }
  37. return false;
  38. });

Ah, One More Thing…

We worked hard on that lib, we would appreciate your feedback and bug reports.
Plus, if you are using it in your project, we would be glad if you let @valeriansaliou know.

If you have any enhancement idea or any bug to report: giggle/issues