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.12 2000/04/10 00:12:14 xiphmont 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
  28 #define MAX_BARK 27
  29
  30 #include <sys/types.h>
  31 #include "vorbis/codebook.h"
  32 #include "vorbis/internal.h"
  33
  34 typedef void vorbis_look_transform;
  35 typedef void vorbis_info_time;
  36 typedef void vorbis_look_time;
  37 typedef void vorbis_info_floor;
  38 typedef void vorbis_look_floor;
  39 typedef void vorbis_info_residue;
  40 typedef void vorbis_look_residue;
  41 typedef void vorbis_info_mapping;
  42 typedef void vorbis_look_mapping;
  43
  44 /* mode ************************************************************/
  45 typedef struct {
  46   int blockflag;
  47   int windowtype;
  48   int transformtype;
  49   int mapping;
  50 } vorbis_info_mode;
  51
  52 /* psychoacoustic setup ********************************************/
  53 typedef struct vorbis_info_psy{
  54   double maskthresh[MAX_BARK];
  55   double lrolldB;
  56   double hrolldB;
  57 } vorbis_info_psy;
  58
  59 /* vorbis_info contains all the setup information specific to the
  60    specific compression/decompression mode in progress (eg,
  61    psychoacoustic settings, channel setup, options, codebook
  62    etc).
  63 *********************************************************************/
  64
  65 typedef struct vorbis_info{
  66   int version;
  67   int channels;
  68   long rate;
  69
  70   /* The below bitrate declarations are *hints*.
  71      Combinations of the three values carry the following implications:
  72
  73      all three set to the same value:
  74        implies a fixed rate bitstream
  75      only nominal set:
  76        implies a VBR stream that averages the nominal bitrate.  No hard
  77        upper/lower limit
  78      upper and or lower set:
  79        implies a VBR bitstream that obeys the bitrate limits. nominal
  80        may also be set to give a nominal rate.
  81      none set:
  82        the coder does not care to speculate.
  83   */
  84
  85   long bitrate_upper;
  86   long bitrate_nominal;
  87   long bitrate_lower;
  88
  89   /* Vorbis supports only short and long blocks, but allows the
  90      encoder to choose the sizes */
  91
  92   long blocksizes[2];
  93
  94   /* modes are the primary means of supporting on-the-fly different
  95      blocksizes, different channel mappings (LR or mid-side),
  96      different residue backends, etc.  Each mode consists of a
  97      blocksize flag and a mapping (along with the mapping setup */
  98
  99   int        modes;
 100   int        maps;
 101   int        times;
 102   int        floors;
 103   int        residues;
 104   int        books;
 105   int        psys;     /* encode only */
 106
 107   vorbis_info_mode    *mode_param[64];
 108   int                  map_type[64];
 109   vorbis_info_mapping *map_param[64];
 110   int                  time_type[64];
 111   vorbis_info_time    *time_param[64];
 112   int                  floor_type[64];
 113   vorbis_info_floor   *floor_param[64];
 114   int                  residue_type[64];
 115   vorbis_info_residue *residue_param[64];
 116   static_codebook     *book_param[256];
 117   vorbis_info_psy     *psy_param[64]; /* encode only */
 118
 119   /* for block long/sort tuning; encode only */
 120   int        envelopesa;
 121   double     preecho_thresh;
 122   double     preecho_clamp;
 123
 124 } vorbis_info;
 125
 126 /* ogg_page is used to encapsulate the data in one Ogg bitstream page *****/
 127
 128 typedef struct {
 129   unsigned char *header;
 130   long header_len;
 131   unsigned char *body;
 132   long body_len;
 133 } ogg_page;
 134
 135 /* ogg_stream_state contains the current encode/decode state of a logical
 136    Ogg bitstream **********************************************************/
 137
 138 typedef struct {
 139   unsigned char   *body_data;    /* bytes from packet bodies */
 140   long    body_storage;          /* storage elements allocated */
 141   long    body_fill;             /* elements stored; fill mark */
 142   long    body_returned;         /* elements of fill returned */
 143
 144
 145   int     *lacing_vals;    /* The values that will go to the segment table */
 146   int64_t *pcm_vals;      /* pcm_pos values for headers. Not compact
 147                              this way, but it is simple coupled to the
 148                              lacing fifo */
 149   long    lacing_storage;
 150   long    lacing_fill;
 151   long    lacing_packet;
 152   long    lacing_returned;
 153
 154   unsigned char    header[282];      /* working space for header encode */
 155   int              header_fill;
 156
 157   int     e_o_s;          /* set when we have buffered the last packet in the
 158                              logical bitstream */
 159   int     b_o_s;          /* set after we've written the initial page
 160                              of a logical bitstream */
 161   long     serialno;
 162   long     pageno;
 163   long     packetno;      /* sequence number for decode; the framing
 164                              knows where there's a hole in the data,
 165                              but we need coupling so that the codec
 166                              (which is in a seperate abstraction
 167                              layer) also knows about the gap */
 168   int64_t   pcmpos;
 169
 170 } ogg_stream_state;
 171
 172 /* ogg_packet is used to encapsulate the data and metadata belonging
 173    to a single raw Ogg/Vorbis packet *************************************/
 174
 175 typedef struct {
 176   unsigned char *packet;
 177   long  bytes;
 178   long  b_o_s;
 179   long  e_o_s;
 180
 181   int64_t  frameno;
 182   long    packetno;       /* sequence number for decode; the framing
 183                              knows where there's a hole in the data,
 184                              but we need coupling so that the codec
 185                              (which is in a seperate abstraction
 186                              layer) also knows about the gap */
 187
 188 } ogg_packet;
 189
 190 typedef struct {
 191   unsigned char *data;
 192   int storage;
 193   int fill;
 194   int returned;
 195
 196   int unsynced;
 197   int headerbytes;
 198   int bodybytes;
 199 } ogg_sync_state;
 200
 201 /* vorbis_dsp_state buffers the current vorbis audio
 202    analysis/synthesis state.  The DSP state belongs to a specific
 203    logical bitstream ****************************************************/
 204 typedef struct vorbis_dsp_state{
 205   int analysisp;
 206   vorbis_info *vi;
 207   int    modebits;
 208
 209   double **pcm;
 210   double **pcmret;
 211   int      pcm_storage;
 212   int      pcm_current;
 213   int      pcm_returned;
 214
 215   double  *multipliers;
 216   int      envelope_storage;
 217   int      envelope_current;
 218
 219   int  eofflag;
 220
 221   long lW;
 222   long W;
 223   long nW;
 224   long centerW;
 225
 226   long frameno;
 227   long sequence;
 228
 229   int64_t glue_bits;
 230   int64_t time_bits;
 231   int64_t floor_bits;
 232   int64_t res_bits;
 233
 234   /* local lookup storage */
 235   envelope_lookup         ve;
 236   double                **window[2][2][2]; /* block, leadin, leadout, type */
 237   vorbis_look_transform **transform[2];    /* block, type */
 238   codebook               *fullbooks;
 239   /* backend lookups are tied to the mode, not the backend or naked mapping */
 240   vorbis_look_mapping   **mode;
 241
 242   /* local storage, only used on the encoding side.  This way the
 243      application does not need to worry about freeing some packets'
 244      memory and not others'; packet storage is always tracked.
 245      Cleared next call to a _dsp_ function */
 246   char *header;
 247   char *header1;
 248   char *header2;
 249
 250 } vorbis_dsp_state;
 251
 252 /* vorbis_block is a single block of data to be processed as part of
 253 the analysis/synthesis stream; it belongs to a specific logical
 254 bitstream, but is independant from other vorbis_blocks belonging to
 255 that logical bitstream. *************************************************/
 256
 257 struct alloc_chain{
 258   void *ptr;
 259   struct alloc_chain *next;
 260 };
 261
 262 typedef struct vorbis_block{
 263   /* necessary stream state for linking to the framing abstraction */
 264   double  **pcm;       /* this is a pointer into local storage */
 265   oggpack_buffer opb;
 266
 267   long  lW;
 268   long  W;
 269   long  nW;
 270   int   pcmend;
 271   int   mode;
 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);
 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
 397 #ifdef __cplusplus
 398 }
 399 #endif /* __cplusplus */
 400
 401
 402 #endif
 403