This REQUIRED attribute is a counter to maintain the integrity of real-time text. Senders MUST increment this value by 1 for each subsequent edit to the same real-time message, including when appending new text. Recipients MUST monitor the seq value as an integrity check on received real-time text. The bounds of seq is 31-bits, the range of positive values for a signed 32-bit integer. See Keeping Real-Time Text Synchronized.

This attribute signals events for real-time text.

If the event attribute is omitted, event='edit' is assumed as the default. When Action Elements are used (e.g. text appends, insertions and deletions), the <rtt/> element MAY contain one or more of any action elements, in any order. When action elements are not allowed, the <rtt/> element MUST be empty. Recipient clients MUST ignore <rtt/> elements containing unrecognized event values.

This attribute is used only if Last Message Correction (XEP-0308) is implemented along with this specification. See Usage with Last Message Correction to enable real-time text during editing of the previous message.

This real-time text standard simply provides early delivery of text before the <body/> element. The <body/> element continues to follow the XMPP IM specification. In particular, XMPP implementations need to ignore XML elements they do not understand. Clients, that do not support real-time text, will continue to behave normally, displaying complete lines of messages as they are delivered.

This is a short summary of action elements that operate on a real-time message.

These elements are kept compact in order to save bandwidth, since a single <rtt/> element can contain a huge number of action elements (e.g. during Preserving Key Press Intervals). See List of Action Elements for details.

• For Element <e/> – Erase Text:
  The n attribute is a length value, in number of characters. If n is omitted, the default value of n MUST be 1.

• For Element <t/> – Insert Text and Element <e/> – Erase Text:
  The p attribute is an absolute position value, as a character position index into the real-time message, where 0 represents the beginning of the message. If p is omitted, the default value of p MUST point to the end of the message (i.e. p is set to the current length of the real-time message).

• For the purpose of this specification, the word "character" represents a single Unicode code point. See Unicode Character Counting.

• Senders MUST NOT use negative values for any attribute, nor use p values bigger than the current message length. However, recipients receiving such values MUST clip negative values to 0, and clip excessively high p values to the current length of the real-time message. Modifications only occur within the boundaries of the current real-time message.

Recipients MUST be able to process all <t/> and <e/> action elements for incoming <rtt/> transmissions, even if senders do not use all of these for outgoing <rtt/> transmissions (e.g. Simple Real-Time Text). Support for <w/> is RECOMMENDED for both senders and recipients, in order to accommodate Preserving Key Press Intervals. Recipients MUST ignore unexpected or unsupported elements within <rtt/>, while continuing to process subsequent action elements. Compatibility is ensured via Namespace Versioning. Action elements are immediate child elements of the <rtt/> element, and are never nested. See examples in Use Cases.

By following Processing Rules, the recipient client creates a new real-time message when receiving <rtt event='new'/> or <rtt event='reset'/>. Thereafter, when receiving text modifications (i.e. <rtt event='edit'/> or <rtt/> without an event attribute):

1. There MUST be an existing real-time message (created via <rtt event='new'/> or <rtt event='reset'/>);
2. Senders MUST increment the seq attribute in steps of 1, for consecutively transmitted text modifications.
3. Recipients MUST verify that the seq attribute is incrementing by 1, for consecutively received text modifications.

Loss of sync occurs during receiving text modifications if the seq attribute do not increment by 1 as expected, or if no real-time message exists. In this case:

• Recipients MUST keep the real-time message unchanged (if any exists); and
• Recipients MUST ignore subsequent text modifications (i.e. <rtt event='edit'/> or <rtt/> without an event attribute); and
• An indication can be used to show the loss of sync (e.g. color coding, modified chat state message).

Recovery occurs when the recipient receives the following:

• A <body/> element. The Body Element supersedes the real-time message.
• An <rtt/> element with an event attribute of 'new' or 'reset' (e.g. new message, or Message Refresh).

A message refresh is the sender's partially composed text being (re)transmitted via <rtt event='reset'/>. The recipient client(s) can seamlessly redisplay the real-time message as a result. This allows real-time text to resume quickly, without waiting for senders to start a new message:

This is a retransmission of the entire real-time message. ]]>

