rtmp-errata-addenda.xml

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc [
  <!ENTITY nbsp    "&#160;">
  <!ENTITY zwsp   "&#8203;">
  <!ENTITY nbhy   "&#8209;">
  <!ENTITY wj     "&#8288;">
]>
<?xml-stylesheet type='text/xsl' href='rfc7991.xslt' ?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>

<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="none" submissionType="independent" category="info" version="3">

<front>
	<title abbrev="RTMP Errata and Addenda">RTMP Errata and Addenda</title>

	<author initials="M." surname="Thornburgh" fullname="Michael C. Thornburgh">
		<address>
			<postal>
				<city>Santa Cruz</city>
				<region>CA</region>
				<code>95060-1950</code>
				<country>US</country>
			</postal>
			<email>zenomt@zenomt.com</email>
			<uri>https://zenomt.zenomt.com/card#me</uri>
		</address>
	</author>

	<abstract><t>

		The specification for Adobe's Real-Time Messaging Protocol
		(RTMP), last updated in December 2012, contains errors,
		omissions, and ambiguities that impede interoperation. This
		memo corrects, clarifies, and amends portions of the RTMP
		specification.

	</t></abstract>

	<note>
		<name>Copyright Notice</name>

		<t>Copyright © 2023 Michael Thornburgh. All rights reserved.</t>

		<t>Permission is hereby granted, free of charge, to any person
		obtaining a copy of this software and associated documentation
		files (the "Software"), to deal in the Software without
		restriction, including without limitation the rights to use,
		copy, modify, merge, publish, distribute, sublicense, and/or
		sell copies of the Software, and to permit persons to whom
		the Software is furnished to do so, subject to the following
		conditions:</t>

		<t>The above copyright notice and this permission notice shall
		be included in all copies or substantial portions of the
		Software.</t>

		<t>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
		KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
		WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
		AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
		HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
		WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
		FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
		OR OTHER DEALINGS IN THE SOFTWARE.</t>

	</note>

</front>

<middle>

<section title="Introduction">

<t>At the time of writing, Adobe's Real-Time Messaging Protocol (RTMP) continues
to be used by the media streaming industry and in media streaming products
for transmitting video and audio over IP networks, including between and
through various stages of live video production, ingest, and distribution.</t>

<t>The <xref target="RTMP">RTMP specification</xref> was last updated by Adobe
in December 2012. That version contains numerous errors, omissions, and
ambiguities that impede the independent development of correct and interoperable
streaming products.</t>

<t>At the time of writing, the RTMP specification is considered to be an
immutable historical artifact. This memo is intended to be referenced alongside
<xref target="RTMP"/> to correct, clarify, and amend portions of that historical
specification.</t>

<t>This memo addresses RTMP Version 3 as publicly described in
<xref target="RTMP"/>. It does not address private or undocumented extensions
for which interoperation is not desired by the extending parties.</t>

<t>For coordinated interoperable extensions and enhancements to RTMP, see
<xref target="E-RTMP">Enhanced RTMP</xref>.</t>

<section title="Terminology">

<t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
"<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>",
"<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>",
"<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>"
in this document are to be interpreted as described in BCP 14
<xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they
appear in all capitals, as shown here.</t>

</section> <!-- Terminology -->
</section> <!-- Introduction -->

<section title="Common Syntax Elements">

<t>Definitions of types and structures in this specification use traditional
text diagrams paired with procedural descriptions using a C-like syntax.  The
C-like procedural descriptions <bcp14>SHALL</bcp14> be construed as definitive.</t>

<t>Structures are packed to take only as many bytes as explicitly indicated.
There is no 32-bit alignment constraint, and fields are not padded for alignment
unless explicitly indicated or described.  Text diagrams may include a bit
ruler across the top; this is a convenience for counting bits in individual
fields and does not necessarily imply field alignment on a multiple of the
ruler width.</t>

<t>Unless specified otherwise, reserved fields <bcp14>SHOULD</bcp14> be set
to 0 by a sender and <bcp14>MUST</bcp14> be ignored by a receiver.</t>

<t>The procedural syntax of this specification defines correct and error-free
encoded inputs to a parser.  The procedural syntax does not describe a fully
featured parser, including error detection and handling.  Implementations
<bcp14>MUST</bcp14> include means to identify error circumstances, including
truncations causing elementary or composed types not to fit inside containing
structures, fields, or elements.  Unless specified otherwise, an error
circumstance <bcp14>SHALL</bcp14> abort the parsing and processing of an
element and its enclosing elements.</t>

