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