The message refresh SHOULD be transmitted regularly at an average interval of 10 seconds during active typing or composing. This interval is frequent enough to minimize user waiting time, while being infrequent enough to not cause a significant bandwidth overhead. This interval MAY vary, or be set to a longer time period, in order to reduce average bandwidth (e.g. long messages, infrequent or minor message changes). To save bandwidth, message refreshes SHOULD NOT occur continuously while the sender is idle. To allow quicker resumption of real-time text, sender clients MAY adjust the timing of the message refresh to occur right after any of the following additional events:

• When the recipient starts sending messages from a different full JID (e.g. switched clients);
• When the recipient becomes available (e.g. presence changes to 'chat');
• When the sender resumes composing after an extended pause (e.g. recipient may have cleared Stale Messages);
• When the conversation is unlocked (e.g. section 5.1 of XMPP IM);

If the recipient already has an existing real-time message from the sender, Processing Rules require that the real-time message MUST be seamlessly replaced. Thus, if the recipient is successfully Staying In Sync, the recipient user sees no visible effect since the text contained within <rtt event='reset'/> is a duplicate of the existing real-time message. If the recipient client was out of lost sync (Recovery From Loss of Sync) or it has no real-time message, the recipient user sees the real-time message immediately “catch up”.

Note: The use of <rtt event='reset'/> is not limited to message refresh, as it can contain any number of Action Elements in any order. Sender clients MAY combine a message refresh with additional action elements (e.g. re-transmitting a whole message in one Element <t/> – Insert Text, followed by some additional action elements, such as additional typing or backspacing, to seamlessly allow Preserving Key Press Intervals).

For this specification, a "character" represents a single Unicode code point. This is the same definition used in section 1.1 of IETF RFC 5198 RFC 5198: Unicode Format for Network Interchange <http://tools.ietf.org/html/rfc5198>.. For platform-independent interoperability of Action Elements, calculations on Attribute Values (p and n) MUST be based on counts of Unicode code points.

Many platforms use different internal encodings (i.e. string formats) that are different from the transmission encoding (UTF-8). These factors need to be considered:

• Multiple Unicode code points (e.g. combining marks, accents) can form a combining character sequence. This can occur in situations where there isn't a visually equivalent composite character of a single code point (e.g. when doing Unicode normalization).
  Action elements operate on Unicode code points individually.

• Unicode code points U+10000 through U+10FFFF are represented as a surrogate pair in some Unicode encodings (e.g. UTF-16).
  Action elements operate on Unicode code points as a whole, not on separate components of a surrogate pair.

• XMPP transmission uses UTF-8, which use a variable number of bytes per Unicode code point.
  Action elements operate on Unicode code points as a whole, not on separate bytes.

Lengths and positions in Attribute Values are relative to the internal Unicode text of the real-time message, independently of the directionality of actual displayed text. As a result, any valid Unicode text direction can be used with real-time text (right-to-left, left-to-right, and bidirectional). One way for implementers to visualize this, is to simply visualize Unicode text as an array of individual code points, and treat Attribute Values as array indexes.

Sender clients MUST generate real-time text (Action Elements and Attribute Values) based on the plain text version of the sender's message with pre-processing completed. This is separate from and concurrent to any displayed presentation of the same message (e.g. formatting, emoticon graphics, &xep0071;).

Pre-processing before generating real-time text includes Unicode normalization, conversion of emoticons graphics to text, removal of illegal characters, line-break conversion, and any other necessary text modifications. For Unicode normalization, sender clients SHOULD ensure the message is in Unicode Normalization Form C Unicode Standard Annex #15: Unicode Normalization Forms <http://www.unicode.org/reports/tr15/>. ("NFC"), as recommended within section 3 of RFC 5198, and within many other standards such as Canonical XML 1.0.

If Unicode combining character sequences (e.g. letter with multiple accents) are used for Element <t/> – Insert Text, then complete combining character sequences SHOULD be sent. In situations where modifications are required to an existing combining character sequence (e.g. adding an additional accent), an Element <e/> – Erase Text SHOULD be used to delete the existing combining character sequence, before transmitting a complete replacement sequence via the <t/> element. (However, recipients SHOULD NOT assume this behavior from sending clients. See Guidelines for Recipients).