<t>This memo uses the elementary types and constructs described in
<xref target="RFC7016" section="2.1.1" sectionFormat="of"/>.
The definitions of that section are incorporated by reference as though fully
set forth here.</t>

<section title="Additional Elementary Types">

<t>This section lists additional elementary types used in the following
sections.</t>

<dl newline="true">
	<dt><tt>uint24_t var;</tt></dt>
	<dd>An unsigned integer 24 bits (3 bytes) in length, in network
	byte order and byte aligned.</dd>

	<dt><tt>uint16le_t var;</tt></dt>
	<dd>An unsigned integer 16 bits (2 bytes) in length, in little-endian
	byte order and byte aligned.</dd>

	<dt><tt>uint32le_t var;</tt></dt>
	<dd>An unsigned integer 32 bits (4 bytes) in length, in little-endian
	byte order and byte aligned.</dd>

</dl>

</section> <!-- Additional Elementary Types -->
</section> <!-- Common Syntax Elements -->

<section title="Chunk Stream Handshake">

<t><xref target="RTMP" section="5.2" relative="#52handshake" sectionFormat="of"/>
describes the initial handshake of an RTMP Chunk Stream connection. In that
section and its subsections, the <tt>C1</tt> and <tt>S1</tt> packets are
described as containing fields of 1528 random bytes, and the <tt>C2</tt> and
<tt>S2</tt> packets as containing identical echoes of the same 1528 random
bytes from <tt>S1</tt> and <tt>C1</tt> respectively.</t>

<t>Some proprietary extensions to RTMP use these data fields for further
handshaking purposes (such as cryptographic key exchange or feature enablement),
and in these cases the <tt>C2</tt> and <tt>S2</tt> packets might not contain
identical echoes of the random bytes from the respective <tt>S1</tt> and
<tt>C1</tt> packets.</t>

<t>Clients or servers that are not implementing or enforcing proprietary
extensions to the handshake <bcp14>SHOULD NOT</bcp14> fail the connection or
limit functionality on account of a non-identical echo of the corresponding
random bytes received in an <tt>S2</tt> or <tt>C2</tt> packet.</t>

</section> <!-- Chunk Stream Handshake -->

<section title="Byte Order">

<t><xref target="RTMP" section="4" relative="#4-byte-order-alignment-and-time-format" sectionFormat="of"/>
states that "all integer fields are carried in network byte order". However,
there are two exceptions in the specification where multi-byte integers are
coded in little-endian byte order. To draw attention to these exceptions and
to eliminate the dissonance between the exceptions and the statement, the
first two sentences of that section are amended to read</t>

<blockquote>
Unless otherwise specified, multi-byte integer fields are carried in network
byte order, byte zero is the first byte shown, and bit zero is the most
significant bit in a word or field. This byte order is commonly known as
"big-endian".

</blockquote>

<section title="Chunk Basic Header">

<t><xref target="RTMP" section="5.3.1.1" relative="#5311-chunk-basic-header" sectionFormat="of"/>
describes the one, two, and three byte encodings of the Chunk Basic Header.
The descriptive text gives a formula to decode the three-byte encoding as
though the "<tt>cs id - 64</tt>" field is little-endian; however, this is not
explicitly stated and is easy to miss given the diagrams and the description
of the field as just "8 or 16 bits". This section clarifies the Chunk Basic
Header encodings.</t>

<artwork align="left" type="ascii-art"><![CDATA[
 0 1 2 3 4 5 6 7|
+-+-+-+-+-+-+-+-+
|fmt|  2 .. 63  |
+-+-+-+-+-+-+-+-+

 0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|fmt|     0     |   cs id - 64  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

 0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|fmt|     1     |       cs id - 64 (LE)         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

struct chunkBasicHeader_t
{
    uintn_t fmt                      :2; // format
    uintn_t provisionalChunkStreamID :6;
    if (provisionalChunkStreamID >= 2)
        chunkStreamID = provisionalChunkStreamID; // one-byte form
    else
    {
        if (0 == provisionalChunkStreamID)
            uint8_t chunkStreamIDMinus64; // two-byte form
        else // 1 == provisionalChunkStreamID
            uint16le_t chunkStreamIDMinus64; // three-byte form
        chunkStreamID = chunkStreamIDMinus64 + 64;
    }
} :variable*8;
]]></artwork>

