[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Commit-gnuradio] r5096 - gnuradio/trunk/gr-cvsd-vocoder/src/lib
|
From: |
trondeau |
|
Subject: |
[Commit-gnuradio] r5096 - gnuradio/trunk/gr-cvsd-vocoder/src/lib |
|
Date: |
Tue, 24 Apr 2007 15:33:42 -0600 (MDT) |
Author: trondeau
Date: 2007-04-24 15:33:42 -0600 (Tue, 24 Apr 2007)
New Revision: 5096
Modified:
gnuradio/trunk/gr-cvsd-vocoder/src/lib/cvsd_decode_bs.h
gnuradio/trunk/gr-cvsd-vocoder/src/lib/cvsd_encode_sb.h
Log:
adding proper documentation to CVSD vocoder
Modified: gnuradio/trunk/gr-cvsd-vocoder/src/lib/cvsd_decode_bs.h
===================================================================
--- gnuradio/trunk/gr-cvsd-vocoder/src/lib/cvsd_decode_bs.h 2007-04-24
21:09:59 UTC (rev 5095)
+++ gnuradio/trunk/gr-cvsd-vocoder/src/lib/cvsd_decode_bs.h 2007-04-24
21:33:42 UTC (rev 5096)
@@ -28,6 +28,22 @@
typedef boost::shared_ptr<cvsd_decode_bs> cvsd_decode_bs_sptr;
+ /*!
+ * \brief Constructor parameters to initialize the CVSD decoder. The default
+ * values are modeled after the Bluetooth standard and should not be changed,
+ * except by an advanced user
+ *
+ * \param min_step Minimum step size used to update the internal
reference. Default: "10"
+ * \param max_step Maximum step size used to update the internal
reference. Default: "1280"
+ * \param step_decay Decay factor applied to step size when there is not
a run of J output 1s or 0s. Default: "0.9990234375" (i.e. 1-1/1024)
+ * \param accum_decay Decay factor applied to the internal reference
during every interation of the codec. Default: "0.96875" (i.e. 1-1/32)
+ * \param K; Size of shift register; the number of output bits
remembered by codec (must be less or equal to 32). Default: "32"
+ * \param J; Number of bits in the shift register that are equal;
i.e. the size of a run of 1s, 0s. Default: "4"
+ * \param pos_accum_max Maximum integer value allowed for the internal
reference. Default: "32767" (2^15 - 1 or MAXSHORT)
+ * \param neg_accum_max Minimum integer value allowed for the internal
reference. Default: "-32767" (-2^15 + 1 or MINSHORT+1)
+ *
+ */
+
cvsd_decode_bs_sptr cvsd_make_decode_bs (short min_step=10,
short max_step=1280,
double step_decay=0.9990234375,
@@ -37,6 +53,58 @@
short pos_accum_max=32767,
short neg_accum_max=-32767);
+/*!
+ * \brief This block performs CVSD audio decoding. Its design and
implementation
+ * is modeled after the CVSD encoder/decoder specifications defined in the
+ * Bluetooth standard.
+ *
+ * \ingroup block
+ *
+ * CVSD is a method for encoding speech that seeks to reduce the
+ * bandwidth required for digital voice transmission. CVSD takes
+ * advantage of strong correlation between samples, quantizing the
+ * difference in amplitude between two consecutive samples. This
+ * difference requires fewer quantization levels as compared to other
+ * methods that quantize the actual amplitude level, reducing the
+ * bandwidth. CVSD employs a two level quantizer (one bit) and an
+ * adaptive algorithm that allows for continuous step size adjustment.
+ *
+ * The coder can represent low amplitude signals with accuracy without
+ * sacrificing performance on large amplitude signals, a trade off that
+ * occurs in some non-adaptive modulations.
+ *
+ * The CVSD decoder effectively provides 1-to-8 decompression. More
+ * specifically, for each incoming input bit, the decoder outputs one
+ * audio sample. If the input is a "1" bit, the internal reference is
+ * increased appropriately and then outputted as the next estimated audio
+ * sample. If the input is a "0" bit, the internal reference is
+ * decreased appropriately and then likewise outputted as the next estimated
+ * audio sample. Grouping 8 input bits together, the encoder essentially
+ * produces 8 output audio samples for everyone one input byte.
+ *
+ * This decoder requires that output audio samples are 2-byte short signed
+ * integers. The result bandwidth conversion, therefore, is 1 byte of
+ * encoded audio data to 16 output bytes of raw audio data.
+ *
+ * The CVSD decoder module must be post-fixed by a down-converter to
+ * under-sample the audio data after decoding. The Bluetooth standard
+ * specifically calls for a 8-to-1 decimating down-converter. This is
+ * required so that so that output sampling rate equals the original input
+ * sampling rate present before the encoder. In all cases, the output
+ * down-converter rate must be the inverse of the input up-converter rate
+ * before the CVSD encoder.
+ *
+ * References:
+ * 1. Continuously Variable Slope Delta Modulation (CVSD) A Tutorial,
+ * Available:
http://www.eetkorea.com/ARTICLES/2003AUG/A/2003AUG29_NTEK_RFD_AN02.PDF.
+ * 2. Specification of The Bluetooth System
+ * Available:
http://grouper.ieee.org/groups/802/15/Bluetooth/core_10_b.pdf.
+ * 3. McGarrity, S., Bluetooth Full Duplex Voice and Data Transmission. 2002.
+ * Bluetooth Voice Simulink� Model, Available:
+ *
http://www.mathworks.com/company/newsletters/digest/nov01/bluetooth.html
+ *
+ */
+
class cvsd_decode_bs : public gr_sync_interpolator
{
private:
@@ -53,8 +121,17 @@
double accum_decay, int K, int J,
short pos_accum_max, short neg_accum_max);
+ //! Member functions required by the encoder/decoder
+ //! \brief Rounding function specific to CVSD
+ //! \return the input value rounded to the nearest integer
int cvsd_round(double input);
+
+ //! \brief A power function specific to CVSD data formats
+ //! \return (radix)^power, where radix and power are short integers
unsigned int cvsd_pow (short radix, short power);
+
+ //! \brief Sums number of 1's in the input
+ //! \return the number of 1s in the four bytes of an input unsigned integer
unsigned char cvsd_bitwise_sum (unsigned int input);
short d_min_step;
@@ -62,20 +139,17 @@
double d_step_decay;
double d_accum_decay;
- //! \brief Size of shift register; the number of output bits remembered in
shift register
- int d_K;
+ int d_K; //!< \brief Size of shift register; the number of output bits
remembered in shift register
+ int d_J; //!< \brief Number of bits in the shift register that are equal;
size of run of 1s, 0s
- //! \brief Number of bits in the shift register that are equal; size of run
of 1s, 0s
- int d_J;
-
short d_pos_accum_max;
short d_neg_accum_max;
- int d_accum;
- int d_loop_counter;
- unsigned int d_runner;
- unsigned int d_runner_mask; // 4 bytes, 0 .. 4,294,967,295
- short d_stepsize;
+ int d_accum; //!< \brief Current value of internal reference
+ int d_loop_counter; //!< \brief Current value of the loop counter
+ unsigned int d_runner; //!< \brief Current value of the shift register
+ unsigned int d_runner_mask; //!< \brief Value of the mask to access the last
J bits of the shift register
+ short d_stepsize; //!< \brief Current value of the step sizer
public:
~cvsd_decode_bs (); // public destructor
Modified: gnuradio/trunk/gr-cvsd-vocoder/src/lib/cvsd_encode_sb.h
===================================================================
--- gnuradio/trunk/gr-cvsd-vocoder/src/lib/cvsd_encode_sb.h 2007-04-24
21:09:59 UTC (rev 5095)
+++ gnuradio/trunk/gr-cvsd-vocoder/src/lib/cvsd_encode_sb.h 2007-04-24
21:33:42 UTC (rev 5096)
@@ -28,6 +28,22 @@
typedef boost::shared_ptr<cvsd_encode_sb> cvsd_encode_sb_sptr;
+ /*!
+ * \brief Constructor parameters to initialize the CVSD encoder. The default
+ * values are modeled after the Bluetooth standard and should not be changed
+ * except by an advanced user
+ *
+ * \param min_step Minimum step size used to update the internal
reference. Default: "10"
+ * \param max_step Maximum step size used to update the internal
reference. Default: "1280"
+ * \param step_decay Decay factor applied to step size when there is not
a run of J output 1s or 0s. Default: "0.9990234375" (i.e. 1-1/1024)
+ * \param accum_decay Decay factor applied to the internal reference
during every interation of the codec. Default: "0.96875" (i.e. 1-1/32)
+ * \param K; Size of shift register; the number of output bits
remembered by codec (must be less or equal to 32). Default: "32"
+ * \param J; Number of bits in the shift register that are equal;
i.e. the size of a run of 1s, 0s. Default: "4"
+ * \param pos_accum_max Maximum integer value allowed for the internal
reference. Default: "32767" (2^15 - 1 or MAXSHORT)
+ * \param neg_accum_max Minimum integer value allowed for the internal
reference. Default: "-32767" (-2^15 + 1 or MINSHORT+1)
+ *
+ */
+
cvsd_encode_sb_sptr cvsd_make_encode_sb (short min_step=10,
short max_step=1280,
double step_decay=0.9990234375,
@@ -37,6 +53,60 @@
short pos_accum_max=32767,
short neg_accum_max=-32767);
+/*!
+ * \brief This block performs CVSD audio encoding. Its design and
implementation
+ * is modeled after the CVSD encoder/decoder specifications defined in the
+ * Bluetooth standard.
+ *
+ * \ingroup block
+ *
+ * CVSD is a method for encoding speech that seeks to reduce the
+ * bandwidth required for digital voice transmission. CVSD takes
+ * advantage of strong correlation between samples, quantizing the
+ * difference in amplitude between two consecutive samples. This
+ * difference requires fewer quantization levels as compared to other
+ * methods that quantize the actual amplitude level, reducing the
+ * bandwidth. CVSD employs a two level quantizer (one bit) and an
+ * adaptive algorithm that allows for continuous step size adjustment.
+ *
+ * The coder can represent low amplitude signals with accuracy without
+ * sacrificing performance on large amplitude signals, a trade off that
+ * occurs in some non-adaptive modulations.
+ *
+ * The CVSD encoder effectively provides 8-to-1 compression. More
+ * specifically, each incoming audio sample is compared to an internal
+ * reference value. If the input is greater or equal to the reference,
+ * the encoder outputs a "1" bit. If the input is less than the reference,
+ * the encoder outputs a "0" bit. The reference value is then updated
+ * accordingly based on the frequency of outputted "1" or "0" bits. By
+ * grouping 8 outputs bits together, the encoder essentially produce one
+ * output byte for every 8 input audio samples.
+ *
+ * This encoder requires that input audio samples are 2-byte short signed
+ * integers. The result bandwidth conversion, therefore, is 16 input bytes
+ * of raw audio data to 1 output byte of encoded audio data.
+ *
+ * The CVSD encoder module must be prefixed by an up-converter to over-sample
+ * the audio data prior to encoding. The Bluetooth standard specifically
+ * calls for a 1-to-8 interpolating up-converter. While this reduces the
+ * overall compression of the codec, this is required so that the encoder
+ * can accurately compute the slope between adjacent audio samples and
+ * correctly update its internal reference value.
+ *
+ * References:
+ *
+ * 1. Continuously Variable Slope Delta Modulation (CVSD) A Tutorial,
+ * Available:
http://www.eetkorea.com/ARTICLES/2003AUG/A/2003AUG29_NTEK_RFD_AN02.PDF.
+ *
+ * 2. Specification of The Bluetooth System
+ * Available:
http://grouper.ieee.org/groups/802/15/Bluetooth/core_10_b.pdf.
+ *
+ * 3. McGarrity, S., Bluetooth Full Duplex Voice and Data Transmission. 2002.
+ * Bluetooth Voice Simulink� Model, Available:
+ * http://www.mathworks.com/company/newsletters/digest/nov01/bluetooth.html
+ *
+ */
+
class cvsd_encode_sb : public gr_sync_decimator
{
private:
@@ -53,28 +123,35 @@
double accum_decay, int K, int J,
short pos_accum_max, short neg_accum_max);
+ //! Member functions required by the encoder/decoder
+ //! \brief Rounding function specific to CVSD
+ //! \return the input value rounded to the nearest integer
int cvsd_round(double input);
+
+ //! \brief A power function specific to CVSD data formats
+ //! \return (radix)^power, where radix and power are short integers
unsigned int cvsd_pow (short radix, short power);
+
+ //! \brief Sums number of 1's in the input
+ //! \return the number of 1s in the four bytes of an input unsigned integer
unsigned char cvsd_bitwise_sum (unsigned int input);
+ // Members variables related to the CVSD encoder use to update interal
reference value
short d_min_step;
short d_max_step;
double d_step_decay;
double d_accum_decay;
- //! \brief Size of shift register; the number of output bits remembered in
shift register
- int d_K;
-
- //! \brief Number of bits in the shift register that are equal; size of run
of 1s, 0s
- int d_J;
-
+ int d_K; //!< \brief Size of shift register; the number of output bits
remembered in shift register
+ int d_J; //!< \brief Number of bits in the shift register that are equal;
size of run of 1s, 0s
+
short d_pos_accum_max;
short d_neg_accum_max;
- int d_accum;
- int d_loop_counter;
- unsigned int d_runner;
- short d_stepsize;
+ int d_accum; //!< \brief Current value of internal reference
+ int d_loop_counter; //!< \brief Current value of the loop counter
+ unsigned int d_runner; //!< \brief Current value of the shift register
+ short d_stepsize; //!< \brief Current value of the step sizer
public:
~cvsd_encode_sb (); // public destructor
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Commit-gnuradio] r5096 - gnuradio/trunk/gr-cvsd-vocoder/src/lib,
trondeau <=