For the purpose of calculating Attribute Values, any line breaks MUST be treated as a single character. Conversion of line breaks into a single LINE FEED U+000A is REQUIRED for XML processors, according to section 2.11 of XML XML: Extensible Markup Language 1.0 (Fifth Edition) <http://www.w3.org/TR/xml/>.. In addition, XML character entities are counted as a single character.

For Element <t/> – Insert Text, text MUST be obtained using compliant XML processing (including entities converted to characters). Recipient clients SHOULD ensure that the received text is in Unicode Normalization Form C ("NFC"). After this, recipient clients MUST NOT do any other modifications to resulting real-time messages. This is to allow accurate processing of subsequent Action Elements and Attribute Values (The recipient client can separately process/modify a copy of the same real-time message text, if necessary for the purpose of display presentation).

It is possible for sender clients to send Element <t/> – Insert Text with an incomplete combining character sequence (e.g. combining mark(s) without a Unicode base character). This is valid when extending an existing combining character sequence into a longer valid complete combining character sequence (e.g. adding an additional accent mark). It is also possible for senders to send Element <e/> – Erase Text to remove code points from an existing combining character sequence, into a shorter valid complete combining character sequence (e.g. removing an accent mark). In all cases, recipient clients MUST process these elements in accordance to Action Elements.

If a long Transmission Interval is used without Preserving Key Press Intervals, then incoming text will appear in intermittent bursts if the display of text is not smoothed. This hurts user experience of real-time text.

For high quality presentation of real-time text, the original look-and-feel of typing can be preserved independently of the transmission interval. This is achieved using Element <w/> – Wait Interval between other Action Elements. Sender clients can transmit the length of pauses between key presses, and send multiple key presses in a single <message/> stanza. Recipient clients that process <w/> elements are able to display the sender's typing smoothly without sudden bursts of text. See Examples of Key Press Intervals.

When key press intervals are preserved at high precision, all subtleties of typing are preserved, including the 'mood' (calm typing versus panicked or emphatic typing, etc.). Much as VoIP allows accurate packet transmission of sound, this spec allows accurate packet transmission of original typing look-and-feel. This enables the real-time feel of typing over virtually any network connection, without requiring frequent transmission intervals. Look and feel of typing is also preserved over variable latency connections including &xep0206;, mobile phone, satellite and long international connections with heavy packet-bursting tendencies.

There are specialized situations such as live transcriptions and captioning (e.g. transcription service, closed captioning provider, captioned telephone, Communication Access Realtime Translation (CART), relay services) that demands low latency transmission. Such systems typically use voice recognition and/or stenotype machines, which output text in word or phrase bursts rather than a character at a time. It can be acceptable for senders with bursty output to immediately transmit word or phrase bursts of text without buffering, as long as the average stanza rate is not excessive. This eliminates any lag caused by the Transmission Interval. It is not necessary to transmit Element <w/> – Wait Interval for real-time transcription.

Some software platforms (e.g. JavaScript, BOSH, mobile devices) may have low-precision timers that impact Transmission Interval and/or Preserving Key Press Intervals. Clients can optimize for bandwidth, performance and/or screen repaints by eliminating, merging, or ignoring Element <w/> – Wait Interval selectively, especially those containing shorter intervals. In addition, it is acceptable for the transmission interval of <rtt/> to vary, either intentionally for optimizations, or due to precision limitation, preferably within the range recommended by Transmission Interval. Compression can also be used to reduce bandwidth (e.g. TLS compression or &xep0138;).

Clients can choose to implement alternate text-smoothing methods, such as adaptive-rate character-at-a-time output, and/or word buffering for incoming real-time text. Word buffering prevents most typing mistakes from being displayed, which can be a useful mode of operation for certain recipients who may dislike watching the sender's typing mistakes.

Sender clients can simply begin transmitting real-time text (i.e. send <rtt/> elements), either immediately or upon user-initiated activation.

For one-on-one chats, it can be beneficial for clients to easily synchronize the enabling/disabling of real-time text. Upon receiving incoming real-time text, recipient clients can automatically do an appropriate response, such as:

