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