Miscellaneous comment, copyright notice, readme updates.
authorGregory Maxwell <greg@xiph.org>
Mon, 16 Feb 2009 23:56:44 +0000 (18:56 -0500)
committerGregory Maxwell <greg@xiph.org>
Tue, 17 Feb 2009 00:52:02 +0000 (19:52 -0500)
COPYING
README
libcelt/bands.h
libcelt/celt.c
libcelt/celt.h
libcelt/modes.c
libcelt/quant_bands.c
libcelt/rate.c

diff --git a/COPYING b/COPYING
index e9705a5..5e54c85 100644 (file)
--- a/COPYING
+++ b/COPYING
@@ -1,5 +1,5 @@
-Copyright 2005-2007 Christopher Montgomery, Jean-Marc Valin,
-                    Timothy Terriberry, CSIRO, and other contributors
+Copyright 2001-2009 Jean-Marc Valin, Timothy B. Terriberry,
+                    CSIRO, and other contributors
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
diff --git a/README b/README
index b957da8..73a2292 100644 (file)
--- a/README
+++ b/README
@@ -1,20 +1,88 @@
 CELT is a very low delay audio codec designed for high-quality communications.
-Its potential uses include video-conferencing and network music performance.
-The code is still in early stage, so it may be broken from time to time and
+
+Traditional full-bandwidth  codecs such as Vorbis and AAC can offer high
+quality but they require codec delays of hundreds of milliseconds, which
+makes them unsuitable  for real-time interactive applications like tele-
+conferencing. Speech targeted codecs, such as Speex or G.722, have lower
+20-40ms delays but their speech focus and limited sampling rates 
+restricts their quality, especially for music.
+
+Additionally, the other mandatory components of a full network audio system—
+audio interfaces, routers, jitter buffers— each add their own delay. For lower
+speed networks the time it takes to serialize a  packet onto the network cable
+takes considerable time, and over the long distances the speed of light
+imposes a significant delay.
+
+In teleconferencing— it is important to keep delay low so that the participants
+can communicate fluidly without talking on top of each  other and so that their
+own voices don't return after a round trip as an annoying echo.
+
+For network music performance— research has show that the total one way delay
+must be kept under 25ms to avoid degrading the musicians performance. 
+
+Since many of the sources of delay in a complete system are outside of the
+user's control (such as the  speed of light) it is often  only possible to
+reduce the total delay by reducing the codec delay. 
+
+Low delay has traditionally been considered a challenging area in audio codec
+design, because as a codec is forced to work on the smaller chunks of audio
+required for low delay it has access to less redundancy and less perceptual
+information which it can use to reduce the size of the transmitted audio.
+
+CELT is designed to bridge the gap between "music" and "speech" codecs,
+permitting new very high quality teleconferencing applications, and to go
+further, permitting latencies much lower than speech codecs normally provide
+to enable applications such as remote musical collaboration even over long
+distances.  
+
+In keeping with the Xiph.Org mission—  CELT is also designed to accomplish
+this without copyright or patent encumbrance. Only by keeping the formats
+that drive our Internet communication free and unencumbered can we maximize
+innovation, collaboration, and interoperability.  Fortunately, CELT is ahead
+of the adoption curve in its target application space, so there should be 
+no reason for someone who needs what CELT provides to go with a proprietary
+codec.
+
+CELT has been tested on x86, x86_64, ARM, and the TI C55x DSPs, and should
+be portable to any platform with a working C compiler and on the order of
+100 MIPS of processing power. 
+
+The code is still in early stage, so it may be broken from time to time, and
 the bit-stream is not frozen yet, so it is different from one version to 
 another. Oh, and don't complain if it sets your house on fire.
 
+Complaints and accolades can be directed to the CELT mailing list:
+http://lists.xiph.org/mailman/listinfo/celt-dev/
+
 To compile:
 % ./configure
 % make
 
-To test the encoder:
+For platforms without fast floating point support (such as ARM) use the
+--enable-fixed argument to configure to build a fixed-point version of CELT.
+
+There are Ogg-based encode/decode tools in tools/. These are quite similar to
+the speexenc/speexdec tools. Use the --help option for details.
+
+There is also a basic tool for testing the encoder and decoder called
+"testcelt" located in libcelt/: 
+
 % testcelt <rate> <channels> <frame size> <bytes per packet> input.sw output.sw
 
-where input.sw is a 16-bit (machine endian) audio file sampled at 
-44.1 kHz or 48 kHz. The output file is already decompressed. 
-the <rate> parameter is the number of bytes per packet to use.
+where input.sw is a 16-bit (machine endian) audio file sampled at 32000 Hz to 
+96000 Hz. The output file is already decompressed.  
+
+For example, for a 44.1 kHz mono stream at ~64kbit/sec and with 256 sample
+frames:
+
+% testcelt 44100 1 256 46 intput.sw output.sw 
+
+Since 44100/256*46*8 = 63393.74 bits/sec.
 
