Tigase Meet Protocol

Abstract: Tigase Meet allows you to have multi-user group video calls. Protocol defined within this document will use tigase:meet:0 namespace.

Table of contents

• 1. Determining support
• 2. How it work
  • 2.1. Existing group call (MIX or MUC)
  • 2.2. Ad-hoc group call (many 1-1 client)
• 3. Use cases
  • 3.1. Managing the call
    • 3.1.1 Creating a group call
    • 3.1.2. Allowing user access to the call
    • 3.1.2. Deny user access to the call
  • 3.2. Establishing call
    • 3.2.1. Joining the call
    • 3.2.2. Inviting participants to the call
    • 3.2.3. Accepting invitation
    • 3.2.4. Notify invitation sender of a failure
    • 3.2.5. Rejecting invitation
    • 3.2.6. Notifications about video publishers
      • 3.2.6.1. Notifying about new publisher
      • 3.2.6.2. Notifying about gone publisher
• 4. TODOs

1. Determining support

If an entity supports Tigase Meet, it should advertise that fact by returning a feature of tigase:meet:0 in response to the XEP-0030: Service Discovery information request.

Additionally entity should advertise media types for which it supports group calls (ie. audio, video) as a feature composed of tigase:meet:0:media: and media name, ie. audio.

Example 1. Service discovery information request

<iq from='user1@example.com/res-1'
    id='ku6e51v3'
    to='meet.example.com'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

Example 2. Service discovery information response

<iq from='meet.example.com'
    id='ku6e51v3'
    to='user1@example.com/res-1'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='tigase:meet:0'/>
    <feature var='tigase:meet:0:media:audio'/>
    <feature var='tigase:meet:0:media:video'/>
  </query>
</iq>

2. How it work

2.1. Existing group call (MIX or MUC)

If MUC room or MIX channel are advertising support for tigase:meet:0 it must act as a video group chat. That means, that room or channel bare JID will be handling/forwarding (accepting and answering) Jingle session requests required to establish a group call.

In this case, client wanting to join the group call, will not create a group call, but will use a room or channel bare JID to initiate a call as specified in Joining the call

2.2. Ad-hoc group call (many 1-1 client)

If client wants to create an ad-hoc group call, it needs to find a component supporting tigase:meet:0 feature and proceed with Creating a group call, Joining the call and then Inviting participants to the call.

3. Use cases

3.1. Managing the call

3.1.1 Creating a group call

Clients sends <iq/> stanza of type set to the bare JID of the video conferencing component with a <create/> element qualified by the tigase:meet:0 namespace. <create/> element must contain one <participant/> element for each participant which should be invited to the newly crated group call and jid attribute of the element should contain bare JID of the participant. <create/> element. Additionally, <create/> element should contain <media/> elements with type attribute set to the media type name which are allowed in the group call, ie. audio or video.

<iq type='set' id='create-1' to='meet.example.com'>
	<create xmlns='tigase:meet:0'>
        <media type="audio" />
        <media type="video" />
		<participant>user2@example.com</participant>
		<participant>user3@example.com</participant>
  </create>
</iq>

Component will respond with <iq/> of type result and <create/> element qualified by tigase:meet:0 namespace which will contain an id attribute with which value will be a localpart of the JID of newly created ad-hoc call. Domain of this JID will match domain of the component JID.

<iq type='result' id='create-1' from='meet.example.com'>
	<create id='23423' xmlns='tigase:meet:0'/>
</iq>

3.1.2. Allowing user access to the call

To allow new user access to the call, meet owner’s client sends <iq/> stanza of type set to the bare JID of the group call with a <allow/> element qualified by the tigase:meet:0 namespace. allow element must contain one <participant/> element for each participant which should be added to JIDs allowed to join the group call.

<iq type='set' id='create-1' to='meet.example.com'>
	<allow xmlns='tigase:meet:0'>
		<participant>user2@example.com</participant>
		<participant>user3@example.com</participant>
  </allow>
</iq>

Component will respond with <iq/> of type result.

<iq type='result' id='create-1' from='meet.example.com' />

3.1.2. Deny user access to the call

To deny new user access to the call, meet owner’s client sends <iq/> stanza of type set to the bare JID of the group call with a <deny/> element qualified by the tigase:meet:0 namespace. deny element must contain one <participant/> element for each participant which should be removed from JIDs allowed to join the group call.

<iq type='set' id='create-1' to='meet.example.com'>
	<deny xmlns='tigase:meet:0'>
		<participant>user2@example.com</participant>
		<participant>user3@example.com</participant>
  </deny>
</iq>

Component will respond with <iq/> of type result.

