API Reference
=============

.. contents::

The only class you need to interact with is JCClient.

JCClient
--------

JCClient constructor

.. js:class:: JCClient([options])

  Constructor for JCClient.  A dictionary can be passed in to override default options.

  **Example**

  .. code-block:: javascript

    var options = {};
    var jc = new JCClient(options);

  :param object options: override default options

    * ``apiKey`` - *Required* Set the API Key. Get it `here <https://jumpch.at/sdk/>`_.
    * ``userid`` - *Required* A string tha represents the user.
    * ``serverName`` - Set the server URL.  Defaults to ``https://jumpch.at``
    * ``audioBandwidth`` - Sets audio bandwidth.  Defaults to ``50`` kbps
    * ``videoBandwidth`` - Sets video bandwidth.  Defaults to ``300`` kbps


JCClient.join
-------------

.. js:function:: JCClient.join(roomName, roomType, password, callback)

  Join a JumpChat room to start a video chat.

  **Example**

  .. code-block:: javascript

   jc.join('jumpchat00', 'random', '', function(users) {
     console.log('joined room jumpchat00');
   });


  :param string roomName: Room name to join.  If ``random``, the string must be of length 10.
  :param string roomType: Room type. Must be ``random`` or ``custom``.
  :param string password: Password for the room.
  :param function callback: Callback will return a ``users`` array.



JCClient.leave
--------------

.. js:function:: JCClient.leave()

  Leave the room.

  **Example**

  .. code-block:: javascript

   jc.join('jumpchat00', 'random', '', function(users) {
     console.log('joined room jumpchat00');
     jc.leave();
     console.log('left room jumpchat00');
   });


JCClient.localVideo
-------------------

.. js:function:: JCClient.localVideo(callback)

  Get the local video.

  **Example**

  .. code-block:: javascript

   jc.localVideo(function(video) {

   });

  :param function callback: Callback to receive the local video.


JCClient.sendChatMessage
------------------------

.. js:function:: JCClient.sendChatMessage(msg, userid)

  Send text message to everyone in the room or a single person.  If userid is not specified or is null, the chat message
  is sent to everyone.

  **Example**

  .. code-block:: javascript

   jc.sendChatMessage("hello");

  :param string msg: Text message
  :param string userid: Userid is optional


JCClient.sendDataMessage
------------------------

.. js:function:: JCClient.sendDataMessage(msg, userid)

  Send data message to everyone in the room. If userid is not specified or is null, the chat message
  is sent to everyone.

  **Example**

  .. code-block:: javascript

   jc.sendDataMessage({'hello': 'world'});

  :param string msg: Message.  This could be any serializable javascript object.
  :param string userid: Userid is optional


JCClient.avatar
---------------

.. js:function:: JCClient.avatar([avatar])

  Get or set avatar

  **Example**

  .. code-block:: javascript

   // get avatar
   var avatar = jc.avatar();
   img.src = avatar;

   // set avatar
   jc.avatar(newAvatar);

  :param string avatar: Avatar url
  :returns: String avatar url

JCClient.username
-----------------

.. js:function:: JCClient.avatar([avatar])

  Get or set username

  **Example**

  .. code-block:: javascript

   // get username
   var username = jc.username();

   // set username
   jc.username(username);

  :param string avatar: Username
  :returns: String username


JCClient.users
--------------

.. js:function:: JCClient.users()

  Get all the users in the room

  **Example**

  .. code-block:: javascript

   // get avatar
   var users = jc.users();

  :returns: Array of users objects

  * ``name`` - Username
  * ``avatar`` - Avatar url
  * ``admin`` - Boolean if user is admin


JCClient.user
-------------

.. js:function:: JCClient.user(userid)

  Get a specific user

  **Example**

  .. code-block:: javascript

   // get avatar
   var user = jc.user("me");

  :param string userid: Userid or ``me`` for current user's info
  :returns: User object or null

  * ``name`` - Username
  * ``avatar`` - Avatar url
  * ``admin`` - Boolean if user is admin


JCClient.broadcastAudio
-----------------------

.. js:function:: JCClient.broadcastAudio([broadcast])

  Get or set broadcast audio setting

  **Example**

  .. code-block:: javascript

   // mute audio
   jc.broadcastAudio(false);
   var broadcast = jc.broadcastAudio();

  :param boolean avatar: Broadcast audio
  :returns: Boolean broadcast audio state


JCClient.broadcastVideo
-----------------------

.. js:function:: JCClient.broadcastVideo([broadcast])

  Get or set broadcast video setting

  **Example**

  .. code-block:: javascript

   // disable video
   jc.broadcastVideo(false);
   var broadcast = jc.broadcastVideo();

  :param boolean avatar: Broadcast video
  :returns: Boolean broadcast video state


JCClient.getSources
-------------------

.. js:function:: JCClient.getSources(callback)

  Get the available audio or video sources.

  **Example**

  .. code-block:: javascript

   jc.getSources(function(sources) {
       for (var i=0; i<sources.length; i++) {
           var source = sources[i];
           console.log('source: ' + source.id + ' kind: ' + source.kind + ' label: ' + source.label);
       }
   });

  :param function callback: Callback function

JCClient.setAudioSourceId
-------------------------

.. js:function:: JCClient.setAudioSourceId(sourceId)

  Set the audio source id.  If set to null or empty string, the default will be selected.  Must call
  resetLocalVideo() in order to see the new source being used.

  **Example**

  .. code-block:: javascript

   jc.setAudioSourceId(sourceId);

  :param String sourceId: sourceId of kind 'audio' retrieved from getSources()

JCClient.setVideoSourceId
-------------------------

.. js:function:: JCClient.setVideoSourceId(sourceId)

  Set the video source id.  If set to null or empty string, the default will be selected.  Must call
  resetLocalVideo() in order to see the new source being used.

  **Example**

  .. code-block:: javascript

   jc.setVideoSourceId(sourceId);

  :param String sourceId: sourceId of kind 'video' retrieved from getSources()

JCClient.on
-----------

.. js:function:: JCClient.on(eventName, callback)

  Register an event handler.

  **Example**
  
  .. code-block:: javascript

   jc.on('joined', function(e, userid) {
     ...
   });

   jc.on('left', function(e, userid) {
     ...
   });

  :param string eventName: Name of the event to register callback.
  :param function callback: Callback function

  * ``joined`` - User has joined.

    .. js:function:: function(e, userid) { ... }

  * ``userLeft`` - User has left.

    .. js:function:: function(e, userid) { ... }

  * ``remoteVideoAdded`` - Remote video added.

    .. js:function:: function(e, userid, video) { ... }

  * ``remoteVideoRemoved`` - Remote video removed.

    .. js:function:: function(e, userid) { ... }

  * ``localVideoUpdated`` - Local video stream has been updated.

    .. js:function:: function(e, stream) { ... }

  * ``broadcastState`` - Update broadcast state. If video or audio is enabled.

    .. js:function:: function(e, userid, state) { ... }

  * ``updateName`` - User name updated.

    .. js:function:: function(e, userid, name) { ... }

  * ``updateAvatar`` - User avatar updated.

    .. js:function:: function(e, userid, avatar) { ... }

  * ``chatMessage`` - Text message received.

    .. js:function:: function(e, userid, msg) { ... }

  * ``dataMessage`` - Data message received.

    .. js:function:: function(e, userid, msg) { ... }