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.9 2000/02/12 08:33:02 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   int   mode;
 273
 274   int eofflag;
 275   int frameno;
 276   int sequence;
 277   vorbis_dsp_state *vd; /* For read-only access of configuration */
 278
 279   /* local storage to avoid remallocing; it's up to the mapping to
 280      structure it */
 281   void               *localstore;
 282   long                localtop;
 283   long                localalloc;
 284   long                totaluse;
 285   struct alloc_chain *reap;
 286
 287   /* bitmetrics for the frame */
 288   long glue_bits;
 289   long time_bits;
 290   long floor_bits;
 291   long res_bits;
 292
 293 } vorbis_block;
 294
 295 #include "vorbis/backends.h"
 296
 297 /* vorbis_info contains all the setup information specific to the
 298    specific compression/decompression mode in progress (eg,
 299    psychoacoustic settings, channel setup, options, codebook
 300    etc). vorbis_info and substructures are in backends.h.
 301 *********************************************************************/
 302
 303 /* the comments are not part of vorbis_info so that vorbis_info can be
 304    static storage */
 305 typedef struct vorbis_comment{
 306   /* unlimited user comment fields.  libvorbis writes 'libvorbis'
 307      whatever vendor is set to in encode */
 308   char **user_comments;
 309   int    comments;
 310   char  *vendor;
 311
 312 } vorbis_comment;
 313
 314
 315 /* libvorbis encodes in two abstraction layers; first we perform DSP
 316    and produce a packet (see docs/analysis.txt).  The packet is then
 317    coded into a framed OggSquish bitstream by the second layer (see
 318    docs/framing.txt).  Decode is the reverse process; we sync/frame
 319    the bitstream and extract individual packets, then decode the
 320    packet back into PCM audio.
 321
 322    The extra framing/packetizing is used in streaming formats, such as
 323    files.  Over the net (such as with UDP), the framing and
 324    packetization aren't necessary as they're provided by the transport
 325    and the streaming layer is not used */
 326
 327 /* OggSquish BITSREAM PRIMITIVES: encoding **************************/
 328
 329 extern int      ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
 330 extern int      ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
 331
 332 /* OggSquish BITSREAM PRIMITIVES: decoding **************************/
 333
 334 extern int      ogg_sync_init(ogg_sync_state *oy);
 335 extern int      ogg_sync_clear(ogg_sync_state *oy);
 336 extern int      ogg_sync_destroy(ogg_sync_state *oy);
 337 extern int      ogg_sync_reset(ogg_sync_state *oy);
 338
 339 extern char    *ogg_sync_buffer(ogg_sync_state *oy, long size);
 340 extern int      ogg_sync_wrote(ogg_sync_state *oy, long bytes);
 341 extern long     ogg_sync_pageseek(ogg_sync_state *oy,ogg_page *og);
 342 extern int      ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
 343 extern int      ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
 344 extern int      ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
 345
 346 /* OggSquish BITSREAM PRIMITIVES: general ***************************/
 347
 348 extern int      ogg_stream_init(ogg_stream_state *os,int serialno);
 349 extern int      ogg_stream_clear(ogg_stream_state *os);
 350 extern int      ogg_stream_reset(ogg_stream_state *os,long expected_pageno);
 351 extern int      ogg_stream_destroy(ogg_stream_state *os);
 352 extern int      ogg_stream_eof(ogg_stream_state *os);
 353
 354 extern int      ogg_page_version(ogg_page *og);
 355 extern int      ogg_page_continued(ogg_page *og);
 356 extern int      ogg_page_bos(ogg_page *og);
 357 extern int      ogg_page_eos(ogg_page *og);
 358 extern int64_t  ogg_page_frameno(ogg_page *og);
 359 extern int      ogg_page_serialno(ogg_page *og);
 360 extern int      ogg_page_pageno(ogg_page *og);
 361
 362 /* Vorbis PRIMITIVES: general ***************************************/
 363
 364 extern void     vorbis_info_init(vorbis_info *vi);
 365 extern void     vorbis_info_clear(vorbis_info *vi);
 366 extern void     vorbis_comment_init(vorbis_comment *vc);
 367 extern void     vorbis_comment_add(vorbis_comment *vc, char *comment);
 368 extern void     vorbis_comment_clear(vorbis_comment *vc);
 369
 370 extern int      vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb);
 371 extern int      vorbis_block_clear(vorbis_block *vb);
 372 extern void     vorbis_dsp_clear(vorbis_dsp_state *v);
 373
 374 /* Vorbis PRIMITIVES: analysis/DSP layer ****************************/
 375
 376 extern int      vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
 377 extern int      vorbis_analysis_headerout(vorbis_dsp_state *v,
 378                                           vorbis_comment *vc,
 379                                           ogg_packet *op,
 380                                           ogg_packet *op_comm,
 381                                           ogg_packet *op_code);
 382 extern double **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
 383 extern int      vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
 384 extern int      vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
 385 extern int      vorbis_analysis(vorbis_block *vb,ogg_packet *op);
 386
 387 /* Vorbis PRIMITIVES: synthesis layer *******************************/
 388 extern int      vorbis_synthesis_headerin(vorbis_info *vi,vorbis_comment *vc,
 389                                           ogg_packet *op);
 390
 391 extern int      vorbis_synthesis_init(vorbis_dsp_state *v,vorbis_info *vi);
 392 extern int      vorbis_synthesis(vorbis_block *vb,ogg_packet *op);
 393 extern int      vorbis_synthesis_blockin(vorbis_dsp_state *v,vorbis_block *vb);
 394 extern int      vorbis_synthesis_pcmout(vorbis_dsp_state *v,double ***pcm);
 395 extern int      vorbis_synthesis_read(vorbis_dsp_state *v,int samples);
 396
 397 #endif
 398