[jitsi-dev] Jirecon XMPP component protocol design


#1

Hello everyone

I am Lishunyang from Peking University, China. Recently I was working
on Jirecon[1] project with Boris' guide.

Jirecon is a server-side application, but we want to implement it as a
XMPP component just like jitsi-videobridge, so that it can be used
much more easier. For example, users can just click one button in
Jitsi-meet, then Jirecon component start recording the conference.

We have discussed the interaction protocol between Jitsi-meet and
Jirecon component, and here is what we have gotten:

If you are interested in it, we can discuss it together:D
Or if you have some advice, just tell me:D

# Jirecon Protocol #

## Introduction ##

Terms
  - Jirecon component. It is an XMPP component just like
Jitsi-videobridge which is used for recording Jitsi-meet conference.
  - Client. It is Jitsi-meet web client.
  - Recording session. A recording process of specified Jitsi-meet
conference.

This document tries to define the interaction protocol used by Jirecon
component and client. Through this protocol, client and Jirecon
component can interact and record specified Jitsi-meet conference.
(Record video and audio stream)

## Interaction example ##

In the process of interaction, client is the active side while Jirecon
component is passive side.
  - Client sends commands to Jirecon component, letting component do
something.
  - Jirecon component listens to the commands, records meeting and
sends reply.

Here are two simple interaction examples. The numbers in brackets
indicate packet type(see Packet Design).

1. Normal scene

  client XMPP component
    > >
    > 'Hey, start recording'(1) |
1 |------------------------------------------->|
    > 'Roger, initiating'(6) |
2 |<-------------------------------------------|
    > 'Hey, recording has started'(3) |
3 |<-------------------------------------------|
    > 'Roger'(8) |
4 |------------------------------------------->|
    > >
    > Recording... |
    > >
    > 'Hey, stop recording'(2) |
5 |------------------------------------------->|
    > 'Roger, stopping'(7) |
6 |<-------------------------------------------|
    > 'Hey, recording has stopped'(4) |
7 |<-------------------------------------------|
    > 'Roger'(8) |
8 |------------------------------------------->|
    > >

2. Abnormal scene

  client XMPP component
    > >
    > 'Hey, start recording'(1) |
1 |------------------------------------------->|
    > 'Roger, initiating'(6) |
2 |<-------------------------------------------|
    > 'Hey, recording has started'(3) |
3 |<-------------------------------------------|
    > 'Roger'(8) |
4 |------------------------------------------->|
    > >
    > Recording... |
    > >
    > 'Hey, recording has aborted'(5) |
5 |<-------------------------------------------|
    > 'Roger'(8) |
6 |------------------------------------------->|
    > >

## Packet Design ##

The general idea is to add a packet extension called recording
extension to IQ packet.

···

+----------------+

iq |

+----------------+

+-----------+ |
> recording | |
> packet | |
> extension | |
+-----------+ |

+----------------+

Some attributes should be set in the recording extension, such as:
  1. action
     Possible values: 'start', 'stop', 'info'.
     'start'/'stop' means to start/stop a recording, 'info' means to
notify recording information.
  2. status
     Possible value: 'initiating', 'recording', 'stopping', 'stopped'.
It MUST be set in packet sent from component.
     Status of specified recording session.
  3. mucjid
     JID of specified recorded Jitsi-meeting. It is ONLY set in
starting command.
  4. dst
     It indicates where does the recording session output so client
can get recorded video files. The specified definition hasn't been
decided yet, maybe it's an URI or something else. It is ONLY set in
"Recording Info" packet.
  5. rid
     Identifier of specified recording session. It is generated by
Jirecon component and MUST be set in IQ packet during post-interaction.

Some rules:
  1. All packet should set "rid" in order to identify recording
session, except for the first command packet sent from client, because
ONLY Jirecon component can generate "rid".
  2. All packet sent from Jirecon component should set "status", to
tell client how's the recording session going.

Now we come up with 8 type of IQ packet(IQ-set or IQ-result) of
interaction:
+----+----+-------+--------+----------+----------+------------------+

No. |id |action |status |From |To |Meaning |

+----+----+-------+--------+----------+----------+------------------+

1 | |start | |client |component |Start a recording |

+----+----+-------+--------+----------+----------+------------------+

2 |yes |stop | |client |component |Stop a recording |

+----+----+-------+--------+----------+----------+------------------+

3 |yes |info |started |component |client |Notify client the |
   > > > > > >recording has |
   > > > > > >started |

+----+----+-------+--------+----------+----------+------------------+

4 |yes |info |stopped |component |client |Notify client the |
   > > > > > >recording has |
   > > > > > >stopped |

+----+----+-------+--------+----------+----------+------------------+

5 |yes |info |aborted |component |client |Notify client the |
   > > > > > >recording has |
   > > > > > >aborted |

+----+----+-------+--------+----------+----------+------------------+

6 |yes |info |initiat-|component |client |Notify client the |
   > > >ing | | |recording is |
   > > > > > >initiating |

+----+----+-------+--------+----------+----------+------------------+

7 |yes |info |stopping|component |client |Notify client the |
   > > > > > >recording is |
   > > > > > >stopping |

+----+----+-------+--------+----------+----------+------------------+

8 |yes |info | |client |component |Ack packet |

+----+----+-------+--------+----------+----------+------------------+

Here are packet examples:

Packet 1. Start Command.
When client wants to start a recording, it will send a starting
command to component:
+-------------------------------------------------------------------+

<iq type="set" |
   to="jirecon@jirecon.example.com" |
   from="client@example.com" |
   id="11:sendIQ'> |
  <recording xmlns='http://jitsi.org/protocol/jirecon' |
             action='start' |
             mucjid='call@conference.example.com' |
             rid=''/> |
</iq> |

