Initial commit for ticket #929: Improve packet lost concealment (PLC) when handling burst of lost packets

WSOLA improvements:
 - Introduce fade-out and fade-in effect
 - Limit the number of continuous synthetic samples (only take effect when fading is used)
 - Export many settings as macros:
   - PJMEDIA_WSOLA_DELAY_MSEC (was HANNING_PTIME)
   - PJMEDIA_WSOLA_TEMPLATE_LENGTH_MSEC (was TEMPLATE_PTIME)
   - PJMEDIA_WSOLA_MAX_EXPAND_MSEC

PLC:
 - added compile time macro PJMEDIA_WSOLA_PLC_NO_FADING to disable fading (default enabled)

Stream:
 - fixed bug when stream is not PLC-ing subsequent packet loss (only the first)
 - also add maximum PLC limit just as precaution if PLC doesn't limit number of synthetic frames
 - unrelated: fixed warning about unused send_keep_alive() function

Delaybuf:
 - modified to NOT use fading in WSOLA since we don't expect it to generate many continuous synthetic frames



git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@2850 74dad513-b988-da41-8d7b-12977e46ad98

2 files changed, 86 insertions, 1 deletions

diff --git a/pjmedia/include/pjmedia/config.h b/pjmedia/include/pjmedia/config.h
index 7cf3652a..a81d2e71 100644
--- a/pjmedia/include/pjmedia/config.h
+++ b/pjmedia/include/pjmedia/config.h
@@ -153,6 +153,64 @@
 
 
 /**
+ * Specify the default maximum duration of synthetic audio that is generated
+ * by WSOLA. This value should be long enough to cover burst of packet losses. 
+ * but not too long, because as the duration increases the quality would 
+ * degrade considerably.
+ *
+ * Note that this limit is only applied when fading is enabled in the WSOLA
+ * session.
+ *
+ * Default: 80
+ */
+#ifndef PJMEDIA_WSOLA_MAX_EXPAND_MSEC
+#   define PJMEDIA_WSOLA_MAX_EXPAND_MSEC    80
+#endif
+
+
+/**
+ * Specify WSOLA template length, in milliseconds. The longer the template,
+ * the smoother signal to be generated at the expense of more computation
+ * needed, since the algorithm will have to compare more samples to find
+ * the most similar pitch.
+ *
+ * Default: 5
+ */
+#ifndef PJMEDIA_WSOLA_TEMPLATE_LENGTH_MSEC
+#   define PJMEDIA_WSOLA_TEMPLATE_LENGTH_MSEC	5
+#endif
+
+
+/**
+ * Specify WSOLA algorithm delay, in milliseconds. The algorithm delay is
+ * used to merge synthetic samples with real samples in the transition
+ * between real to synthetic and vice versa. The longer the delay, the 
+ * smoother signal to be generated, at the expense of longer latency and
+ * a slighty more computation.
+ *
+ * Default: 5
+ */
+#ifndef PJMEDIA_WSOLA_DELAY_MSEC
+#   define PJMEDIA_WSOLA_DELAY_MSEC	    5
+#endif
+
+
+/**
+ * Set this to non-zero to disable fade-out/in effect in the PLC when it
+ * instructs WSOLA to generate synthetic frames. The use of fading may
+ * or may not improve the quality of audio, depending on the nature of
+ * packet loss and the type of audio input (e.g. speech vs music).
+ * Disabling fading also implicitly remove the maximum limit of synthetic
+ * audio samples generated by WSOLA (see PJMEDIA_WSOLA_MAX_EXPAND_MSEC).
+ *
+ * Default: 0
+ */
+#ifndef PJMEDIA_WSOLA_PLC_NO_FADING
+#   define PJMEDIA_WSOLA_PLC_NO_FADING	    0
+#endif
+
+
+/**
  * Specify number of sound buffers. Larger number is better for sound
  * stability and to accommodate sound devices that are unable to send frames
  * in timely manner, however it would probably cause more audio delay (and 
diff --git a/pjmedia/include/pjmedia/wsola.h b/pjmedia/include/pjmedia/wsola.h
index 757e08cb..d841c16b 100644
--- a/pjmedia/include/pjmedia/wsola.h
+++ b/pjmedia/include/pjmedia/wsola.h
@@ -69,7 +69,17 @@ enum pjmedia_wsola_option
      * Specify that the WSOLA will not be used to discard frames in
      * non-contiguous buffer.
      */
-    PJMEDIA_WSOLA_NO_DISCARD = 4
+    PJMEDIA_WSOLA_NO_DISCARD = 4,
+
+    /**
+     * Disable fade-in and fade-out feature in the transition between
+     * actual and synthetic frames in WSOLA. With fade feature enabled, 
+     * WSOLA will only generate a limited number of synthetic frames 
+     * (configurable with #pjmedia_wsola_set_max_expand()), fading out 
+     * the volume on every more samples it generates, and when it reaches
+     * the limit it will only generate silence.
+     */
+    PJMEDIA_WSOLA_NO_FADING = 8
 };
 
 
@@ -96,6 +106,23 @@ PJ_DECL(pj_status_t) pjmedia_wsola_create(pj_pool_t *pool,
 
 
 /**
+ * Specify maximum number of continuous synthetic frames that can be
+ * generated by WSOLA, in milliseconds. This option will only take
+ * effect if fading is not disabled via the option when the WSOLA
+ * session was created. Default value is PJMEDIA_WSOLA_MAX_EXPAND_MSEC
+ * (see also the documentation of PJMEDIA_WSOLA_MAX_EXPAND_MSEC for
+ * more information).
+ *
+ * @param wsola	    The WSOLA session
+ * @param msec	    The duration.
+ *
+ * @return	    PJ_SUCCESS normally.
+ */
+PJ_DECL(pj_status_t) pjmedia_wsola_set_max_expand(pjmedia_wsola *wsola,
+						  unsigned msec);
+
+
+/**
  * Destroy WSOLA.
  *
  * @param wsola	    WSOLA session.