jibri-spec.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Jitsi Broadcasting Infrastructure Subprotocol for MUC</title>
  <abstract>
    This specification documents the Jitsi Broadcasting Infrastructure (Jibri)
    Multi-User Chat subprotocol for controlling the broadcasting and recording
    infrastructure.
  </abstract>
  &LEGALNOTICE;
  <number>jibri</number>
  <status>ProtoXEP</status>
  <type>Informational</type>
  <sig>Private</sig>
  <approver/>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0045</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>jibri</shortname>
  &sam;
  <revision>
    <version>0.0.1</version>
    <date>2016-09-20</date>
    <initials>ssw</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>
    The Jitsi Broadcasting Infrastructure (Jibri) is used by Jitsi to record and
    broadcast A/V streams from conferences. Each Jibri instance creates an XMPP
    client-to-server connection as defined in &rfc6120;, joins a pre-configured
    &xep0045; room, and then accepts commands from a Jitsi Conference Focus
    (Jicofo) using a custom subprotocol documented herein.
  </p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>
    The following requirements should be met by a future version of this
    protocol:
  </p>
  <ul>
    <li>
      Ability to discover and select multiple recording methods supported by a
      Jibri.
    </li>
    <li>
      Jibris should support servicing multiple clusters, deployments, or
      servers.
    </li>
  </ul>
</section1>
<section1 topic='Glossary' anchor='glossary'>
  <dl>
    <dt>Conference Focus</dt>
    <dd>
      The moderator, admin, or other controling agent in the conference that
      determines who has the ability to speak
    </dd>
  </dl>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Setting Jibri Status' anchor='usecases-status'>
    <p>
      When a Jibri joins a MUC, or any other time its status changes (eg. it
      becomes available for recording or is selected and becomes in use and
      unavailable for recording), it needs to signal its availability to begin
      recording or its current status. To do so all presences sent by a Jibri
      MUST contain a jibri-status payload qualified by the
      http://jitsi.org/protocol/jibri namespace with a status attribute
      set to the current status of the Jibri.
    </p>
    <p>
      The status attribute MUST be one of:
    </p>
    <ul>
      <li>idle (the Jibri is available to begin recording or streaming)</li>
      <li>busy (the Jibri is in use and another Jibri should be selected)</li>
    </ul>
    <example caption="Jibri advertises that it is available for use"><![CDATA[
<presence xmlns='jabber:client'
          xml:lang='en'
          to='e8cffff5-5b63-4b69-a7f2-0ebd60e4c055@example.net/jicofo'
          from='thebrewery@muc.example.net/jibri-09919948929524391'>
  <jibri-status status='idle' xmlns='http://jitsi.org/protocol/jibri'/>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item jid='jibri@auth.example.net/1cd7a5ea-2b60-4301-901e-010b3f4c2da2' affiliation='owner' role='moderator'/>
  </x>
</presence>
]]></example>
  </section2>
  <section2 topic='Start Recording' anchor='usecases-start-recording'>
    <p>
      When a user wishes to begin recording using a Jibri they send an IQ to the
      conference focus (or another admin from which Jibri will accept commands)
      containing a jibri payload qualified by the
      http://jitsi.org/protocol/jibri namespace and containing an action to
      perform (start, stop) and (if the action is 'start') a YouTube stream ID.
    </p>
  <example caption="User instructs the focus to select a Jibri"><![CDATA[
<iq to='weirdsisterstoilwearily@conference.example.net/focus'
    type='set'
    xmlns='jabber:client'
    id='c5c8a24e-4054-4e73-ac05-fe8c92ba1d77'>
  <jibri xmlns='http://jitsi.org/protocol/jibri'
    action='start'
    streamid='1111-1111-1111-1111'/>
</iq>
]]></example>
  <p>
    If the user is allowed to begin recording, the focus selects a Jibri and
    sends a similar IQ to the selected Jibri. This IQ should also contain the
    YouTube stream ID as an attribute, but should also have a room attribute
    indicating what room the Jibri should join to begin recording. The focus
    SHOULD only send the start IQ to an available Jibri (one that is advertising
    its status as "idle"). If the Jibri is not available (eg. because it is
    shared between deployments and was just selected for use by another focus
    but has not sent a presence update yet, or because it cannot join the given
    MUC room or no room was specified) it SHOULD return a stanza error with
    condition service-unavailable and error code 503 as defined in
    <cite>RFC6120</cite>. If the Jibri can begin recording it should immediately
    broadcast a presence to the MUC indicating that it is now busy.
  </p>
  <example caption="Focus instructs a Jibri to start recording"><![CDATA[
<iq from='jibricontrol@conference.example.net/focus'
    to='jibricontrol@conference.example.net/jibri1'
    room='theconferenceroom@conference.example.net'
    type='set'
    xmlns='jabber:client'
    id='c5c8a24e-4054-4e73-ac05-fe8c92ba1d77'>
  <jibri xmlns='http://jitsi.org/protocol/jibri'
    action='start'
    streamid='1111-1111-1111-1111'/>
</iq>
]]></example>
  <example caption="Jibri replies with an error"><![CDATA[
<iq type="error"
    to="be910704-f25a-48d0-905b-98eb9a84e736@sam.jitsi.net/059ccbcf-857a-439d-8090-e0d52b1f7a20"
    from="brightantelopesterminateanxiously2@conference.sam.jitsi.net/focus"
    id="8c2eb3d7-af05-4c38-98fe-e820e7706624:sendIQ"
    xmlns="jabber:client">
<iq>
]]></example>
	</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>
    The YouTube stream ID that is sometimes sent to a Jibri and the conference
    focus can be used to record arbitrary video streams to the account of the
    user that generated the stream ID. It should only ever be sent over TLS and
    should be handled with care on the Focus and Jibri.
  </p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>This document requires no interaction with the &REGISTRAR;.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <p>TODO</p>
</section1>
</xep>