<t>The <tt>chunkStreamIDMinus64</tt> field of the 3-byte form encodes the
chunk stream ID less 64 in little-endian byte order.</t>

</section> <!-- Chunk Basic Header -->

<section title="Chunk Message Header">

<t><xref target="RTMP" section="5.3.1.2" relative="#5312-chunk-message-header" sectionFormat="of"/>
describes the four Chunk Message Header formats. The format being used is
indicated by the <tt>fmt</tt> field of the Chunk Basic Header.</t>

<t>The <tt>Type 0</tt> Chunk Message Header format includes the RTMP Message
Stream ID. The description of the <tt>Message Stream ID (4 bytes)</tt> field
in
<xref target="RTMP" section="5.3.1.2.5" relative="#53125-common-header-fields" sectionFormat="of"/>
specifies that the field "is stored in little-endian format". However, the
diagram doesn't show this and it is easily missed. This section clarifies the
<tt>Type 0</tt> Chunk Message Header format.</t>

<artwork align="left" type="ascii-art"><![CDATA[
 0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               provisional timestamp           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                  message length               |message type id|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                     message stream id (LE)                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+
|    if(0xFFFFFF == provisionalTimestamp)  extendedTimestamp    |
+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+~+

struct chunkMessageHeaderType0_t
{
    uint24_t   provisionalTimestamp;
    uint24_t   messageLength;
    uint8_t    messageTypeID;
    uint32le_t messageStreamID;

    if (0xFFFFFF == provisionalTimestamp)
    {
        uint32_t extendedTimestamp;
        timestamp = extendedTimestamp;
    }
    else
        timestamp = provisionalTimestamp;
} :variable*8;
]]></artwork>

<t>The <tt>messageStreamID</tt> field encodes the message stream ID
as four bytes in little-endian byte order. Note however that
per <xref target="rtmp-message-format"/>
the message stream ID <bcp14>SHOULD NOT</bcp14> exceed 16777215.</t>

</section> <!-- Chunk Message Header -->
</section> <!-- Byte Order -->

<section title="Timestamps">

<section title="Chunk Message Header Extended Timestamp">

<t><xref target="RTMP" section="5.3.1.2" relative="#5312-chunk-message-header" sectionFormat="of"/>
implies that the <tt>Extended Timestamp</tt> field is separate from the Chunk
Message Header. This implication is misleading because, when it is present,
it is in fact part of the chunk header and does not count toward the chunk's
payload or the <tt>Message Length</tt>. Because of this, all four types of
Chunk Message Header should be recognized as being variable-length.</t>

<t>While 
<xref target="RTMP" section="5.3.1.3" relative="#5313-extended-timestamp" sectionFormat="of"/>
states that the <tt>Extended Timestamp</tt> is present in <tt>Type 3</tt>
chunks when the most recent <tt>Type 0</tt>, <tt>Type 1</tt>, or <tt>Type
2</tt> chunk on the same Chunk Stream ID indicated the presence of an extended
timestamp, this has caused confusion for some implementors for the <tt>Type
3</tt> chunks that are the subsequent portions of the same message, or that
are the first chunk of subsequent messages on the same Chunk Stream ID. To
clarify: while the <tt>Extended Timestamp</tt> field is indicated, it
<bcp14>MUST</bcp14> be present in <em>every</em> <tt>Type 3</tt> Chunk Message
Header for a message, including the first as well as subsequent chunks of
that message <em>and subsequent messages starting with <tt>Type 3</tt></em>,
even though this is wasteful.</t>

</section> <!-- Chunk Message Header Extended Timestamp -->

<section title="Timestamp Order of Messages">

<t><xref target="RTMP" section="5" relative="#5-rtmp-chunk-stream" sectionFormat="of"/>
states</t>

<blockquote>
When used with a reliable transport protocol such as TCP <xref target="RFC0793"/>,
RTMP Chunk Stream provides guaranteed timestamp-ordered end-to-end delivery
of all messages, across multiple streams.
</blockquote>

<t>However, this wording is misleading. For example,
<xref target="RTMP" section="5.3.1.2.1" relative="#53121type-0" sectionFormat="of"/>
alludes to a case where "the stream timestamp goes backward (e.g. because of
a backward seek)". Note that RTMP can be used for Video on Demand (VOD) and
Digital Video Recorder (DVR) playback as well as for live streaming.</t>

