include/vorbis/codec.h

   1 /********************************************************************
   2  *                                                                  *
   3  * THIS FILE IS PART OF THE Ogg Vorbis SOFTWARE CODEC SOURCE CODE.  *
   4  * USE, DISTRIBUTION AND REPRODUCTION OF THIS SOURCE IS GOVERNED BY *
   5  * THE GNU PUBLIC LICENSE 2, WHICH IS INCLUDED WITH THIS SOURCE.    *
   6  * PLEASE READ THESE TERMS DISTRIBUTING.                            *
   7  *                                                                  *
   8  * THE OggSQUISH SOURCE CODE IS (C) COPYRIGHT 1994-2000             *
   9  * by Monty <monty@xiph.org> and The XIPHOPHORUS Company            *
  10  * http://www.xiph.org/                                             *
  11  *                                                                  *
  12  ********************************************************************
  13
  14  function: libvorbis codec headers
  15  last mod: $Id: codec.h,v 1.32 2000/10/12 07:28:03 jack Exp $
  16
  17  ********************************************************************/
  18
  19 #ifndef _vorbis_codec_h_
  20 #define _vorbis_codec_h_
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif /* __cplusplus */
  26
  27 #define MAX_BARK 27
  28
  29 #include <ogg/ogg.h>
  30 #include "vorbis/codebook.h"
  31
  32 typedef void vorbis_look_transform;
  33 typedef void vorbis_info_time;
  34 typedef void vorbis_look_time;
  35 typedef void vorbis_info_floor;
  36 typedef void vorbis_look_floor;
  37 typedef void vorbis_echstate_floor;
  38 typedef void vorbis_info_residue;
  39 typedef void vorbis_look_residue;
  40 typedef void vorbis_info_mapping;
  41 typedef void vorbis_look_mapping;
  42
  43 /* mode ************************************************************/
  44 typedef struct {
  45   int blockflag;
  46   int windowtype;
  47   int transformtype;
  48   int mapping;
  49 } vorbis_info_mode;
  50
  51 /* psychoacoustic setup ********************************************/
  52 #define P_BANDS 17
  53 #define P_LEVELS 11
  54 typedef struct vorbis_info_psy{
  55   int    athp;
  56   int    decayp;
  57   int    smoothp;
  58
  59   int    noisecullp;
  60   float noisecull_barkwidth;
  61
  62   float ath_adjatt;
  63   float ath_maxatt;
  64
  65   /*     0  1  2   3   4   5   6   7   8   9  10  11  12  13  14  15   16   */
  66   /* x: 63 88 125 175 250 350 500 700 1k 1.4k 2k 2.8k 4k 5.6k 8k 11.5k 16k Hz */
  67   /* y: 0 10 20 30 40 50 60 70 80 90 100 dB */
  68
  69   int tonemaskp;
  70   float toneatt[P_BANDS][P_LEVELS];
  71
  72   int peakattp;
  73   float peakatt[P_BANDS][P_LEVELS];
  74
  75   int noisemaskp;
  76   float noiseatt[P_BANDS][P_LEVELS];
  77
  78   float max_curve_dB;
  79
  80   /* decay setup */
  81   float attack_coeff;
  82   float decay_coeff;
  83 } vorbis_info_psy;
  84
  85 /* vorbis_info contains all the setup information specific to the
  86    specific compression/decompression mode in progress (eg,
  87    psychoacoustic settings, channel setup, options, codebook
  88    etc).
  89 *********************************************************************/
  90
  91 typedef struct vorbis_info{
  92   int version;
  93   int channels;
  94   long rate;
  95
  96   /* The below bitrate declarations are *hints*.
  97      Combinations of the three values carry the following implications:
  98
  99      all three set to the same value:
 100        implies a fixed rate bitstream
 101      only nominal set:
 102        implies a VBR stream that averages the nominal bitrate.  No hard
 103        upper/lower limit
 104      upper and or lower set:
 105        implies a VBR bitstream that obeys the bitrate limits. nominal
 106        may also be set to give a nominal rate.
 107      none set:
 108        the coder does not care to speculate.
 109   */
 110
 111   long bitrate_upper;
 112   long bitrate_nominal;
 113   long bitrate_lower;
 114
 115   /* Vorbis supports only short and long blocks, but allows the
 116      encoder to choose the sizes */
 117
 118   long blocksizes[2];
 119
 120   /* modes are the primary means of supporting on-the-fly different
 121      blocksizes, different channel mappings (LR or mid-side),
 122      different residue backends, etc.  Each mode consists of a
 123      blocksize flag and a mapping (along with the mapping setup */
 124
 125   int        modes;
 126   int        maps;
 127   int        times;
 128   int        floors;
 129   int        residues;
 130   int        books;
 131   int        psys;     /* encode only */
 132
 133   vorbis_info_mode    *mode_param[64];
 134   int                  map_type[64];
 135   vorbis_info_mapping *map_param[64];
 136   int                  time_type[64];
 137   vorbis_info_time    *time_param[64];
 138   int                  floor_type[64];
 139   vorbis_info_floor   *floor_param[64];
 140   int                  residue_type[64];
 141   vorbis_info_residue *residue_param[64];
 142   static_codebook     *book_param[256];
 143   vorbis_info_psy     *psy_param[64]; /* encode only */
 144
 145   /* for block long/sort tuning; encode only */
 146   int        envelopesa;
 147   float     preecho_thresh;
 148   float     preecho_clamp;
 149   float     preecho_minenergy;
 150 } vorbis_info;
 151
 152 /* vorbis_dsp_state buffers the current vorbis audio
 153    analysis/synthesis state.  The DSP state belongs to a specific
 154    logical bitstream ****************************************************/
 155 typedef struct vorbis_dsp_state{
 156   int analysisp;
 157   vorbis_info *vi;
 158   int    modebits;
 159
 160   float **pcm;
 161   float **pcmret;
 162   int      pcm_storage;
 163   int      pcm_current;
 164   int      pcm_returned;
 165
 166   int  preextrapolate;
 167   int  eofflag;
 168
 169   long lW;
 170   long W;
 171   long nW;
 172   long centerW;
 173
 174   ogg_int64_t granulepos;
 175   ogg_int64_t sequence;
 176
 177   ogg_int64_t glue_bits;
 178   ogg_int64_t time_bits;
 179   ogg_int64_t floor_bits;
 180   ogg_int64_t res_bits;
 181
 182   /* local lookup storage */
 183   void                   *ve; /* envelope lookup */
 184   float                **window[2][2][2]; /* block, leadin, leadout, type */
 185   vorbis_look_transform **transform[2];    /* block, type */
 186   codebook               *fullbooks;
 187   /* backend lookups are tied to the mode, not the backend or naked mapping */
 188   vorbis_look_mapping   **mode;
 189
 190   /* local storage, only used on the encoding side.  This way the
 191      application does not need to worry about freeing some packets'
 192      memory and not others'; packet storage is always tracked.
 193      Cleared next call to a _dsp_ function */
 194   unsigned char *header;
 195   unsigned char *header1;
 196   unsigned char *header2;
 197
 198 } vorbis_dsp_state;
 199
 200 /* vorbis_block is a single block of data to be processed as part of
 201 the analysis/synthesis stream; it belongs to a specific logical
 202 bitstream, but is independant from other vorbis_blocks belonging to
 203 that logical bitstream. *************************************************/
 204
 205 struct alloc_chain{
 206   void *ptr;
 207   struct alloc_chain *next;
 208 };
 209
 210 typedef struct vorbis_block{
 211   /* necessary stream state for linking to the framing abstraction */
 212   float  **pcm;       /* this is a pointer into local storage */
 213   oggpack_buffer opb;
 214
 215   long  lW;
 216   long  W;
 217   long  nW;
 218   int   pcmend;
 219   int   mode;
 220
 221   int eofflag;
 222   ogg_int64_t granulepos;
 223   ogg_int64_t sequence;
 224   vorbis_dsp_state *vd; /* For read-only access of configuration */
 225
 226   /* local storage to avoid remallocing; it's up to the mapping to
 227      structure it */
 228   void               *localstore;
 229   long                localtop;
 230   long                localalloc;
 231   long                totaluse;
 232   struct alloc_chain *reap;
 233
 234   /* bitmetrics for the frame */
 235   long glue_bits;
 236   long time_bits;
 237   long floor_bits;
 238   long res_bits;
 239
 240 } vorbis_block;
 241
 242 #include "vorbis/backends.h"
 243
 244 /* vorbis_info contains all the setup information specific to the
 245    specific compression/decompression mode in progress (eg,
 246    psychoacoustic settings, channel setup, options, codebook
 247    etc). vorbis_info and substructures are in backends.h.
 248 *********************************************************************/
 249
 250 /* the comments are not part of vorbis_info so that vorbis_info can be
 251    static storage */
 252 typedef struct vorbis_comment{
 253   /* unlimited user comment fields.  libvorbis writes 'libvorbis'
 254      whatever vendor is set to in encode */
 255   char **user_comments;
 256   int   *comment_lengths;
 257   int    comments;
 258   char  *vendor;
 259
 260 } vorbis_comment;
 261
 262
 263 /* libvorbis encodes in two abstraction layers; first we perform DSP
 264    and produce a packet (see docs/analysis.txt).  The packet is then
 265    coded into a framed OggSquish bitstream by the second layer (see
 266    docs/framing.txt).  Decode is the reverse process; we sync/frame
 267    the bitstream and extract individual packets, then decode the
 268    packet back into PCM audio.
 269
 270    The extra framing/packetizing is used in streaming formats, such as
 271    files.  Over the net (such as with UDP), the framing and
 272    packetization aren't necessary as they're provided by the transport
 273    and the streaming layer is not used */
 274
 275 /* Vorbis PRIMITIVES: general ***************************************/
 276
 277 extern void     vorbis_info_init(vorbis_info *vi);
 278 extern void     vorbis_info_clear(vorbis_info *vi);
 279 extern void     vorbis_comment_init(vorbis_comment *vc);
 280 extern void     vorbis_comment_add(vorbis_comment *vc, char *comment);
 281 extern void     vorbis_comment_add_tag(vorbis_comment *vc,
 282                                        char *tag, char *contents);
 283 extern char    *vorbis_comment_query(vorbis_comment *vc, char *tag, int count);
 284 extern int      vorbis_comment_query_count(vorbis_comment *vc, char *tag);
 285 extern void     vorbis_comment_clear(vorbis_comment *vc);
 286
 287 extern int      vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb);
 288 extern int      vorbis_block_clear(vorbis_block *vb);
 289 extern void     vorbis_dsp_clear(vorbis_dsp_state *v);
 290
 291 /* Vorbis PRIMITIVES: analysis/DSP layer ****************************/
 292
 293 extern int      vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
 294 extern int      vorbis_analysis_headerout(vorbis_dsp_state *v,
 295                                           vorbis_comment *vc,
 296                                           ogg_packet *op,
 297                                           ogg_packet *op_comm,
 298                                           ogg_packet *op_code);
 299 extern float  **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
 300 extern int      vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
 301 extern int      vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
 302 extern int      vorbis_analysis(vorbis_block *vb,ogg_packet *op);
 303
 304 /* Vorbis PRIMITIVES: synthesis layer *******************************/
 305 extern int      vorbis_synthesis_headerin(vorbis_info *vi,vorbis_comment *vc,
 306                                           ogg_packet *op);
 307
 308 extern int      vorbis_synthesis_init(vorbis_dsp_state *v,vorbis_info *vi);
 309 extern int      vorbis_synthesis(vorbis_block *vb,ogg_packet *op);
 310 extern int      vorbis_synthesis_blockin(vorbis_dsp_state *v,vorbis_block *vb);
 311 extern int      vorbis_synthesis_pcmout(vorbis_dsp_state *v,float ***pcm);
 312 extern int      vorbis_synthesis_read(vorbis_dsp_state *v,int samples);
 313
 314 #ifdef __cplusplus
 315 }
 316 #endif /* __cplusplus */
 317
 318 #endif
 319