+-------------------------------------------------------------------+
"Start Command" MUST contains 'mucjid' and 'rid', and the 'rid' MUST
be empty.

Packet 2. Stop Command.
When client wants to stop a recording, it will send stopping command
to component:
+-------------------------------------------------------------------+

<iq type='set' |
   to='jirecon@jirecon.example.com' |
   from='client@example.com' |
   id='11:sendIQ'> |
<recording xmlns='http://jitsi.org/protocol/jirecon' |
            action='stop' |
            rid='a73sjjvkla37jfea'/> |
</iq> |

+-------------------------------------------------------------------+

Packet 3. Start Notification.
After the Jireocn component starting a recording, it will send a
recording started notification to the client.
+-------------------------------------------------------------------+

<iq type='set' |
   to='client@example.com' |
   from='jirecon@jirecon.example.com' |
   id='11:sendIQ'> |
<recording xmlns='http://jitsi.org/protocol/jirecon' |
            action='info' |
            status='recording' |
            dst='http://jitsi.ort/jirecon/dst/a73sjjvkla37jfea' |
            rid='a73sjjvkla37jfea'/> |
</iq> |

+-------------------------------------------------------------------+
"Start Notification" MUST contains 'dst'.

Packet 4. Stop Notification.
After the Jirecon component stopping a recording, it will send a
recording stopped notification to the client.
+-------------------------------------------------------------------+

<iq type='set' |
   to='client@example.com' |
   from='jirecon@jirecon.example.com' |
   id='11:sendIQ'> |
<recording xmlns='http://jitsi.org/protocol/jirecon' |
            action='info' |
            status='stopped' |
            rid='a73sjjvkla37jfea'/> |
</iq> |

+-------------------------------------------------------------------+

Packet 5. Abort Notification.
When Jirecon component has to abort a recording session for some
failure, it will send a recording aborted notification to the client.
+-------------------------------------------------------------------+

<iq type='set' |
   to='client@example.com' |
   from='jirecon@jirecon.example.com' |
   id='11:sendIQ'> |
<recording xmlns='http://jitsi.org/protocol/jirecon' |
            action='info' |
            status='aborted' |
            rid='a73sjjvkla37jfea'/> |
</iq> |

+-------------------------------------------------------------------+

Packet 6. Start Command Reply.
When Jirecon component receives start command, it will initialize
recording session and send back a reply.
+-------------------------------------------------------------------+

<iq type='result' |
   to='client@example.com' |
   from='jirecon@jirecon.example.com' |
   id='11:sendIQ'> |
<recording xmlns='http://jitsi.org/protocol/jirecon' |
            action='info' |
            status='initializing' |
            rid='a73sjjvkla37jfea'/> |
</iq> |

+-------------------------------------------------------------------+
"Start Command Reply" ONLY means Jirecon component starts to prepare
for recording. If the recording session has started or failed, Jirecon
component will send another "Start Notification" or "Abort
Notification" to client.

Packet 7. Stop Command Reply.
When Jirecon component receives stop command, it will send back a
reply and then try to stop recording.
+-------------------------------------------------------------------+

<iq type='result' |
   to='client@example.com' |
   from='jirecon@jirecon.example.com' |
   id='11:sendIQ'> |
<recording xmlns='http://jitsi.org/protocol/jirecon' |
            action='info' |
            status='stopping' |
            rid='a73sjjvkla37jfea'/> |
</iq> |

+-------------------------------------------------------------------+
"Stop Command Reply" ONLY means Jirecon component starts to stop
reocording. If the recording session has been stopped successfully,
Jirecon component will send a "Stop Notification" to client.

Packet 8. Client ACK.
Whenever client receives IQ-set from Jirecon component, it sends an
IQ-result back to component.
+-------------------------------------------------------------------+

<iq type='result' |
   to='jirecon@jirecon.example.com' |
   from='client@example.com' |
   id='11:sendIQ'/> |

+-------------------------------------------------------------------+

## XML Schemas ##
+---------------------------------------------------------------------+

<?xml version='1.0' encoding='UTF-8'?> |
                                                                    >
<xs:schema |
   xmlns:xs='http://www.w3.org/2001/XMLSchema' |
   targetNamespace='http://jitsi/org/protocol/jirecon' |
   xmlns='http://jitsi/org/protocol/jirecon' |
   elementFormDefault='qualified'> |
                                                                    >
<xs:element name='recording'> |
   <xs:complexType> |
     <xs:attribute name='action' use='required'> |
       <xs:simpleType> |
         <xs:restriction base='xs:NCName'> |
           <xs:enumeration value='start'/> |
           <xs:enumeration value='stop'/> |
           <xs:enumeration value='info'/> |
         </xs:restriction> |
       </xs:simpleType> |
     </xs:attribute> |
     <xs:attribute name='status' use='optional'> |
       <xs:simepleType> |
         <xs:restriction base='xs:NCNname'> |
           <xs:enumeration value='initiating'/> |
           <xs:enumeration value='recording'/> |
           <xs:enumeration value='stopping'/> |
           <xs:enumeration value='stopped'/> |
           <xs:enumeration value='aborted'/> |
         </xs:restriction> |
       </xs:simpleType> |
     </xs:attribute> |
     <xs:attribute name='mucjid' type='xs:string' use='optional'/> |
     <xs:attribute name='rid' type='xs:string' use='required'/> |
     <xs:attribute name='dst' type='xs:anyURI'/> |
   </xs:complexType> |
</xs:element> |
</xs:schema> |

+---------------------------------------------------------------------+

- -Li

[1] Jircon is a server-side application to record Jitsi-meet
conference into local files.

- --
Shunyang Li
School of Electronics Engineering & Computer Science
Peking University, China
Email: lishunyang@pku.edu.cn