<t>Senders <bcp14>MAY</bcp14> apply real-time treatments to RTMP messages,
including prioritization policies and transmission deadlines. Prioritization
can include (but is not limited to) preferential allocation of transmission
resources to audio over video, or to one stream over another.  Prioritization
can cause, for example, later audio messages to be transmitted before earlier
video messages.</t>

<t>Senders have full control over scheduling, interleaving, and transmitting
RTMP messages, or portions thereof, over lower-layer transports. When using
RTMP Chunk Stream over a reliable, in-order transport protocol such as TCP
<xref target="RFC0793"/>, a sender can ensure delivery of messages in any
desired order, including in timestamp order.</t>

<t>For optimum interoperability with straightforward implementations and with
many existing implementations, timestamps <bcp14>SHOULD NOT</bcp14> go backwards
in the same Message Stream ID for the same RTMP Message Type ID without an
explicit signal from the receiver (such as initiating a backward seek)
indicating such a jump is expected.</t>

</section> <!-- Timestamp Ordering of Messages -->

</section> <!-- Timestamps -->

<section title="Abandoning a Message">

<t><xref target="RTMP" section="5.4.2" relative="#542abort-message-2" sectionFormat="of"/>
describes the <tt>Abort Message</tt> Protocol Control Message. The description
of this message states</t>

<blockquote>
An application may send this message when closing in order to indicate that
further processing of the messages is not required.
</blockquote>

<t>This description is misleading, and suggests that receipt of this message
signals that no further processing of any messages is required, which is
incorrect.</t>

<t>This protocol control message aborts a single partially-transmitted message
on the indicated Chunk Stream ID. Afterward, new messages can commence on the
same Chunk Stream ID.</t>

<t>Senders can apply real-time treatments to messages, including transmission
deadlines. A message's transmission deadline might be exceeded after transmission
has started but before transmission is complete. Therefore, receivers
<bcp14>MUST</bcp14> be operable to process the <tt>Abort Message</tt> Protocol
Control Message by discarding the partially-received message and being prepared
to receive a new message on the indicated Chunk Stream ID.</t>

<t>If at least one chunk for a new message is transmitted, then a timestamp
is established for that message against which a timestamp delta in a subsequent
message can be applied, even if the first message is aborted.</t>

</section> <!-- Abandoning a Message -->

<section title="RTMP Message Format" anchor="rtmp-message-format">

<t><xref target="RTMP" section="6.1" relative="#61-rtmp-message-format" sectionFormat="of"/>
defines the RTMP Message Format, with an explicit encoding of the RTMP message
header including field widths and byte ordering. However, this definition is
misleading because RTMP messages are not serialized according to this format
over either of the common transports. For example, when RTMP messages are
transported by the RTMP Chunk Stream, RTMP message headers are encoded into
Chunk Message Headers; and when RTMP messages are transported in RTMFP according
to <xref target="RFC7425" section="5.1" sectionFormat="of"/>, RTMP message
headers are encoded into flow metadata and the leading bytes of flow user
messages.  Therefore, the Message Header of the RTMP Message Format
<bcp14>SHOULD</bcp14> be construed as a <em>virtual</em> header that is mapped
to the facilities of a lower-layer transport protocol such as RTMP Chunk
Stream or RTMFP.</t>

<t>The semantics of the RTMP Message Virtual Header and the encodings used in
the common transport protocols constrain the possible values of RTMP Message
Header fields. In particular:</t>

<ul>
	<li>Message Type is constrained to values from 0 to 255 inclusive;</li>

	<li>Message payloads can be at most 16777215 bytes long;</li>

	<li>Timestamps range from 0 to 4294967295 and wrap around;</li>

	<li>Stream ID is constrained to values from 0 to 16777215 inclusive.</li>

</ul>

<t>Note that in some cases these constraints are more restrictive than the
facilities provided by lower-layer transports. For example, RTMP Chunk Stream
could encode a Stream ID up to 4294967295; RTMFP could encode a Stream ID of
any finite non-negative integer (though typical implementations are limited
to 2<sup>64</sup> - 1) and transport messages of unlimited length. However,
exceeding the limits enumerated above will impede interoperability and protocol
translation, so they <bcp14>SHOULD NOT</bcp14> be exceeded.</t>

<section title="Alternative Transports and Processing Possible">

<t>RTMP Chunk Stream is not the only possible transport service for RTMP
Messages. This flexibility is stated in several places. For example:</t>

