dlyerr_2_errpat - from 3GPP S4-121077

CMakeLists.txt

@@ -20,6 +20,7 @@ add_custom_target(test-verbose COMMAND ${CMAKE_CTEST_COMMAND} --verbose)
 add_subdirectory(src/basop/test_framework)
 add_subdirectory(src/basop/flc)
 add_subdirectory(src/bs1770demo)
+add_subdirectory(src/dlyerr_2_errpat)
 add_subdirectory(src/eid)
 add_subdirectory(src/esdru)
 add_subdirectory(src/fir)

doc/manual/eid.tex

@@ -1341,3 +1341,110 @@ \subsubsection{EID-EV G.192 Output frame examples }
 	\label{fig:G192outputFrameLayer034ErrorIndividual}
   \end{center}
 \end{figure}
+
+%--------------------------------------
+\section {Delay/error profile to erasure pattern (dlyerr\_2\_errpat)} \label{DLYERR}
+%--------------------------------------
+
+\subsection{Description}
+
+The {\tt dlyerr\_2\_errpat} tool converts a delay-and-error profile into a
+frame-erasure error pattern suitable for use with {\tt eid-xor}. This enables
+simulation of jitter buffer management (JBM) behavior: packets that arrive
+too late for playout are treated as lost, in addition to packets lost in
+the network.
+
+The input profile contains one integer per line representing either:
+\begin{itemize}
+\item A network delay in milliseconds (0--1999), or
+\item The value $-1$, indicating the packet was lost in the network.
+\end{itemize}
+
+Two JBM emulation modes are supported:
+\begin{itemize}
+\item {\bf Constant-delay mode} ({\tt -d}): a fixed JBM delay in milliseconds.
+      Any packet with delay exceeding this threshold is marked as lost.
+\item {\bf Bounded-loss-rate mode} ({\tt -l}): the tool automatically selects
+      the minimum JBM delay such that the combined late-loss rate stays
+      below the specified percentage.
+\end{itemize}
+
+\subsection{Algorithm}
+
+Processing is performed in two passes over the input profile:
+
+\begin{enumerate}
+\item {\bf Histogram pass}: reads the profile and builds a delay histogram
+      (counts per millisecond bin). In bounded-loss-rate mode, this histogram
+      is used to determine the JBM delay threshold by accumulating from the
+      highest delay downward until the target late-loss rate is exceeded.
+
+\item {\bf Output pass}: re-reads the profile and classifies each packet:
+      \begin{itemize}
+      \item delay $= -1$ (network loss) $\rightarrow$ frame erased
+      \item delay $>$ JBM threshold $\rightarrow$ frame erased (late loss)
+      \item otherwise $\rightarrow$ frame received (good)
+      \end{itemize}
+\end{enumerate}
+
+If the profile is shorter than the requested output length ({\tt -L}), the
+file is rewound and reused from the beginning.
+
+When {\tt -f~2} is specified, each packet decision produces two consecutive
+frame-erasure flags in the output (for codecs sending two frames per packet).
+
+\subsection{Usage}
+
+{\tt\small
+\begin{verbatim}
+dlyerr_2_errpat [options]
+
+  -i <inputfile>       delay/error profile (required)
+  -o <outputfile>      error pattern output (required)
+  -d <delay_ms>        constant-JBM-delay mode
+  -l <rate_percent>    bounded-loss-rate mode
+  -L <frames>          output length (default: 7500)
+  -s <offset>          skip initial frames in profile
+  -f <1|2>             frames per packet (default: 1)
+  -w                   word-oriented G.192 output
+  -b                   byte-oriented G.192 output
+  -c                   text with LF (one entry per line)
+\end{verbatim}
+}
+
+Exactly one of {\tt -d} or {\tt -l} must be supplied.
+
+\subsection{Output formats}
+
+\begin{itemize}
+\item {\bf Default text}: concatenated ASCII {\tt 0} (good) / {\tt 1} (erased)
+\item {\bf Text with LF} ({\tt -c}): one digit per line
+\item {\bf Byte G.192} ({\tt -b}): binary bytes 0x21 (good) / 0x20 (erased)
+\item {\bf Word G.192} ({\tt -w}): binary 16-bit words 0x6B21 / 0x6B20
+\end{itemize}
+
+\subsection{Example}
+
+Apply MTSI delay/error profile with a fixed 200\,ms JBM delay, word-oriented
+G.192 output, random offset into the profile:
+
+{\tt\small
+\begin{verbatim}
+dlyerr_2_errpat -d 200 -f 1 -w -s 1234 \
+    -i dly_err_profile_1.dat -o ep1.g192
+eid-xor -fer -ep g192 bitstream.g192 ep1.g192 output.g192
+\end{verbatim}
+}
+
+Bounded loss rate of 1\%, two frames per packet:
+
+{\tt\small
+\begin{verbatim}
+dlyerr_2_errpat -l 1 -f 2 -w -i dly_err_profile_5.dat -o ep5.g192
+\end{verbatim}
+}
+
+\subsection{Origin}
+
+Provided by Fraunhofer IIS via 3GPP Tdoc S4-121077 (TSGS4\#70, Chicago,
+13--17 Aug 2012), in support of the EVS reference codec processing plan.