<iq type='result' id='create-1' from='meet.example.com' />

Note: If denied users would be in the call, he will be kicked out.

3.2. Establishing call

3.2.1. Joining the call

Client initiates jingle call with the bare JID of the group call as it would during 1-1 Jingle session establishment.

In the response, component will not only establish this session, but will also initiate a Jingle session to the client. Client should accept this incoming session automatically (it will be coming from the same group chat bare JID). This incoming session initiation may be delayed until at least one other participant will join the group call.

3.2.2. Inviting participants to the call

Client sends <message/> to each participant which should join the call. Message must contain <propose/> element qualified by tigase:meet:0 namespace with id attribute used for identification of invitation. <propose/> element must contain <media/> elements for each media type supported in the group call.

<message to='user2@example.com'>
	<propose xmlns='tigase:meet:0' id='a73sjjvkla37jfea' jid='23423@meet.example.com'>
        <media type="audio"/>
        <media type="video"/>
    </propose>
</message>

3.2.3. Accepting invitation

Client will respond with a <message/> of the same type as invitation with <accept/> element qualified by tigase:meet:0 namespace and with idattribute equal id of the invitation.

<message to='user2@example.com'>
	<accept xmlns='tigase:meet:0' id='a73sjjvkla37jfea' />
</message>

and will begin Jingle session establishment as specified in Joining the call. If session establishment will fail for any reason, client should Notify invitation sender of a failure.

3.2.4. Notify invitation sender of a failure

Client will send a <message/> of the same type as invitation with <failure/> element qualified by tigase:meet:0 namespace and id attribute equal id of the invitation.

<message to='user2@example.com'>
	<failure xmlns='tigase:meet:0' id='a73sjjvkla37jfea' />
</message>

3.2.5. Rejecting invitation

Client will respond with a <message/> of the same type as invitation with <reject/> element qualified by tigase:meet:0 namespace and with idattribute equal id of the invitation.

<message to='user2@example.com'>
	<reject xmlns='tigase:meet:0' id='a73sjjvkla37jfea' />
</message>

NOTE: Clients should listen for those message-based invitations using carbons as they do for Jingle Message Initiation and act in the same way, so that accepting a call on a single client would silence other clients of the same user.

3.2.6. Notifications about video publishers

Meet component will notify joined meet participant about other meet participants joining or leaving video call (starting to publish or stopping to publish).

3.2.6.1. Notifying about new publisher

Meet component will send <iq/> stanza of type set to the client with <joined/> element qualified by tigase:meet:0 namespace. This element should contain one or more <publisher/> elements describing publishers for each publisher joining the call. Each publisher element MUST contain jid attribute with a bare JID of a participant joining the call. publisher element MUST contain one or more <stream> elements with mid attribute containing mid of a Jingle content which contains audio/video/data streams sent by participant.

<iq type='set' to='user2@example.com'>
    <joined xmlns='tigase:meet:0'>
        <participant jid='user@example.com'>
            <stream mid='0' />
            <stream mid='1' />
        </participant>
    </joined>
</iq>

NOTE: Notifications about participants will not cover participant himself. There will be no notification about participant user@example.com sent to participant user@example.com.

3.2.6.2. Notifying about gone publisher

Meet component will send <iq/> stanza of type set to the client with <left/> element qualified by tigase:meet:0 namespace. This element should contain one or more <publisher/> elements describing publishers for each publisher joining the call. Each publisher element MUST contain jid attribute with a bare JID of a participant joining the call. publisher element MUST contain one or more <stream> elements with mid attribute containing mid of a Jingle content which contains audio/video/data streams sent by participant.

<iq type='set' to='user2@example.com'>
    <left xmlns='tigase:meet:0'>
        <participant jid='user@example.com'>
            <stream mid='0' />
            <stream mid='1' />
        </participant>
    </left>
</iq>

NOTE: Notifications about participants will not cover participant himself. There will be no notification about participant user@example.com sent to participant user@example.com.

4. TODOs

1. What if we want to invite people from the room/channel to that call? Should we send an invite? or just a message to the room/channel? To invite participants in the call we would send a message to the channel.
2. Should we kick out people, when they are kicked out from the channel/room? or i other cases as well? People should be kicked out of the group call when they leave the channel.
3. We should consider a feature of manual “destruction” of the ad-hoc group call.
4. We should consider to allow inviting or kicking out people from the call.
5. It would be useful to add “metadata” exchange, so clients would know which A/V stream is sent by which participant (which bare JID). Added with <joined/> and <left/>
6. Verify that usage of tigase:meet:0:media:audio is a good idea for versioned features.