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