src/dlyerr_2_errpat/CMakeLists.txt

@@ -0,0 +1,25 @@
+add_executable(dlyerr_2_errpat dlyerr_2_errpat.c)
+
+# default text format, constant delay
+add_test(dlyerr_2_errpat1 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/dlyerr_2_errpat
+         -i test_data/profile.dat -o test_data/t1_text.proc -L 30 -d 40)
+add_test(dlyerr_2_errpat1-verify ${CMAKE_COMMAND} -E compare_files
+         test_data/t1_text.ref test_data/t1_text.proc)
+
+# LF text format
+add_test(dlyerr_2_errpat2 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/dlyerr_2_errpat
+         -i test_data/profile.dat -o test_data/t2_lf.proc -L 30 -d 40 -c)
+add_test(dlyerr_2_errpat2-verify ${CMAKE_COMMAND} -E compare_files
+         test_data/t2_lf.ref test_data/t2_lf.proc)
+
+# word G.192 ASCII format with frame aggregation
+add_test(dlyerr_2_errpat3 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/dlyerr_2_errpat
+         -i test_data/profile.dat -o test_data/t3_word.proc -L 30 -d 40 -w -f 2)
+add_test(dlyerr_2_errpat3-verify ${CMAKE_COMMAND} -E compare_files
+         test_data/t3_word.ref test_data/t3_word.proc)
+
+# late-loss-rate driven threshold
+add_test(dlyerr_2_errpat4 ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/dlyerr_2_errpat
+         -i test_data/profile.dat -o test_data/t4_lateloss.proc -L 30 -l 5.0)
+add_test(dlyerr_2_errpat4-verify ${CMAKE_COMMAND} -E compare_files
+         test_data/t4_lateloss.ref test_data/t4_lateloss.proc)

src/dlyerr_2_errpat/README.md

@@ -0,0 +1,59 @@
+       =============================================================
+       COPYRIGHT NOTE: This source code, and all of its derivations,
+       is subject to the "ITU-T General Public License". Please have
+       it  read  in    the  distribution  disk,   or  in  the  ITU-T
+       Recommendation G.191 on "SOFTWARE TOOLS FOR SPEECH AND  AUDIO
+       CODING STANDARDS".
+       =============================================================
+
+# dlyerr_2_errpat
+
+Delay-and-error profile to frame-erasure pattern conversion tool. Reads a
+delay/error profile (one entry per packet, giving network delay in ms and a
+loss flag) and emits an error pattern suitable for use with the STL
+`eid-xor` tool. Supports both fixed-delay and bounded-loss-rate jitter
+buffer management emulation modes.
+
+Provided by Fraunhofer IIS via 3GPP Tdoc S4-121077 (TSGS4#70, Chicago,
+13–17 Aug 2012), in support of the EVS reference codec processing plan.
+
+## Source files
+
+    dlyerr_2_errpat.c: Tool source and main(); single-file program.
+
+## Usage
+
+    dlyerr_2_errpat [options]
+
+      -i <inputfile>         delay/error profile (required)
+      -o <outputfile>        error pattern (required)
+      -L <length>            output length in frames
+      -s <offset>            shift/offset in frames into the profile
+      -f <frames_per_packet> 1 or 2
+      -l <late_loss_rate>    bounded-loss-rate mode, percent
+      -d <jbm_delay_ms>      constant-JBM-delay mode, milliseconds
+      -b                     byte-oriented G.192 format (0x21 ok, 0x20 lost)
+      -w                     word-oriented G.192 (0x6b21 ok, 0x6b20 lost)
+      -c                     append LF in text format (one entry per line;
+                             was the default in V1.0)
+
+Exactly one of `-l` or `-d` must be supplied.
+
+## Examples (from S4-121077)
+
+Apply MTSI delay/error profile 1, 2, or 3 (fixed JBM delay) to a G.192
+bitstream:
+
+    dlyerr_2_errpat -d 200 -f 1 -w -s YYY -i dly_err_profile_XXX.dat -o epXXX.g192
+    eid-xor -fer g192bsin epXXX.g192 g192bsout
+
+Profiles 4 or 6 (bounded loss rate, 1 frame/packet):
+
+    dlyerr_2_errpat -l 1 -f 1 -w -s YYY -i dly_err_profile_XXX.dat -o epXXX.g192
+
+Profile 5 (bounded loss rate, 2 frames/packet):
+
+    dlyerr_2_errpat -l 1 -f 2 -w -s YYY -i dly_err_profile_5.dat -o ep5.g192
+
+`YYY` is a random offset into the profile (see the STL `random` tool for
+generating reproducible offsets).