• Activate immediately (begin transmitting <rtt/> elements too); or
• Activate after user confirmation prompt (for Privacy considerations); or
• Deny (transmit <rtt event='cancel'/>); or
• Ignore (discard incoming <rtt/> elements); or
• Display only incoming real-time text (e.g. Multi-User Chat participants control their own outgoing real-time text).

For any client, the preferred first <rtt/> element to send is <rtt event='init'/> as it can quickly signal activation of real-time text, without waiting for the sender to begin composing a new message, and since it is usable regardless of discovery. Conversely, if the sender was already composing a message when activating real-time text, Message Refresh handles this situation.

While explicit discovery is preferred (See Determining Support), the sender client can implicitly request and discover the use of real-time text, by sending <rtt event='init'/> upon activation. In the case of one-on-one chats, it is inappropriate to send any further <rtt/> elements, until support is confirmed either by incoming <rtt/> elements or via discovery. Implicit discovery makes it possible to use real-time text as an enhancement to &xep0085; (XEP-0085 Section 5.1), during all situations where it can be used. See Usage with Chat States.

Real-time text can be deactivated by transmitting <rtt event='cancel'/>, or simply by ending the chat session. Recipient clients can respond to deactivation with appropriate response(s), including:

• Stop transmitting <rtt/> elements as well (not applicable to Multi-User Chat); and
• Handle the sender's unfinished incoming real-time message; and
• Inform the recipient user that sender ended real-time text (or denied/cancelled, if no real-time text was received).

Any client can send an <rtt event='cancel'/> when ending the chat session (e.g. user closes a chat window) or when deactivating real-time text while continuing the chat session. Clients receiving <rtt event='cancel'/> do not need to also transmit <rtt event='cancel'/> back.

Senders deactivating real-time text while in the middle of composing a message, can continue composing their message without real-time text being sent. Completed messages continue to be transmitted normally via the Body Element. Recipients that no longer receive further real-time updates, can handle the incomplete sender's real-time message appropriately (e.g. clearing/greying-out/saving the message, or using Stale Messages handling).

After deactivation, any client can reactivate real-time text again using <rtt event='init'/>.

Experience has found that the most reliable method for generating real-time text, is to monitor for text changes to the sender’s message entry field, instead of key press events. Text change events have the following advantages:

• It captures all typing, including edits and deletes.
• It captures copy & paste operations, as well as edits made via a pointing device.
• It captures all automatic text changes (e.g. spell checker, auto-correct, macros, transcription, assistive devices).
• It captures characters requiring multiple key presses to compose (e.g. accents, combining marks).
• It makes no assumptions about different keyboards or input method editors (e.g. Chinese).
• Text change events are more portable across platforms, including on mobile phones.

During a text change event, the sender’s current message text can be compared to the old message text from the previous text change event. The difference in text, between consecutive text change events, is typically a one character difference (e.g. key press) or one text block difference (e.g. auto-correct, cut, paste). In order to calculate what text changes took place, the first changed character and the last changed character is determined. From this, it is simple to generate Action Elements for a single text block deletion and/or insertion. In addition, if Preserving Key Press Intervals is supported, then Element <w/> – Wait Interval records the time elapsed between text change events.

Sender software can do the following:

1. Monitor for text changes in the sender’s message. Whenever a text change event occurs, compute action element(s) and append these action element(s) to a buffer. Repeating this step during every text change event, is equivalent to recording a small sequence of typing.

2. During every Transmission Interval, all buffered action elements are transmitted in <rtt/> element in a <message/> stanza. This is equivalent to transmitting a small sequence of typing at a time.

3. If there are no message changes occurring, no unnecessary transmission takes place.

Real-time text can be generated via monitoring key presses. However, this does not have the advantages of Monitoring Message Changes Instead Of Key Presses. Care needs be taken with automatic changes to the message, generated by means other than key presses. This includes spell check auto-correct, copy and pastes, transcription, input method editors, and multiple key presses required to compose a character (i.e. accents). Key press events can miss these text changes, and this can potentially cause incorrect real-time text to be transmitted.

