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.8 2000/02/06 13:39:37 xiphmont Exp $
  16
  17  ********************************************************************/
  18
  19 #ifndef _vorbis_codec_h_
  20 #define _vorbis_codec_h_
  21
  22 #define MAX_BARK 27
  23
  24 #include <sys/types.h>
  25 #include "vorbis/codebook.h"
  26 #include "vorbis/internal.h"
  27
  28 typedef void vorbis_look_transform;
  29 typedef void vorbis_info_time;
  30 typedef void vorbis_look_time;
  31 typedef void vorbis_info_floor;
  32 typedef void vorbis_look_floor;
  33 typedef void vorbis_info_residue;
  34 typedef void vorbis_look_residue;
  35 typedef void vorbis_info_mapping;
  36 typedef void vorbis_look_mapping;
  37
  38 /* mode ************************************************************/
  39 typedef struct {
  40   int blockflag;
  41   int windowtype;
  42   int transformtype;
  43   int mapping;
  44 } vorbis_info_mode;
  45
  46 /* psychoacoustic setup ********************************************/
  47 typedef struct vorbis_info_psy{
  48   double maskthresh[MAX_BARK];
  49   double lrolldB;
  50   double hrolldB;
  51
  52   /* quantization information to match the residue encoding */
  53   /*int    blocklen;    comes from res info */
  54   /*int    elements[4]; comes from res info */
  55   double cutoffs[4];
  56   int    quantval[4];
  57
  58 } vorbis_info_psy;
  59
  60 /* vorbis_info contains all the setup information specific to the
  61    specific compression/decompression mode in progress (eg,
  62    psychoacoustic settings, channel setup, options, codebook
  63    etc).
  64 *********************************************************************/
  65
  66 typedef struct vorbis_info{
  67   int version;
  68   int channels;
  69   long rate;
  70
  71   /* The below bitrate declarations are *hints*.
  72      Combinations of the three values carry the following implications:
  73
  74      all three set to the same value:
  75        implies a fixed rate bitstream
  76      only nominal set:
  77        implies a VBR stream that averages the nominal bitrate.  No hard
  78        upper/lower limit
  79      upper and or lower set:
  80        implies a VBR bitstream that obeys the bitrate limits. nominal
  81        may also be set to give a nominal rate.
  82      none set:
  83        the coder does not care to speculate.
  84   */
  85
  86   long bitrate_upper;
  87   long bitrate_nominal;
  88   long bitrate_lower;
  89
  90   /* Vorbis supports only short and long blocks, but allows the
  91      encoder to choose the sizes */
  92
  93   long blocksizes[2];
  94
  95   /* modes are the primary means of supporting on-the-fly different
  96      blocksizes, different channel mappings (LR or mid-side),
  97      different residue backends, etc.  Each mode consists of a
  98      blocksize flag and a mapping (along with the mapping setup */
  99
 100   int        modes;
 101   int        maps;
 102   int        times;
 103   int        floors;
 104   int        residues;
 105   int        books;
 106   int        psys;     /* encode only */
 107
 108   vorbis_info_mode    *mode_param[64];
 109   int                  map_type[64];
 110   vorbis_info_mapping *map_param[64];
 111   int                  time_type[64];
 112   vorbis_info_time    *time_param[64];
 113   int                  floor_type[64];
 114   vorbis_info_floor   *floor_param[64];
 115   int                  residue_type[64];
 116   vorbis_info_residue *residue_param[64];
 117   static_codebook     *book_param[256];
 118   vorbis_info_psy     *psy_param[64]; /* encode only */
 119
 120   /* for block long/sort tuning; encode only */
 121   int        envelopesa;
 122   double     preecho_thresh;
 123   double     preecho_clamp;
 124
 125 } vorbis_info;
 126
 127 /* ogg_page is used to encapsulate the data in one Ogg bitstream page *****/
 128
 129 typedef struct {
 130   unsigned char *header;
 131   long header_len;
 132   unsigned char *body;
 133   long body_len;
 134 } ogg_page;
 135
 136 /* ogg_stream_state contains the current encode/decode state of a logical
 137    Ogg bitstream **********************************************************/
 138
 139 typedef struct {
 140   unsigned char   *body_data;    /* bytes from packet bodies */
 141   long    body_storage;          /* storage elements allocated */
 142   long    body_fill;             /* elements stored; fill mark */
 143   long    body_returned;         /* elements of fill returned */
 144
 145
 146   int     *lacing_vals;    /* The values that will go to the segment table */
 147   int64_t *pcm_vals;      /* pcm_pos values for headers. Not compact
 148                              this way, but it is simple coupled to the
 149                              lacing fifo */
 150   long    lacing_storage;
 151   long    lacing_fill;
 152   long    lacing_packet;
 153   long    lacing_returned;
 154
 155   unsigned char    header[282];      /* working space for header encode */
 156   int              header_fill;
 157
 158   int     e_o_s;          /* set when we have buffered the last packet in the
 159                              logical bitstream */
 160   int     b_o_s;          /* set after we've written the initial page
 161                              of a logical bitstream */
 162   long     serialno;
 163   long     pageno;
 164   long     packetno;      /* sequence number for decode; the framing
 165                              knows where there's a hole in the data,
 166                              but we need coupling so that the codec
 167                              (which is in a seperate abstraction
 168                              layer) also knows about the gap */
 169   int64_t   pcmpos;
 170
 171 } ogg_stream_state;
 172
 173 /* ogg_packet is used to encapsulate the data and metadata belonging
 174    to a single raw Ogg/Vorbis packet *************************************/
 175
 176 typedef struct {
 177   unsigned char *packet;
 178   long  bytes;
 179   long  b_o_s;
 180   long  e_o_s;
 181
 182   int64_t  frameno;
 183   long    packetno;       /* sequence number for decode; the framing
 184                              knows where there's a hole in the data,
 185                              but we need coupling so that the codec
 186                              (which is in a seperate abstraction
 187                              layer) also knows about the gap */
 188
 189 } ogg_packet;
 190
 191 typedef struct {
 192   unsigned char *data;
 193   int storage;
 194   int fill;
 195   int returned;
 196
 197   int unsynced;
 198   int headerbytes;
 199   int bodybytes;
 200 } ogg_sync_state;
 201
 202 /* vorbis_dsp_state buffers the current vorbis audio
 203    analysis/synthesis state.  The DSP state belongs to a specific
 204    logical bitstream ****************************************************/
 205 typedef struct vorbis_dsp_state{
 206   int analysisp;
 207   vorbis_info *vi;
 208   int    modebits;
 209
 210   double **pcm;
 211   double **pcmret;
 212   int      pcm_storage;
 213   int      pcm_current;
 214   int      pcm_returned;
 215
 216   double  *multipliers;
 217   int      envelope_storage;
 218   int      envelope_current;
 219
 220   int  eofflag;
 221
 222   long lW;
 223   long W;
 224   long nW;
 225   long centerW;
 226
 227   long frameno;
 228   long sequence;
 229
 230   int64_t glue_bits;
 231   int64_t time_bits;
 232   int64_t floor_bits;
 233   int64_t res_bits;
 234
 235   /* local lookup storage */
 236   envelope_lookup         ve;
 237   double                **window[2][2][2]; /* block, leadin, leadout, type */
 238   vorbis_look_transform **transform[2];    /* block, type */
 239   codebook               *fullbooks;
 240   /* backend lookups are tied to the mode, not the backend or naked mapping */
 241   vorbis_look_mapping   **mode;
 242
 243   /* local storage, only used on the encoding side.  This way the
 244      application does not need to worry about freeing some packets'
 245      memory and not others'; packet storage is always tracked.
 246      Cleared next call to a _dsp_ function */
 247   char *header;
 248   char *header1;
 249   char *header2;
 250
 251 } vorbis_dsp_state;
 252
 253 /* vorbis_block is a single block of data to be processed as part of
 254 the analysis/synthesis stream; it belongs to a specific logical
 255 bitstream, but is independant from other vorbis_blocks belonging to
 256 that logical bitstream. *************************************************/
 257
 258 struct alloc_chain{
 259   void *ptr;
 260   struct alloc_chain *next;
 261 };
 262
 263 typedef struct vorbis_block{
 264   /* necessary stream state for linking to the framing abstraction */
 265   double  **pcm;       /* this is a pointer into local storage */
 266   oggpack_buffer opb;
 267
 268   long  lW;
 269   long  W;
 270   long  nW;
 271   int   pcmend;
 272
 273   int eofflag;
 274   int frameno;
 275   int sequence;
 276   vorbis_dsp_state *vd; /* For read-only access of configuration */
 277
 278   /* local storage to avoid remallocing; it's up to the mapping to
 279      structure it */
 280   void               *localstore;
 281   long                localtop;
 282   long                localalloc;
 283   long                totaluse;
 284   struct alloc_chain *reap;
 285
 286   /* bitmetrics for the frame */
 287   long glue_bits;
 288   long time_bits;
 289   long floor_bits;
 290   long res_bits;
 291
 292 } vorbis_block;
 293
 294 #include "vorbis/backends.h"
 295
 296 /* vorbis_info contains all the setup information specific to the
 297    specific compression/decompression mode in progress (eg,
 298    psychoacoustic settings, channel setup, options, codebook
 299    etc). vorbis_info and substructures are in backends.h.
 300 *********************************************************************/
 301
 302 /* the comments are not part of vorbis_info so that vorbis_info can be
 303    static storage */
 304 typedef struct vorbis_comment{
 305   /* unlimited user comment fields.  libvorbis writes 'libvorbis'
 306      whatever vendor is set to in encode */
 307   char **user_comments;
 308   int    comments;
 309   char  *vendor;
 310
 311 } vorbis_comment;
 312
 313
 314 /* libvorbis encodes in two abstraction layers; first we perform DSP
 315    and produce a packet (see docs/analysis.txt).  The packet is then
 316    coded into a framed OggSquish bitstream by the second layer (see
 317    docs/framing.txt).  Decode is the reverse process; we sync/frame
 318    the bitstream and extract individual packets, then decode the
 319    packet back into PCM audio.
 320
 321    The extra framing/packetizing is used in streaming formats, such as
 322    files.  Over the net (such as with UDP), the framing and
 323    packetization aren't necessary as they're provided by the transport
 324    and the streaming layer is not used */
 325
 326 /* OggSquish BITSREAM PRIMITIVES: encoding **************************/
 327
 328 extern int      ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
 329 extern int      ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
 330
 331 /* OggSquish BITSREAM PRIMITIVES: decoding **************************/
 332
 333 extern int      ogg_sync_init(ogg_sync_state *oy);
 334 extern int      ogg_sync_clear(ogg_sync_state *oy);
 335 extern int      ogg_sync_destroy(ogg_sync_state *oy);
 336 extern int      ogg_sync_reset(ogg_sync_state *oy);
 337
 338 extern char    *ogg_sync_buffer(ogg_sync_state *oy, long size);
 339 extern int      ogg_sync_wrote(ogg_sync_state *oy, long bytes);
 340 extern long     ogg_sync_pageseek(ogg_sync_state *oy,ogg_page *og);
 341 extern int      ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
 342 extern int      ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
 343 extern int      ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
 344
 345 /* OggSquish BITSREAM PRIMITIVES: general ***************************/
 346
 347 extern int      ogg_stream_init(ogg_stream_state *os,int serialno);
 348 extern int      ogg_stream_clear(ogg_stream_state *os);
 349 extern int      ogg_stream_reset(ogg_stream_state *os,long expected_pageno);
 350 extern int      ogg_stream_destroy(ogg_stream_state *os);
 351 extern int      ogg_stream_eof(ogg_stream_state *os);
 352
 353 extern int      ogg_page_version(ogg_page *og);
 354 extern int      ogg_page_continued(ogg_page *og);
 355 extern int      ogg_page_bos(ogg_page *og);
 356 extern int      ogg_page_eos(ogg_page *og);
 357 extern int64_t  ogg_page_frameno(ogg_page *og);
 358 extern int      ogg_page_serialno(ogg_page *og);
 359 extern int      ogg_page_pageno(ogg_page *og);
 360
 361 /* Vorbis PRIMITIVES: general ***************************************/
 362
 363 extern void     vorbis_info_init(vorbis_info *vi);
 364 extern void     vorbis_info_clear(vorbis_info *vi);
 365 extern void     vorbis_comment_init(vorbis_comment *vc);
 366 extern void     vorbis_comment_add(vorbis_comment *vc, char *comment);
 367 extern void     vorbis_comment_clear(vorbis_comment *vc);
 368
 369 extern int      vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb);
 370 extern int      vorbis_block_clear(vorbis_block *vb);
 371 extern void     vorbis_dsp_clear(vorbis_dsp_state *v);
 372
 373 /* Vorbis PRIMITIVES: analysis/DSP layer ****************************/
 374
 375 extern int      vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
 376 extern int      vorbis_analysis_headerout(vorbis_dsp_state *v,
 377                                           vorbis_comment *vc,
 378                                           ogg_packet *op,
 379                                           ogg_packet *op_comm,
 380                                           ogg_packet *op_code);
 381 extern double **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
 382 extern int      vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
 383 extern int      vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
 384 extern int      vorbis_analysis(vorbis_block *vb,ogg_packet *op);
 385
 386 /* Vorbis PRIMITIVES: synthesis layer *******************************/
 387 extern int      vorbis_synthesis_headerin(vorbis_info *vi,vorbis_comment *vc,
 388                                           ogg_packet *op);
 389
 390 extern int      vorbis_synthesis_init(vorbis_dsp_state *v,vorbis_info *vi);
 391 extern int      vorbis_synthesis(vorbis_block *vb,ogg_packet *op);
 392 extern int      vorbis_synthesis_blockin(vorbis_dsp_state *v,vorbis_block *vb);
 393 extern int      vorbis_synthesis_pcmout(vorbis_dsp_state *v,double ***pcm);
 394 extern int      vorbis_synthesis_read(vorbis_dsp_state *v,int samples);
 395
 396 #endif
 397