diff doc/RTP-analysis @ 173:aaa0380f9958

doc/RTP-analysis: document new tools
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 27 Dec 2022 00:00:57 +0000
parents 8eb0e7a39409
children 9fb22fa4d373
line wrap: on
line diff
--- a/doc/RTP-analysis	Mon Dec 26 22:42:41 2022 +0000
+++ b/doc/RTP-analysis	Tue Dec 27 00:00:57 2022 +0000
@@ -1,20 +1,39 @@
-The present package includes a utility named rtp-gsmfr-extr; this utility
-extracts a single RTP stream in either FR1 or EFR codec format from a pcap file,
-presumably captured with tcpdump on an IP network serving either an IP-based BTS
-or a gateway from an E1-based BTS to RTP - the intent is to extract a GSM call
-uplink that has been rendered into an RTP stream by a BTS.  The RTP stream being
-extracted must be fully continuous without any gaps, using Themyscira
-RTP-BFI-extension BFI marker packets in those 20 ms windows where no good
-traffic frame has been received.  rtp-gsmfr-extr verifies continuity of the RTP
-stream being extracted: any detected discontinuity (either a sequence number
-jump indicating packet loss or a timestamp jump indicating an intentional gap
-generated at the source) will be reported, and the extraction will stop there.
+The present package includes a number of utilities for analyzing RTP streams
+that have been captured with tcpdump or equivalent tools in pcap format.  In
+order to use any of these utilities, you need to have a pcap file (obviously),
+and you need to identify the RTP stream to be analyzed or extracted by either
+source or destination IP:port.  All tools begin by applying a filter,
+considering only those packets that are UDP in IPv4 (no IPv6 support currently),
+and only those that match the specified source or destination IP:port.  Every
+matched packet is checked for a valid RTP header, and then the actual RTP stream
+analysis or extraction takes place, depending on the specific tool:
 
-To run rtp-gsmfr-extr, you need to have a pcap file (obviously), and you need to
-identify the RTP stream to be extracted by either source or destination IP:port.
-rtp-gsmfr-extr will look at every UDP packet that matches this src-IP-port or
-dest-IP-port filter, and then check for valid RTP, verify the expected increment
-in sequence and timestamp numbers, check for either FR1 or EFR payload (or a
-Themyscira BFI marker for FR & EFR), and finally write the extracted frame
-stream to a gsmx file.  This gsmx output can then be analyzed with gsmrec-dump,
-or decoded to playable WAV with gsmfr-decode or gsmefr-decode.
+rtp-cont-check	This program checks the selected RTP stream for continuity.  It
+		verifies that every matched packet has the same SSRC, that the
+		sequence number always increments by 1 from each individual
+		packet to the next, and that the RTP header timestamp always
+		increments by 160 units.  (The assumption is that the
+		application at hand is in the traditional telephony domain,
+		with a sampling rate of 8000 samples/s and 20 ms packetization
+		for RTP.)  This tool also looks at the capture time deltas
+		between successive packets and reports the observed minimum and
+		maximum; by seeing min and max delta-T, a developer can easily
+		notice timing aberrations that aren't caught by RTP header
+		sequence number and timestamp checks.
+
+rtp-gsmfr-extr	This program focuses on a single selected RTP stream like the
+		others, enforces its continuity just like rtp-cont-check, but
+		then further enforces that every RTP packet be one of these 3
+		possibilities: a GSM FR1 codec frame, a GSM EFR codec frame or
+		a Themyscira BFI marker as defined in the RTP-BFI-extension
+		document.  (The payload type number is NOT considered, only the
+		payload length and the characteristic signature of each of the
+		3 allowed possibilities.)  The selected RTP stream is then
+		extracted and written into a gsmx file (see Binary-file-format),
+		which can then be analyzed with gsmrec-dump or decoded to
+		playable WAV with gsmfr-decode or gsmefr-decode.
+
+rtp-jitter-view	This program analyzes a single selected RTP stream just like
+		rtp-cont-check, but instead of reporting minimum and maximum
+		time deltas for the entire stream, it prints the individual
+		capture time delta between every successive pair of packets.