<blockquote>
The [sic] section specifies the format of RTMP messages that are transferred between
entities on a network using a lower level transport layer, such as RTMP Chunk
Stream. While RTMP was designed to work with the RTMP Chunk Stream, it can
send the messages using any other transport protocol.
(<xref target="RTMP" section="6" relative="#6-rtmp-message-formats" sectionFormat="of"/>)
</blockquote>

<blockquote>
Real-time streaming network communication for the Flash platform of video,
audio, and data typically uses Adobe's Real-Time Messaging Protocol (RTMP)
messages.  RTMP messages were originally designed to be transported over RTMP
Chunk Stream in TCP; however, other transports (such as the one described in
this memo) are possible. (<xref target="RFC7425" section="1"/>)
</blockquote>

<blockquote>
The Flash platform uses RTMP messages for media streaming and communication.
This section describes how to transport RTMP messages over RTMFP flows and
additional messages and semantics unique to this transport.
(<xref target="RFC7425" section="5"/>)
</blockquote>

<t>This flexibility is memorialized here.</t>

<t>Note well that during ordinary processing, RTMP Messages can be translated
between different protocols and can pass through heterogeneous processing
elements, which can mask, confound, or destroy message meta-information beyond
the Message Virtual Header (such as the Chunk Stream ID or RTMFP flow on which
a message originally arrived).  Different processing elements can apply
different treatments, policies, priorities, and deadlines to RTMP message
streams, potentially affecting message arrival, arrival order, and interarrival
timing.</t>

</section> <!-- Alternative Transports Possible -->

<section title="Object Encoding 3" anchor="object-encoding-3">

<t>When <tt>objectEncoding</tt> 3 is negotiated during <tt>connect</tt>
(<xref target="object-encoding-negotiation"/>), <tt>Type 17</tt> Command
Extended and <tt>Type 15</tt> Data Extended messages can be used to carry
<xref target="AMF3">AMF 3</xref> coded values.</t>

<t><xref target="RTMP" section="7.1.1" relative="#711command-message-20-17" sectionFormat="of"/>
implies that a <tt>Type 17</tt> Command Extended message is a sequence of
AMF 3 coded values. Likewise,
<xref target="RTMP" section="7.1.2" relative="#712data-message-18-15" sectionFormat="of"/>
implies that a <tt>Type 15</tt> Data Extended message is a sequence of AMF 3
coded values. These implications are incorrect.</t>

<artwork align="left" type="ascii-art"><![CDATA[
 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|format selector|
+-+-+-+-+-+-+-+-+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
|                          coded value                          |
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
                                :
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
|                          coded value                          |
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

// Message Type 17 "Command Extended" and Type 15 "Data Extended"
struct extendedActionMessagePayload_t
{
    uint8_t formatSelector;

    if (0 == formatSelector)
    {
        while (remainder() > 0)
        {
            provisionalValue = decode_amf0();
            if (avmplus_object_marker == provisionalValue)
                // saw marker byte 0x11
                codedValue = decode_amf3();
            else
                codedValue = provisionalValue;
        }
    }
    // else unknown format
} :rtmpMessagePayloadLength*8;
]]></artwork>

<t>A <tt>Type 17</tt> Command Extended or <tt>Type 15</tt> Data Extended
message payload begins with a format selector byte, followed by a sequence
of values in a format-specific encoding.  Currently only format 0 is defined;
therefore, the format selector byte <bcp14>MUST</bcp14> be 0.  Format 0 is a
sequence of AMF values, each encoded in AMF 0 by default; AMF 3 encoding for
a value is selected by prefixing it with an <tt>avmplus-object-marker</tt>
(byte <tt>0x11</tt>) as defined in <xref target="AMF0"/>.</t>

<t><tt>Type 20</tt> Command messages and <tt>Type 18</tt> Data messages
comprise a sequence of AMF 0 coded values, as originally implied.</t>

</section> <!-- Object Encoding 3 -->

</section> <!-- RTMP Message Format -->

<section title="Remote Procedure Call">

<section title="connect" anchor="connect-message">

<t><xref target="RTMP" section="7.2.1.1" relative="#7211connect" sectionFormat="of"/>
lists parameters for the <tt>connect</tt> command and their potential values
or ranges. However, that section contains incomplete and misleading information
particularly in capability negotiation.</t>

<section title="objectEncoding Negotiation" anchor="object-encoding-negotiation">