The use of Element <t/> – Insert Text without any attributes, simply appends text to the end of a message, while the use of Element <e/> – Erase Text without any attributes, simply erases text from the end of the message. This sending method can also be useful for special-purpose clients where mid-message editing capabilities are not used (e.g. simple transcription, news tickers, relay services, captioned telephone).

It is possible for sender clients to use Message Refresh to simply re-transmit the whole real-time message, as a method of transmitting text changes. The advantage is very simple implementation. Disadvantages can include the lack of Preserving Key Press Intervals, and extra bandwidth consumption that can occur with longer messages, unless stream compression is used. The below illustrates transmission of the real-time message “Hello there!” at a regular Transmission Interval while the sender is typing.

Hel Hello th Hello there! ]]>

A large sequence of action elements can result in an <rtt/> larger than the size of a message <body/>. This can occur normally during fast typing when Preserving Key Press Intervals during small messages. However, if the <rtt/> element becomes unusually huge (e.g. macros, multiple copy and pastes, leading to an <rtt/> exceeding one kilobyte) a Message Refresh can instead be used, in order to save bandwidth. (Stream compression is another approach.)

Clients can limit the length of the text input for the sender's message, in order to keep the size of <message/> stanzas reasonable, including during Message Refresh. Also, large <rtt/> elements may occur in situations such as large copy and pastes. To keep message stanza sizes reasonable, <rtt/> can be transmitted in a separate <message/> than the one containing <body/>.

For clients that send continuous real-time text (e.g. news ticker, captioning, speech transcription, TTY/text telephone gateway), a Body Element can be sent and then a new real-time message started immediately after, every time a message reaches a specific size. This allows continuous real-time text without real-time messages becoming excessively large.

Real-time text can be used in conjunction with XEP-0085 Chat States. It is best to handle XEP-0301 and XEP-0085 transmissions in separate <message/> stanzas. Chat states such as <composing/> or <active/> are sent separately of <rtt/> elements.

Chat states are handled as specified by XEP-0085 Chat States. The continuous transmission of real-time text corresponds to a <composing/> chat state. Therefore, the timing of the <composing/> chat state coincides with the beginning of continuous <rtt/> transmission. 

It is possible to have &xep0308; (XEP-0308) with real-time text. If XEP-0308 is implemented at the same time as this specification, the following rules apply:

• For all <rtt/> elements transmitted during composing a new message, the id attribute of <rtt/> is not used.

• For all <rtt/> elements transmitted during editing of the previous message, the id attribute of <rtt/> matches the id attribute of the old <message/> stanza containing the <body/> text being edited (See 'Business Rules' in XEP-0308). This enables recipient clients to display real-time text while the sender is editing the previously-delivered message.

• Senders clients need to transmit a Message Refresh when transmitting <rtt/> for a different message than the previously transmitted <rtt/> (i.e. the value of the id attribute changes, id becomes included, or id becomes not included). This keeps real-time text synchronized when beginning to edit a previously delivered message versus continuing to compose a new message.

• The XEP-0301 and XEP-0308 protocols operate concurrently via separate message stanzas. Thus, a message stanza never simultaneously includes both <rtt/> and <replace/>.

• The Body Element delivers a finished new message or a finished message correction (<replace/> is used with <body/> in accordance to XEP-0308).

The in-band nature of this real-time text standard makes it possible to seamlessly integrate real-time text into &xep0045; (MUC), as well as concurrent simultaneous logins.

There are situations where senders pause typing indefinitely. This can result in recipients displaying a real-time message for an extended time period. It may also be a screen clutter concern during Multi-User Chat. In addition, it may be a resource-consumption concern, as part of Congestion Considerations.

It is acceptable for recipients to clear (and/or save) incoming real-time messages that have been idle for an extended time period. There is no specific time-out period defined by this specification. For Multi-User Chat, the time-out period might be shorter because of the need to reduce screen clutter. For normal chat sessions, the time-out period might need to be longer to allow reasonable interruptions (i.e. sender pausing during a long phone call).

Senders that resume composing a message (i.e. continues a partially-composed message hours later) can do a Message Refresh, which allows recipients to redisplay the real-time message.