-Alternatively, there are now Ogg-based tools in tools/. Use 
-the --help option for details. These are quite similar to the
-speexenc/speexdec tools.
+All even frame sizes from 64 to 512 are currently supported, although
+power-of-two sizes are recommended  and most CELT development is done
+using a size of 256.  The delay imposed by CELT is  1.25x - 1.5x  the 
+frame duration depending on the frame size and some details of CELT's
+internal operation.  For 256 sample frames the delay is 1.5x  or  384
+samples, so the total codec delay in the above example is 8.70ms 
+(1000/(44100/384)).   
index 8955a49..c1609f2 100644 (file)
 #include "entdec.h"
 #include "rate.h"
 
-/** Applies a series of rotations so that pulses are spread like a two-sided
-exponential. The effect of this is to reduce the tonal noise created by the
-sparse spectrum resulting from the pulse codebook */
-void exp_rotation(celt_norm_t *X, int len, int dir, int stride, int iter);
-
 /** Compute the amplitude (sqrt energy) in each of the bands 
  * @param m Mode data 
  * @param X Spectrum
index 9877fe3..2774edd 100644 (file)
@@ -656,10 +656,11 @@ int celt_encode_float(CELTEncoder * restrict st, const celt_sig_t * pcm, celt_si
          }
       }
    }
-   /*fprintf (stderr, "remaining bits after encode = %d\n", nbCompressedBytes*8-ec_enc_tell(&st->enc, 0));*/
-   /*if (ec_enc_tell(&st->enc, 0) < nbCompressedBytes*8 - 7)
-      celt_warning_int ("many unused bits: ", nbCompressedBytes*8-ec_enc_tell(&st->enc, 0));*/
-   /*printf ("%d\n", ec_enc_tell(&st->enc, 0)-8*nbCompressedBytes);*/
+
+   /*fprintf (stderr, "remaining bits after encode = %d\n", nbCompressedBytes*8-ec_enc_tell(&enc, 0));*/
+   /*if (ec_enc_tell(&enc, 0) < nbCompressedBytes*8 - 7)
+      celt_warning_int ("many unused bits: ", nbCompressedBytes*8-ec_enc_tell(&enc, 0));*/
+
    /* Finishing the stream with a 0101... pattern so that the decoder can check is everything's right */
    {
       int val = 0;
index c5bf4ea..251007b 100644 (file)
@@ -159,7 +159,7 @@ EXPORT void celt_encoder_destroy(CELTEncoder *st);
  *                        (can change from one frame to another)
  @return Number of bytes written to "compressed". Should be the same as 
  *       "nbCompressedBytes" unless the stream is VBR. If negative, an error
- *       has occured (see error codes). It is IMPORTANT that the length returned
+ *       has occurred (see error codes). It is IMPORTANT that the length returned
  *       be somehow transmitted to the decoder. Otherwise, no decoding is possible.
 */
 EXPORT int celt_encode_float(CELTEncoder *st, const float *pcm, float *optional_synthesis, unsigned char *compressed, int nbCompressedBytes);
@@ -176,7 +176,7 @@ EXPORT int celt_encode_float(CELTEncoder *st, const float *pcm, float *optional_
  *                        (can change from one frame to another)
  @return Number of bytes written to "compressed". Should be the same as 
  *       "nbCompressedBytes" unless the stream is VBR. If negative, an error
- *       has occured (see error codes). It is IMPORTANT that the length returned
+ *       has occurred (see error codes). It is IMPORTANT that the length returned
  *       be somehow transmitted to the decoder. Otherwise, no decoding is possible.
  */
 EXPORT int celt_encode(CELTEncoder *st, const celt_int16_t *pcm, celt_int16_t *optional_synthesis, unsigned char *compressed, int nbCompressedBytes);
index 061a7df..8cced7c 100644 (file)
@@ -1,4 +1,4 @@
-/* (C) 2007-2008 Jean-Marc Valin, CSIRO
+/* (C) 2007-2009 Jean-Marc Valin, CSIRO
    (C) 2008 Gregory Maxwell */
 /*
    Redistribution and use in source and binary forms, with or without
index 3ad16eb..0dd2a7d 100644 (file)
@@ -112,7 +112,7 @@ static void quant_coarse_energy_mono(const CELTMode *m, celt_ener_t *eBands, cel
    celt_word16_t prev = 0;
    celt_word16_t coef = m->ePredCoef;
    celt_word16_t beta;
-   /* The .7 is a heuristic */
+   /* The .8 is a heuristic */
    beta = MULT16_16_Q15(QCONST16(.8f,15),coef);
    
    bits = ec_enc_tell(enc, 0);
@@ -196,7 +196,7 @@ static void unquant_coarse_energy_mono(const CELTMode *m, celt_ener_t *eBands, c
    unsigned bits;
    celt_word16_t prev = 0;
    celt_word16_t coef = m->ePredCoef;
-   /* The .7 is a heuristic */
+   /* The .8 is a heuristic */
    celt_word16_t beta = MULT16_16_Q15(QCONST16(.8f,15),coef);
    
    bits = ec_dec_tell(dec, 0);
index 38b193d..8e1a9c0 100644 (file)
@@ -1,4 +1,4 @@
-/* (C) 2007-2008 Jean-Marc Valin, CSIRO
+/* (C) 2007-2009 Jean-Marc Valin, CSIRO
 */
 /*
    Redistribution and use in source and binary forms, with or without