<t>The <tt>objectEncoding</tt> property of the <tt>connect</tt> command's Command Object
is <bcp14>OPTIONAL</bcp14> with a default value of 0. If given, the possible
values are 0 and 3 (Numbers). This value indicates the Object Encoding methods
supported by the client. A value of 0 indicates support only for AMF 0 and
the <tt>Type 20</tt> Command and <tt>Type 18</tt> Data message types.  A
value of 3 indicates support for both AMF 0 and AMF 3, and for <tt>Type 17</tt>
Command Extended and <tt>Type 15</tt> Data Extended messages in addition to
<tt>Type 20</tt> and <tt>Type 18</tt> messages. See
<xref target="object-encoding-3"/> for the corrected encoding of these
message types.</t>

<t>The server responds with the highest legal value that both it and the
client support (that is, the server <bcp14>MUST NOT</bcp14> send <tt>3</tt>
if the client didn't send <tt>3</tt>). Some clients require this property in
the <tt>_result</tt>, so the server <bcp14>SHOULD</bcp14> send it. If Object
Encoding 0 is negotiated, client and server <bcp14>MUST NOT</bcp14> send
Command Extended or Data Extended messages to each other. If Object Encoding
3 is negotiated, client and server can use either the normal (<tt>Type 20</tt>
and <tt>Type 18</tt>) or extended (<tt>Type 17</tt> and <tt>Type 15</tt>)
message types at any time.</t>

<t>Interoperability Note: The <tt>connect</tt> command <bcp14>SHOULD</bcp14>
be sent in a <tt>Type 20</tt> Command message unless the client has prior
knowledge that the server to which it is connecting supports Object Encoding
3.</t>

</section> <!-- objectEncoding Negotiation -->

<section title="tcUrl">

<t>The <tt>tcUrl</tt> property of the <tt>connect</tt> command's Command Object
is <bcp14>REQUIRED</bcp14>. Its value is a string representing the URI
to which the client is connecting. Contrary to
<xref target="RTMP" section="7.2.1.1" relative="#7211connect" sectionFormat="of"/>,
RTMP family URIs follow the
<xref target="RFC3986">generic syntax for URIs</xref>. The path and optional
query components identify the abstract <em>target resource</em> within the server's
namespace. See <xref target="RTMP-URIS"/> for more information about the
syntax constraints and access semantics of RTMP family URIs.</t>

<t>The meaning of "target resource" is implementation-specific and is the
prerogative of the server.</t>

<t>Interoperability Note: Some client implementations incorrectly presume
the server's interpretation of the <tt>path</tt> component of the URI,
specifically by presuming the number of path segments that identify the target
resource and setting <tt>tcUrl</tt> accordingly.  These clients then incorrectly
interpret the remaining path segments of the original URI as identifying a secondary
resource (such as the name of a stream to play or publish via the connection to
the target resource).  This behavior is not in keeping with the spirit of
URIs (particularly that the <tt>authority</tt> governs its namespace),
is not interoperable, and is <bcp14>NOT RECOMMENDED</bcp14>.  Such secondary
resources, when encoded in a URI, should instead be identified by the fragment
component as described in <xref target="RTMP-URIS"/>. The full path and
optional query components from the original URI <bcp14>SHOULD</bcp14> be
preserved in <tt>tcUrl</tt>.</t>

<t>Per <xref target="security-considerations">Security Considerations</xref>, the
client <bcp14>SHOULD</bcp14> strip any <tt>userinfo</tt> and <tt>fragment</tt>
components from the URI before sending it in <tt>tcUrl</tt>.</t>

</section> <!-- tcUrl -->

<section title="app">

<t>The <tt>app</tt> property of the <tt>connect</tt> command's Command Object
is <bcp14>REQUIRED</bcp14>. Its value is a string indicating the abstract
<em>target application resource</em> to which the client is connecting. Unless
the client has prior knowledge to the contrary of the server's specific
implementation, <tt>app</tt> <bcp14>SHOULD</bcp14> be set to the <tt>path</tt>
and optional <tt>query</tt> components of the URI to which the client is
connecting, not including the leading slash of the path (if any).</t>

<t>The meaning of "target application resource" is implementation-specific
and is the prerogative of the server.</t>

</section> <!-- app -->

<section title="Codec Negotiation">

<t>The <tt>videoCodecs</tt> and <tt>audioCodecs</tt> properties of the
<tt>connect</tt> command's Command Object are bit fields representing the video and
audio codecs, respectively, that the client is able and willing to receive.
These properties are <bcp14>OPTIONAL</bcp14> and each defaults to 0 (that is,
no bits set, so no codecs indicated). The values for these fields are
enumerated in
<xref target="RTMP" section="7.2.1.1" relative="#7211connect" sectionFormat="of"/>;
multiple codecs are combined with bitwise-or.</t>

<t>Interoperability Note: Some server implementations, including Adobe Media
Server, use this information to selectively filter out <tt>Video</tt> and
<tt>Audio</tt> messages having codecs not indicated in the respective bit
fields. In other words, some servers might not send the video and/or audio
messages of certain streams unless these properties are sent with appropriate
values. Therefore, clients <bcp14>SHOULD</bcp14> send <tt>videoCodecs</tt>
and <tt>audioCodecs</tt> in the <tt>connect</tt> command indicating at least
their supported playback codecs.</t>

<t>Codec and capability negotiation are extended in <xref target="E-RTMP"/>.</t>

</section> <!-- Codec Negotiation -->

<section title="Optional User Arguments">

<t><xref target="RTMP" section="7.2.1.1" relative="#7211connect" sectionFormat="of"/>
shows that optional user arguments to the <tt>connect</tt> command are allowed.
However, that section shows and implies that “any optional information” would
be in a single optional AMF Object following the Command Object. This is
misleading. The <tt>connect</tt> command can accept, expect, or require zero
or more additional arguments of any AMF types following the Command Object.
The number and types of the additional arguments, their interpretation, and
whether they are expected or required is implementation-specific and is the
prerogative of the server. Often a server will expect one or more string
arguments to the <tt>connect</tt> command following the Command Object; for
example a developer key, a user name and password, or implementation-specific
connection properties.</t>

</section> <!-- Optional User Arguments -->

<section title="Authentication">

<t>RTMP doesn’t define an explicit connection authentication mechanism,
handshake, or protocol. However, RTMP does provide multiple generic facilities
that an application could use to authenticate and authorize a connection. Some
common examples:</t>

<ul>
	<li>A user name and password, a developer key, or an authorization
	token could be given as additional user arguments to the <tt>connect</tt>
	command;</li>

	<li>Authentication parameters could be encoded into the query component
	of the RTMP URI (thereby appearing in the <tt>tcUrl</tt> and <tt>app</tt>
	properties of the <tt>connect</tt> command’s Command Object);</li>

	<li>The name used for publishing or playing a stream, if known only
	to authorized users, could itself authenticate and authorize the
	publish or play;</li>

	<li>Call of a custom server-side command could be required immediately
	after the <tt>connect</tt> command, potentially incorporating authentication
	credentials and a challenge or other information from the <tt>connect</tt>
	command's <tt>_result</tt>.</li>

</ul>

<t>This list of examples is not exhaustive; other authentication schemes are
possible both within the facilities of RTMP and external (such as the server
requiring an authorized <xref target="RFC8446">TLS</xref> client certificate
for an <tt>rtmps:</tt> connection).</t>

<t>A concrete multi-phase challenge/response authentication protocol, using
URI query parameters and challenges returned from <tt>connect</tt> <tt>_error</tt>
responses, is described in the
<em>Authentication between RTMP Publisher and Primetime Live Packager</em>
section of <xref target="PRIMETIME"/>.</t>

</section> <!-- Authentication -->

</section> <!-- connect -->

<section title="call">

<t><xref target="RTMP" section="7.2.1" relative="#721netconnection-commands" sectionFormat="of"/>,
in context, implies that "<tt>call</tt>" is the name of a standard remote
command to be invoked on the server (similar to <tt>connect</tt> and
<tt>createStream</tt>). This implication is incorrect. Instead, "<tt>call</tt>"
is an <strong>implementation-specific client-side method</strong> of a
<tt>NetConnection</tt> ActionScript object (specific to the APIs of Flash
Player and Adobe Integrated Runtime), the effect of which in those clients
is to send an arbitrary command to the server as a normally-encoded Command
Message
(<xref target="RTMP" section="7.2" relative="#72-command-messages" sectionFormat="of"/>).
</t>

<t>This incorrect implication has caused confusion for some implementers.</t>

<t>Note that
<xref target="RTMP" section="7.2.1.2" relative="#7212call" sectionFormat="of"/>
correctly describes the encoding of a generic remote procedure call into a
Command Message. However, the "Optional Arguments" portion following the
Command Object in that section’s illustration implies that the optional
arguments are composed into a single AMF Object; instead, additional arguments
can be a concatenation of any kinds of AMF coded values, as clarified and
described in <xref target="object-encoding-3"/>.</t>

</section> <!-- call -->

<section title="deleteStream">

<t><xref target="RTMP" section="7.2.2.3" relative="#7223deletestream" sectionFormat="of"/>
erroneously states that the <tt>deleteStream</tt> command is a <em>"NetStream"</em>
command. The <tt>deleteStream</tt> command is actually a <em>"NetConnection"</em>
command (like <tt>connect</tt> and <tt>createStream</tt>) and is to be sent
on Message Stream ID 0 (the "control stream"). The Message Stream ID being
deleted is sent as the fourth field of the command message, as indicated.</t>

</section> <!-- deleteStream -->

</section> <!-- Remote Procedure Call -->

<section title="IANA Considerations">
<t>This memo has no IANA actions.</t>
</section> <!-- IANA -->

<section title="Security Considerations" anchor="security-considerations">

<t>RTMP and RTMFP URIs use the <xref target="RFC3986">generic syntax for
URIs</xref>.  URIs can encode sensitive or private information such as user
names, passwords, stream names, and so on. Implementations <bcp14>SHOULD</bcp14>
remove any <tt>userinfo</tt> and <tt>fragment</tt> components of a URI before
sending it as the <tt>tcUrl</tt> property of the <tt>connect</tt> command's
Command Object or in the Ancillary Data option of an RTMFP Endpoint Discriminator
(<xref target="RFC7425" section="4.4.2.2" sectionFormat="of"/>).</t>

</section> <!-- Security Considerations -->

</middle>

<back>
	<references>
	<name>References</name>

	<references title="Normative References">

		<reference anchor="AMF0" target="https://rtmp.veriskope.com/pdf/amf0-file-format-specification.pdf">
			<front>
				<title>Action Message Format -- AMF 0</title>
				<author><organization>Adobe Inc.</organization></author>
				<date month="December" year="2007"/>
			</front>
		</reference>

		<reference anchor="AMF3" target="https://rtmp.veriskope.com/pdf/amf3-file-format-spec.pdf">
			<front>
				<title>Action Message Format -- AMF 3</title>
				<author><organization>Adobe Inc.</organization></author>
				<date month="January" year="2013"/>
			</front>
		</reference>

		<xi:include href="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"/> <!-- BCP14 -->
		<xi:include href="http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml"/> <!-- URI syntax -->
		<xi:include href="http://xml.resource.org/public/rfc/bibxml/reference.RFC.7016.xml"/> <!-- RTMFP -->
		<xi:include href="http://xml.resource.org/public/rfc/bibxml/reference.RFC.7425.xml"/> <!-- RTMP in RTMFP -->
		<xi:include href="http://xml.resource.org/public/rfc/bibxml/reference.RFC.8174.xml"/> <!-- BCP14 -->

		<reference anchor="RTMP" target="https://rtmp.veriskope.com/docs/spec/">
			<front>
				<title>Adobe’s Real Time Messaging Protocol</title>
				<author initials="H." surname="Parmar" role="editor"/>
				<author initials="M." surname="Thornburgh" role="editor"/>
				<date month="December" year="2012"/>
			</front>
		</reference>

		<reference anchor="RTMP-URIS" target="https://zenomt.github.io/rtmp-errata-addenda/rtmp-uris/">
			<front>
				<title>RTMP Family URI Schemes</title>
				<author initials="M." surname="Thornburgh"/>
				<date month="July" year="2024"/>
			</front>
		</reference>

	</references>

	<references title="Informative References">

		<reference anchor="E-RTMP" target="https://veovera.org/">
			<front>
				<title>Enhanced RTMP</title>
				<author initials="S." surname="Lozben"/>
				<date month="May" year="2024"/>
			</front>
		</reference>

		<reference anchor="PRIMETIME" target="https://helpx.adobe.com/primetime/packagers/live_packager_getting_started.pdf">
			<front>
				<title>Adobe Primetime Live Packager Getting Started</title>
				<author><organization>Adobe Inc.</organization></author>
				<date month="July" year="2014"/>
			</front>
		</reference>

		<xi:include href="http://xml.resource.org/public/rfc/bibxml/reference.RFC.0793.xml"/> <!-- TCP -->
		<xi:include href="http://xml.resource.org/public/rfc/bibxml/reference.RFC.8446.xml"/> <!-- TLS -->

	</references>

	</references>

	<section numbered="false" title="Acknowledgements">
		<t>Thanks to Slavik Lozben for his detailed review of this memo.</t>
	</section> <!-- Acknowledgements -->
</back>

</rfc>