With real-time text, frequent screen updates can occur. Screen updates are a potential performance bottleneck, since fast typists type many key presses per second. Optimizing screen updates becomes especially important for slower platforms. The real-time message might be implemented as a separate window or separate display element.

Battery life considerations are closely related to performance, as the addition of real-time text may impact battery life. If Preserving Key Press Intervals are supported, then the implementation of Element <w/> – Wait Interval needs to be implemented in a battery-efficient manner. The Transmission Interval may vary dynamically to optimize for battery life and wireless reception. For devices where screen updates are an unavoidable inefficient bottleneck, see Low-Bandwidth and Low-Precision Text Smoothing to reduce the number of screen updates per second.

Hello Bob, this is Alice! ]]>

Final result of real-time message: "Hello, this is Alice!"
This example outputs "Hello Bob, this is Alice!" then <e n='4' p='9'/> erases 4 characters before character position index 9. The Element <e/> – Erase Text removes the text " Bob" including the preceding space character.

Hello, this is Alice! Bob ]]>

Final result of real-time message: "Hello Bob, this is Alice!"
This is because this example outputs "Hello, this is Alice!" then the <t p='5'> inserts the specified text " Bob" at position 5, using Element <t/> – Insert Text.

Hello Bob, tihsd is Alice! this ]]>

Final result of real-time message: "Hello Bob, this is Alice!"
This example outputs "Hello Bob, tihsd is Alice!", then <e p='16' n='5'/> erases 5 characters at position 16 in the string of text (which erases the mistyped word "tihsd"). Finally, <t p='11'>this</t> inserts the text "this" place of the original misspelled word.

This is an example message containing multiple consecutive real-time message edits. This illustrates valid use of the <rtt/> element.

Helo lo...planet World there, ]]>

Resulting real-time message: "Hello there, World", completed in the following series of action elements:

*The Cursor Position column is only relevant if the Optional Remote Cursor is implemented.

This example does not illustrate Preserving Key Press Intervals. Also, it is noted that most situations, during normal typing speeds at a normal Transmission Interval, the above series of Action Elements will normally be spread over multiple separate <rtt/> elements.

All examples shown below, result in the same real-time message “HELLO”. Only the last example follows Preserving Key Press Intervals.

HELLO ]]>

The above example outputs “HELLO” in a single action element (Element <t/> – Insert Text).

H E L L O ]]>

The above example outputs “HELLO” in separate action elements for each key press.

H E L L O ]]>

The above example outputs “HELLO” in separate action elements for each key press, while also Preserving Key Press Intervals. The Element <w/> – Wait Interval specifies the number of milliseconds between key presses, to allow smooth presentation in recipient clients that support <w/> action elements.

This example is a transmission of “Hello there!” while Preserving Key Press Intervals. It illustrates a four-second typing sequence:

• The misspelled phrase “Hello tehre!” is typed;
• Optional transmission of cursor movements towards the typing mistake;
• Two backspaces to delete the typing mistake;
• Two correct key presses to correctly spell the word “there”.

The use Element <w/> – Wait Interval, between key presses, allows the receiving client execute a small pause between action elements. This allows recipient clients to play back the sender's typing fluidly.

H e l l o t e h r e ! h e Hello there! ]]>

This example also illustrates the following:

• Typing is done via Element <t/> – Insert Text.
• Backspaces are done via Element <e/> – Erase Text.
• There is a final transmission with a Body Element, when the message is finished.
• Intervals between key presses are done via Element <w/> – Wait Interval.
• Each <message/> is delivered at a regular Transmission Interval, typically 700 milliseconds.
• Cursor movements via empty <t/> elements. Sender transmission is not essential, but can be desirable for recipient clients supporting an Optional Remote Cursor.
• Recipient clients that do not support Preserving Key Press Intervals and/or Optional Remote Cursor, will still display this message normally.
• The total sum of all values in Element <w/> – Wait Interval in one <message/> equal the Transmission Interval during periods of continuous typing. This also results in some <w/> interval elements being split between consecutive messages. Although not critical, it can further improve the fluidity of Receiving Real-Time Text.
• See Monitoring Message Changes Instead Of Key Presses for the best method of implementation.