plc.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * plc.h
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2004 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: plc.h,v 1.8 2005/11/25 14:52:00 steveu Exp $
00027  */
00028 
00029 /*! \file */
00030 
00031 #if !defined(_PLC_H_)
00032 #define _PLC_H_
00033 
00034 /*! \page plc_page Packet loss concealment
00035 \section plc_page_sec_1 What does it do?
00036 The packet loss concealment module provides a suitable synthetic fill-in signal,
00037 to minimise the audible effect of lost packets in VoIP applications. It is not
00038 tied to any particular codec, and could be used with almost any codec which does not
00039 specify its own procedure for packet loss concealment.
00040 
00041 Where a codec specific concealment procedure exists, the algorithm is usually built
00042 around knowledge of the characteristics of the particular codec. It will, therefore,
00043 generally give better results for that particular codec than this generic concealer will.
00044 
00045 \section plc_page_sec_2 How does it work?
00046 While good packets are being received, the plc_rx() routine keeps a record of the trailing
00047 section of the known speech signal. If a packet is missed, plc_fillin() is called to produce
00048 a synthetic replacement for the real speech signal. The average mean difference function
00049 (AMDF) is applied to the last known good signal, to determine its effective pitch.
00050 Based on this, the last pitch period of signal is saved. Essentially, this cycle of speech
00051 will be repeated over and over until the real speech resumes. However, several refinements
00052 are needed to obtain smooth pleasant sounding results.
00053 
00054 - The two ends of the stored cycle of speech will not always fit together smoothly. This can
00055   cause roughness, or even clicks, at the joins between cycles. To soften this, the
00056   1/4 pitch period of real speech preceeding the cycle to be repeated is blended with the last
00057   1/4 pitch period of the cycle to be repeated, using an overlap-add (OLA) technique (i.e.
00058   in total, the last 5/4 pitch periods of real speech are used).
00059 
00060 - The start of the synthetic speech will not always fit together smoothly with the tail of
00061   real speech passed on before the erasure was identified. Ideally, we would like to modify
00062   the last 1/4 pitch period of the real speech, to blend it into the synthetic speech. However,
00063   it is too late for that. We could have delayed the real speech a little, but that would
00064   require more buffer manipulation, and hurt the efficiency of the no-lost-packets case
00065   (which we hope is the dominant case). Instead we use a degenerate form of OLA to modify
00066   the start of the synthetic data. The last 1/4 pitch period of real speech is time reversed,
00067   and OLA is used to blend it with the first 1/4 pitch period of synthetic speech. The result
00068   seems quite acceptable.
00069 
00070 - As we progress into the erasure, the chances of the synthetic signal being anything like
00071   correct steadily fall. Therefore, the volume of the synthesized signal is made to decay
00072   linearly, such that after 50ms of missing audio it is reduced to silence.
00073 
00074 - When real speech resumes, an extra 1/4 pitch period of sythetic speech is blended with the
00075   start of the real speech. If the erasure is small, this smoothes the transition. If the erasure
00076   is long, and the synthetic signal has faded to zero, the blending softens the start up of the
00077   real signal, avoiding a kind of "click" or "pop" effect that might occur with a sudden onset.
00078 
00079 \section plc_page_sec_3 How do I use it?
00080 Before audio is processed, call plc_init() to create an instance of the packet loss
00081 concealer. For each received audio packet that is acceptable (i.e. not including those being
00082 dropped for being too late) call plc_rx() to record the content of the packet. Note this may
00083 modify the packet a little after a period of packet loss, to blend real synthetic data smoothly.
00084 When a real packet is not available in time, call plc_fillin() to create a sythetic substitute.
00085 That's it!
00086 */
00087 
00088 /*! Minimum allowed pitch (66 Hz) */
00089 #define PLC_PITCH_MIN           120
00090 /*! Maximum allowed pitch (200 Hz) */
00091 #define PLC_PITCH_MAX           40
00092 /*! Maximum pitch OLA window */
00093 #define PLC_PITCH_OVERLAP_MAX   (PLC_PITCH_MIN >> 2)
00094 /*! The length over which the AMDF function looks for similarity (20 ms) */
00095 #define CORRELATION_SPAN        160
00096 /*! History buffer length. The buffer much also be at leat 1.25 times
00097     PLC_PITCH_MIN, but that is much smaller than the buffer needs to be for
00098     the pitch assessment. */
00099 #define PLC_HISTORY_LEN         (CORRELATION_SPAN + PLC_PITCH_MIN)
00100 
00101 /*!
00102     The generic packet loss concealer context.
00103 */
00104 typedef struct
00105 {
00106     /*! Consecutive erased samples */
00107     int missing_samples;
00108     /*! Current offset into pitch period */
00109     int pitch_offset;
00110     /*! Pitch estimate */
00111     int pitch;
00112     /*! Buffer for a cycle of speech */
00113     float pitchbuf[PLC_PITCH_MIN];
00114     /*! History buffer */
00115     int16_t history[PLC_HISTORY_LEN];
00116     /*! Current pointer into the history buffer */
00117     int buf_ptr;
00118 } plc_state_t;
00119 
00120 
00121 #ifdef __cplusplus
00122 extern "C" {
00123 #endif
00124 
00125 /*! Process a block of received audio samples for PLC.
00126     \brief Process a block of received audio samples for PLC.
00127     \param s The packet loss concealer context.
00128     \param amp The audio sample buffer.
00129     \param len The number of samples in the buffer.
00130     \return The number of samples in the buffer. */
00131 int plc_rx(plc_state_t *s, int16_t amp[], int len);
00132 
00133 /*! Fill-in a block of missing audio samples.
00134     \brief Fill-in a block of missing audio samples.
00135     \param s The packet loss concealer context.
00136     \param amp The audio sample buffer.
00137     \param len The number of samples to be synthesised.
00138     \return The number of samples synthesized. */
00139 int plc_fillin(plc_state_t *s, int16_t amp[], int len);
00140 
00141 /*! Initialise a packet loss concealer context.
00142     \brief Initialise a PLC context.
00143     \param s The packet loss concealer context.
00144     \return A pointer to the the packet loss concealer context. */
00145 plc_state_t *plc_init(plc_state_t *s);
00146 
00147 /*! Free a packet loss concealer context.
00148     \param s The packet loss concealer context.
00149     \return 0 for OK. */
00150 int plc_release(plc_state_t *s);
00151 
00152 #ifdef __cplusplus
00153 }
00154 #endif
00155 
00156 #endif
00157 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1