Changed some of the mode data from int to celt_int16_t to save memory.
[opus.git] / libcelt / celt.h
index 2418f40..4d44f5e 100644 (file)
@@ -1,5 +1,10 @@
-/* (C) 2007 Jean-Marc Valin, CSIRO
+/* (C) 2007-2008 Jean-Marc Valin, CSIRO
 */
+/**
+  @file celt.h
+  @brief Contains all the functions for encoding and decoding audio streams
+ */
+
 /*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
 #ifndef CELT_H
 #define CELT_H
 
+#include "celt_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Error codes */
+/** No error */
+#define CELT_OK                0
+/** An (or more) invalid argument (e.g. out of range) */
+#define CELT_BAD_ARG          -1
+/** The mode struct passed is invalid */
+#define CELT_INVALID_MODE     -2
+/** An internal error was detected */
+#define CELT_INTERNAL_ERROR   -3
+/** The data passed (e.g. compressed data to decoder) is corrupted */
+#define CELT_CORRUPTED_DATA   -4
+
+/* Requests */
+/** GET the frame size used in the current mode */
+#define CELT_GET_FRAME_SIZE   1000
+/** GET the lookahead used in the current mode */
+#define CELT_GET_LOOKAHEAD    1001
+/** GET the number of channels used in the current mode */
+#define CELT_GET_NB_CHANNELS  1002
+
+
+/** Contains the state of an encoder. One encoder state is needed for each 
+    stream. It is initialised once at the beginning of the stream. Do *not*
+    re-initialise the state for every frame.
+   @brief Encoder state
+ */
 typedef struct CELTEncoder CELTEncoder;
+
+/** State of the decoder. One decoder state is needed for each stream. It is
+    initialised once at the beginning of the stream. Do *not* re-initialise
+    the state for every frame */
 typedef struct CELTDecoder CELTDecoder;
 
+/** The mode contains all the information necessary to create an encoder. Both
+    the encoder and decoder need to be initialised with exactly the same mode,
+    otherwise the quality will be very bad */
 typedef struct CELTMode CELTMode;
 
-extern const CELTMode const *celt_mode1;
-extern const CELTMode const *celt_mode2;
-extern const CELTMode const *celt_mode3;
+
+/** \defgroup codec Encoding and decoding */
+/*  @{ */
+
+/* Mode calls */
+
+/** Creates a new mode struct. This will be passed to an encoder or decoder.
+    The mode MUST NOT BE DESTROYED until the encoders and decoders that use it
+    are destroyed as well.
+ @param Fs Sampling rate (32000 to 64000 Hz)
+ @param channels Number of channels
+ @param frame_size Number of samples (per channel) to encode in each packet (64 - 256)
+ @param lookahead Extra latency (in samples per channel) in addition to the frame size (between 32 and frame_size). The larger that value, the better the quality (at the expense of latency)
+ @param error Returned error code (if NULL, no error will be returned)
+ @return A newly created mode
+*/
+CELTMode *celt_mode_create(celt_int32_t Fs, int channels, int frame_size, int lookahead, int *error);
+
+/** Destroys a mode struct. Only call this after all encoders and decoders
+    using this mode are destroyed as well.
+ @param mode Mode to be destroyed
+*/
+void celt_mode_destroy(CELTMode *mode);
+
+/** Query information from a mode */
+int celt_mode_info(const CELTMode *mode, int request, celt_int32_t *value);
+
 
 /* Encoder stuff */
 
-CELTEncoder *celt_encoder_new(const CELTMode *mode);
 
-void celt_encoder_destroy(CELTEncoder *st);
+/** Creates a new encoder state. Each stream needs its own encoder state (can't
+    be shared across simultaneous streams).
+ @param mode Contains all the information about the characteristics of the stream
+             (must be the same characteristics as used for the decoder)
+ @return Newly created encoder state.
+*/
+CELTEncoder *celt_encoder_create(const CELTMode *mode);
 
-int celt_encode(CELTEncoder *st, short *pcm);
+/** Destroys a an encoder state.
+ @param st Encoder state to be destroyed
+ */
+void celt_encoder_destroy(CELTEncoder *st);
 
-char *celt_encoder_get_bytes(CELTEncoder *st, int *nbBytes);
+/** Encodes a frame of audio.
+ @param st Encoder state
+ @param pcm PCM audio in signed 16-bit format (native endian). There must be 
+            exactly frame_size samples per channel. The input data is 
+            overwritten by a copy of what the remote decoder would decode.
+ @param compressed The compressed data is written here
+ @param nbCompressedBytes Number of bytes to use for compressing the frame
+                          (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
+         be somehow transmitted to the decoder. Otherwise, no decoding is possible.
+*/
+int celt_encode(CELTEncoder *st, celt_int16_t *pcm, unsigned char *compressed, int nbCompressedBytes);
 
 /* Decoder stuff */
 
-CELTDecoder *celt_decoder_new(const CELTMode *mode);
 
+/** Creates a new decoder state. Each stream needs its own decoder state (can't
+    be shared across simultaneous streams).
+ @param mode Contains all the information about the characteristics of the
+             stream (must be the same characteristics as used for the encoder)
+ @return Newly created decoder state.
+ */
+CELTDecoder *celt_decoder_create(const CELTMode *mode);
+
+/** Destroys a a decoder state.
+ @param st Decoder state to be destroyed
+ */
 void celt_decoder_destroy(CELTDecoder *st);
 
-int celt_decode(CELTDecoder *st, char *data, int len, short *pcm);
+/** Decodes a frame of audio.
+ @param st Decoder state
+ @param data Compressed data produced by an encoder
+ @param len Number of bytes to read from "data". This MUST be exactly the number
+            of bytes returned by the encoder. Using a larger value WILL NOT WORK.
+ @param pcm One frame (frame_size samples per channel) of decoded PCM will be
+            returned here. 
+ @return Error code.
+   */
+int celt_decode(CELTDecoder *st, unsigned char *data, int len, celt_int16_t *pcm);
+
+/*  @} */
+
+
+#ifdef __cplusplus
+}
+#endif
 
 #endif /*CELT_H */