Themyscira Wireless Technical Specification TW-TS-005 Version 1.0.3 Hexadecimal file format for sequences of RTP payloads for GSM speech codecs 0. Foreword This Technical Specification (TS) has been produced under the authority of the Presiding Sisterhood (government) of the Women's Republic of Themyscira as part of Themyscira Wireless technical initiative. Author: Mother Mychaela N. Falconia, High Priestess of Telecommunications As an official publication of Themyscira government, this document is not subject to copyright. 1. Scope Osmocom and Themyscira software components for GSM speech services represent the frames of each supported codec type as RTP payloads, using payload formats defined in various standards. In development and test activities related to these speech codecs and software components, a need sometimes arises to store sequences of RTP-encoded codec frames in a file at rest, perhaps representing a capture of a session or a test sequence. The present TS defines an ASCII hexadecimal file format that can represent RTP payloads that correspond to several different codec types used in GSM networks. 2. References The following documents contain provisions which, through reference in this text, constitute provisions of the present document. [1] IETF RFC 3550, H. Schulzrinne, S. Casner, R. Frederick, V. Jacobson: "RTP: A Transport Protocol for Real-Time Applications". [2] IETF RFC 3551, H. Schulzrinne, S. Casner: "RTP Profile for Audio and Video Conferences with Minimal Control". [3] ETSI TS 101 318: "Telecommunications and Internet Protocol Harmonization Over Networks (TIPHON); Using GSM speech codecs within ITU-T Recommendation H.323". [4] TW-TS-001: "Enhanced RTP transport of FR and EFR codec frames in an IP-based GSM RAN". [5] TW-TS-002: "Enhanced RTP transport of HRv1 codec frames in an IP-based GSM RAN". [6] IETF RFC 5993, X. Duan, S. Wang, M. Westerlund, K. Hellwig, T. Johansson: "RTP Payload Format for Global System for Mobile Communications Half Rate (GSM-HR)". [7] 3GPP TS 48.103: "Base Station System - Media GateWay (BSS-MGW) interface; User Plane transport mechanism". 3. Supported codec types and RTP formats The hexadecimal file format of the present TS is intended to be suitable for representing the following combinations of GSM speech codecs and their associated RTP formats: * FR, HR and EFR codecs in RTP encodings of ETSI TS 101 318 sections 5.1, 5.2 and 5.3, respectively; * FR and EFR codecs in the extended RTP format of TW-TS-001; * HR codec in 3GPP-5993 format, i.e., the payload format of RFC 5993 as constrained by 3GPP TS 26.102 referenced from TS 48.103; * HR codec in super-5993 format of TW-TS-002. It may be possible to use the presently defined hexadecimal file format for other codecs and/or other RTP payload types - however, the list of combinations enumerated above represents the design intent of the present TS. 4. File format definition 4.1. Principal definition The file format of the present TS is a line-based ASCII text format. Each line consists solely of printable ASCII characters, followed by OS-specific newline encoding. The maximum allowed length of each line is 80 characters, not including the OS-specific newline encoding. 4.2. Line record structure Each non-blank, non-comment line in an ASCII text file formatted per the present TS constitutes one record and represents a single RTP payload of a supported codec type. The RTP payload shall be written as a long string of hexadecimal digits, with two hex digits for each octet and no white space between octets. 4.2.1. Case of hexadecimal digits Hexadecimal digits A through F may be either uppercase or lowercase. 4.3. Frame delineation In all supported codec-format combinations listed in section 3, each 20 ms speech frame, be it good or errored, is transferred as a discrete RTP payload. In the hexadecimal file format of the present TS, each such frame or payload shall be stored as a separate hex-encoded line, terminated with OS-specific newline representation. Therefore, any program reading these hexadecimal files will have the same ability to detect and handle frame boundaries as a network element that receives a new RTP packet every 20 ms. 4.3.1. Representation of frame gaps Enhanced RTP transport formats of TW-TS-001 and TW-TS-002 require that a properly encoded frame be transmitted in every 20 ms window, and provide special No_Data frames to be used when the sender has nothing else to transmit. However, the same provision does not exist in other RTP formats, and the most common industry practice is to send nothing at all, or perhaps a zero-length payload, during frame gaps. In the hexadecimal file format of the present TS, a frame gap corresponding to an "empty" 20 ms time window for which no payload bytes exists is the keyword "NULL" (without quotes) in the place of a hexadecimal record. For consistency with case-insenstive hexadecimal digits (see section 4.2.1), this keyword shall likewise be recognized in a case-insensitive manner. 4.4. White space and comments Blank lines, whitespace-only lines or comment-only lines are allowed anywhere, and shall be ignored by programs that read frame sequence files per the present TS. White space is defined as any sequence of one or more ASCII space and/or tab characters. Comments are introduced with '#' character; all text following this character till the end of the line is to be treated as a comment and ignored. Each valid record (hexadecimal string or NULL keyword) shall start at the beginning of its respective physical line in the text file (i.e., no preceding white space is allowed), but may be followed by trailing white space. A record may also be followed by a comment (introduced with '#' character) - however, such record-attached comments must be preceded (separated from the record body) by white space. '#' directly after a record, without intervening white space, is not allowed. 5. Postel principle Programs that read frame sequence files per the present TS may implement parsers that are more permissive than the rules stated in chapter 4, accepting more than what is allowed by the strict language of the present TS. However, all programs that generate output that aims to follow the present TS shall strictly obey all file format rules enumerated in chapter 4. Annex A (normative): Representation format for FR and EFR codecs The term "TW-TS-005 Annex A file format" shall be used for data files that store a sequence of GSM-FR or GSM-EFR codec frames using the hexadecimal file format of the present TS. The following RTP formats are allowed for this Annex: * The basic RTP format of ETSI TS 101 318, also duplicated in RFC 3551; * The extended RTP format of TW-TS-001, either TEH only or a payload frame preceded by TEH; * A frame gap represented by NULL keyword. A program that reads FR/EFR frame sequence files per this Annex can autodetect the specific format in use out of the above, as well as detect invalid input, by checking the length of each record (stored RTP payload) and the signature nibbles in the leading octets: * An RTP payload of 1 octet can only be TW-TS-001 TEH in this context, in which case the upper nibble can only equal 0xE; * An RTP payload of 31 octets can only be EFR in basic RTP format, in which case the upper nibble of the first octet can only equal 0xC; * An RTP payload of 32 octets can only be EFR in extended RTP format: - the upper nibble of the first octet equals 0xE; - the upper nibble of the second octet equals 0xC; * An RTP payload of 33 octets can only be FR in basic RTP format, in which case the upper nibble of the first octet can only equal 0xD; * An RTP payload of 34 octets can only be FR in extended RTP format: - the upper nibble of the first octet equals 0xE; - the upper nibble of the second octet equals 0xD; * Any other input that does not equal any of the possibilities enumerated above is invalid. A 1-octet RTP payload that consists of TW-TS-001 TEH with NDF=1 is equally valid for FR and EFR and thus cannot be used to distinguish between the two codecs; all other valid possibilities are specific to either FR only or EFR only. Annex B (normative): Representation format for HR codec The term "TW-TS-005 Annex B file format" shall be used for data files that store a sequence of GSM-HR codec frames using the hexadecimal file format of the present TS. The following RTP formats are allowed for this Annex: * The basic RTP format of ETSI TS 101 318 section 5.2; * The extended RTP format of RFC 5993 and TW-TS-002 - as detailed in [5], many (but not all) super-5993 RTP payloads are also valid RFC 5993 payloads; * A frame gap represented by NULL keyword. A program that reads GSM-HR frame sequence files per this Annex can autodetect the specific format in use out of the above, as well as detect invalid input, by checking the length of each record (stored RTP payload) and for some lengths, certain bit fields in the first octet: * An RTP payload of 1 octet can only be TW-TS-002 FT=1 or FT=7 in this context; the single octet should be checked to verify that it is valid TW-TS-002 format with one of these two frame types. * An RTP payload of 14 octets can only be TS 101 318 section 5.2 in this context. Because every possible pattern of 112 bits is a potentially valid GSM-HR codec frame, no further validation checks can be done on payloads of this length. * An RTP payload of 15 octets can only be RFC 5993 or TW-TS-002 in this context, with FT=0, FT=2 or FT=6. * Any other input that does not equal any of the possibilities enumerated above is invalid. Annex C (informative): Specification change history Version 1.0.2: initial publication for review and early implementation by Themyscira and Osmocom communities. Version 1.0.3: correct a typing error in Annex A.