[muji/master] expand + clarify things

[Dafydd Harries]

---
 xep/mingle.xml |   84 ++++++++++++++++++++++++++++++++++++-------------------
 1 files changed, 55 insertions(+), 29 deletions(-)

diff --git a/xep/mingle.xml b/xep/mingle.xml
index 14c4d51..c568695 100644
--- a/xep/mingle.xml
+++ b/xep/mingle.xml
@@ -44,18 +44,18 @@ Mingle conferences are held in <cite>XEP-0045</cite> rooms.
 </section1>
 
 <section1 topic="How it works" anchor="howitworks">
-Each participant in a Mingle conference announce the definitions of the
-contents that they provide in their MUC presence. This serves two purposes.
-Firstly, so that each participant knows which contents every other participant
-provides. Secondly, so that there is a global payload type (PT) mapping for
-the various contents, so that clients only need to encode and payload each
-content that they provide once.
+A Mingle conference has a number of contents, each of which has unique name.
+content type, and an encoding. Each participant may provide a stream for each
+content, and communicates which contents they are willing to provide streams
+for, along with encoding information, in their MUC presence. This serves two
+purposes. Firstly, so that each participant knows which contents every other
+participant provides. Secondly, so that there is a global payload type (PT)
+mapping for the various contents, so that clients only need to encode and
+payload each content that they provide once.
 
 Participants can participate in a read-only mode by not advertising any
-contents. Participants are not obliged to initiate Jingle sessions with all
-other participants. If they do initiate a Jingle session with another
-participant, they are not required to accept all the contents that are
-available. For example, a Mingle client might choose to only request audio
+contents. Participants are not required to participate all the contents that
+are available. For example, a Mingle client might choose to only request audio
 streams.
 </section1>
 
@@ -93,22 +93,46 @@ streams.
 </section1>
 
 <section1 topic='Joining a conference' anchor='starting'>
-  Other members of the MUC can join a conference by first updating their own
-  presence with a Mingle stanza reflecting the contents they want to
-  participate in. All contents with the same name describe one global content
-  and have to be compatible. That is for a given payload id the codec name and
-  (receive) parameters MUST match and each content MUST have at least some
-  payload id that match those of all other participants.
+  A client that is a member of a MUC joins a Mingle conference by first
+  updating their MUC presence with a Mingle stanza reflecting the contents
+  they want to provide.
 
-  Afterwords a normal jingle session MUST initiated to all participants
-  previously in the conference. The name of a content in the jingle session
-  refers to the content with the same name in the Mingle stanza presence. The
-  jingle content MUST have exactly the same description as the Mingle content
-  it refers to.
+  A Mingle client MUST NOT advertise Mingle capabilities in their MUC presence
+  before they have received MUC presence from every other participant in the
+  MUC, because otherwise they cannot reliably create a payload type mapping
+  that's compatible with those of the existing participants. This means that
+  the initial MUC presence must not contain Mingle data.
 
-  To leave a conference first the Mingle stanza presence MUST be removed from
-  the participants presence and afterwards it SHOULD terminate all jingle
-  sessions.
+  When a client adds a payload ID to a content description, it MUST have the
+  same codec name and encoding parameters as the corresponding entries in
+  other participants' payload maps for that content. For instance, if Alice
+  defines a payload type with ID 98, codec Speex and a a clock rate of 8000
+  for a content called “voice0”, then Bob must define payload type 98
+  identically or not at all for that content.
+
+  Furthermore, each content description MUST include at least one payload type
+  that every other participant supports. In other words, the intersection of
+  payload type mappings in descriptions for a content must not be the empty
+  set. This avoids clients having to encode the same stream multiple times,
+  which can be very costly, and also allows sending the encoded data only once
+  where the transport makes this possible (e.g. IP multicast).
+
+  Once a client has constructed content descriptions and advertised them in
+  its MUC presence, it MUST initiate a Jingle session with every other
+  participant. The requirement that it is the joining participant that
+  initiates sessions avoids race conditions.
+
+  Jingle sessions are initiated between the MUC JIDs of participants. That is,
+  the Jingle session-intiate stanza is sent from one MUC JID to another. This
+  allows participants to easily identify sessions as belonging to a Mingle
+  conference. Content names inside Mingle-related Jingle sessions always refer
+  to the content with the same name inside the Mingle conference.
+
+  To leave a conference first the Mingle information, presence MUST first be
+  removed from the participant's presence; subsequently it SHOULD terminate
+  all Jingle sessions related to that conference. Updating the presence first
+  reduces the likelihood of situations where new participants initiate
+  sessions with participants who are leaving the conference.
 </section1>
 
 <section1 topic='TODO' anchor='TODO'>
@@ -122,11 +146,13 @@ streams.
   <li> Describe how to add/remove contents.
   </li>
   <li> Add support for relays. Not all participants might have the necessary
-       upstream bandwidth to stream to everyone. A relay can help here by
-       relaying the RTP streams of on or more participants. The relay could
-       either be a specialised component or just another client. </li>
-  <li> Add support for mixers. In the same way. Not all participant might have
-       the CPU power to decode all streams or the downstream bandwidth to
+       upstream bandwidth to stream to everyone. A relay can help by relaying
+       the RTP streams of on or more participants. The relay could either be a
+       specialised component or just another client. Participants will provide
+       relay services by advertising them in their MUC presence.
+  </li>
+  <li> Add support for mixers in a similar way. Not all participants might
+       have the CPU power to decode all streams or the downstream bandwidth to
        receive all streams. A mixer could mix various media streams into one
        media stream and relay that. Again the mixer could be a specialised
        component or just another client.
-- 
1.5.6.5