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.2 2000/01/12 11:34:37 xiphmont Exp $
  16
  17  ********************************************************************/
  18
  19 #ifndef _vorbis_codec_h_
  20 #define _vorbis_codec_h_
  21
  22 #include <sys/types.h>
  23 #include "vorbis/codebook.h"
  24 #include "vorbis/internal.h"
  25
  26 /* vobis_info contains all the setup information specific to the specific
  27    compression/decompression mode in progress (eg, psychoacoustic settings,
  28    channel setup, options, codebook etc) *********************************/
  29
  30 #define MAX_BARK 27
  31
  32 /* not used yet */
  33 typedef struct vorbis_info_time{
  34 }vorbis_info_time;
  35
  36 typedef struct vorbis_info_floor{
  37   int   order;
  38   long  rate;
  39   long  barkmap;
  40   int   stages;
  41   int  *books;
  42 } vorbis_info_floor;
  43
  44 typedef struct vorbis_info_res{
  45   long  begin;
  46   long  end;
  47
  48   int   stages;
  49   int  *books;
  50 } vorbis_info_res;
  51
  52 typedef struct vorbis_psysettings{
  53   double maskthresh[MAX_BARK];
  54   double lrolldB;
  55   double hrolldB;
  56 } vorbis_psysettings;
  57
  58 typedef struct vorbis_info{
  59   int channels;
  60   long rate;
  61   int version;
  62
  63   /* The below bitrate declarations are *hints*.
  64      Combinations of the three values carry the following implications:
  65
  66      all three set to the same value:
  67        implies a fixed rate bitstream
  68      only nominal set:
  69        implies a VBR stream that averages the nominal bitrate.  No hard
  70        upper/lower limit
  71      upper and or lower set:
  72        implies a VBR bitstream that obeys the bitrate limits. nominal
  73        may also be set to give a nominal rate.
  74      none set:
  75        the coder does not care to speculate.
  76   */
  77
  78   long bitrate_upper;
  79   long bitrate_nominal;
  80   long bitrate_lower;
  81
  82   /* unlimited user comment fields.  libvorbis writes 'libvorbis'
  83      whatever vedor is set to in encode */
  84   char **user_comments;
  85   int    comments;
  86   char  *vendor;
  87
  88   /* short and long block sizes */
  89   int blocksize[2];
  90
  91   /* no mapping so no balance yet */
  92   int channelmapping[2];   /* mapping type: 0 == (independant channel) */
  93
  94   /* time domain setup */
  95   int                timech;
  96   vorbis_info_time  *times[2];
  97
  98   /* mdct domain floor setup */
  99   int                floorch;
 100   vorbis_info_floor *floors[2]; /* [long,short][floorchannel] */
 101
 102   /* mdct domain residue setup */
 103   int                residuech;
 104   vorbis_info_res   *residues[2];
 105
 106   /* Codebook storage for encode and decode.  Encode side is submitted
 107      by the client (and memory must be managed by the client), decode
 108      side is allocated by header_in */
 109   codebook  *booklist;
 110   int        books;
 111
 112   /* Encode-side settings for analysis. different mappings use them
 113      differently. */
 114   vorbis_psysettings *psy;
 115
 116   /* for block long/sort tuning */
 117   int    envelopesa;
 118   double preecho_thresh;
 119   double preecho_clamp;
 120
 121   /* local storage, only used on the encoding size.  This way the
 122      application does not need to worry about freeing some packets'
 123      memory and not others'.  Packet storage is always tracked */
 124   char *header;
 125   char *header1;
 126   char *header2;
 127
 128   int   freeall;     /* codebooks submitted or malloced? */
 129
 130 } vorbis_info;
 131
 132 /* ogg_page is used to encapsulate the data in one Ogg bitstream page *****/
 133
 134 typedef struct {
 135   unsigned char *header;
 136   long header_len;
 137   unsigned char *body;
 138   long body_len;
 139 } ogg_page;
 140
 141 /* ogg_stream_state contains the current encode/decode state of a logical
 142    Ogg bitstream **********************************************************/
 143
 144 typedef struct {
 145   unsigned char   *body_data;    /* bytes from packet bodies */
 146   long    body_storage;          /* storage elements allocated */
 147   long    body_fill;             /* elements stored; fill mark */
 148   long    body_returned;         /* elements of fill returned */
 149
 150
 151   int     *lacing_vals;    /* The values that will go to the segment table */
 152   int64_t *pcm_vals;      /* pcm_pos values for headers. Not compact
 153                              this way, but it is simple coupled to the
 154                              lacing fifo */
 155   long    lacing_storage;
 156   long    lacing_fill;
 157   long    lacing_packet;
 158   long    lacing_returned;
 159
 160   unsigned char    header[282];      /* working space for header encode */
 161   int              header_fill;
 162
 163   int     e_o_s;          /* set when we have buffered the last packet in the
 164                              logical bitstream */
 165   int     b_o_s;          /* set after we've written the initial page
 166                              of a logical bitstream */
 167   long     serialno;
 168   long     pageno;
 169   long     packetno;      /* sequence number for decode; the framing
 170                              knows where there's a hole in the data,
 171                              but we need coupling so that the codec
 172                              (which is in a seperate abstraction
 173                              layer) also knows about the gap */
 174   int64_t   pcmpos;
 175
 176 } ogg_stream_state;
 177
 178 /* ogg_packet is used to encapsulate the data and metadata belonging
 179    to a single raw Ogg/Vorbis packet *************************************/
 180
 181 typedef struct {
 182   unsigned char *packet;
 183   long  bytes;
 184   long  b_o_s;
 185   long  e_o_s;
 186
 187   int64_t  frameno;
 188   long    packetno;       /* sequence number for decode; the framing
 189                              knows where there's a hole in the data,
 190                              but we need coupling so that the codec
 191                              (which is in a seperate abstraction
 192                              layer) also knows about the gap */
 193
 194 } ogg_packet;
 195
 196 typedef struct {
 197   unsigned char *data;
 198   int storage;
 199   int fill;
 200   int returned;
 201
 202   int unsynced;
 203   int headerbytes;
 204   int bodybytes;
 205 } ogg_sync_state;
 206
 207 /* vorbis_dsp_state buffers the current vorbis audio
 208    analysis/synthesis state.  The DSP state belongs to a specific
 209    logical bitstream ****************************************************/
 210
 211 typedef struct vorbis_dsp_state{
 212   int analysisp;
 213   vorbis_info *vi;
 214
 215   double *window[2][2][2]; /* windowsize, leadin, leadout */
 216   envelope_lookup ve;
 217   mdct_lookup vm[2];
 218   lpc_lookup vl[2];
 219   lpc_lookup vbal[2];
 220   psy_lookup vp[2];
 221
 222   double **pcm;
 223   double **pcmret;
 224   int      pcm_storage;
 225   int      pcm_current;
 226   int      pcm_returned;
 227
 228   double  *multipliers;
 229   int      envelope_storage;
 230   int      envelope_current;
 231
 232   int  eofflag;
 233
 234   long lW;
 235   long W;
 236   long nW;
 237   long centerW;
 238
 239   long frameno;
 240   long sequence;
 241
 242   int64_t gluebits;
 243   int64_t time_envelope_bits;
 244   int64_t spectral_envelope_bits;
 245   int64_t spectral_residue_bits;
 246
 247 } vorbis_dsp_state;
 248
 249 /* vorbis_block is a single block of data to be processed as part of
 250 the analysis/synthesis stream; it belongs to a specific logical
 251 bitstream, but is independant from other vorbis_blocks belonging to
 252 that logical bitstream. *************************************************/
 253
 254 typedef struct vorbis_block{
 255   double **pcm;
 256   double **lpc;
 257   double **lsp;
 258   double *amp;
 259   oggpack_buffer opb;
 260
 261   int   pcm_channels;  /* allocated, not used */
 262   int   pcm_storage;   /* allocated, not used */
 263   int   floor_channels;
 264   int   floor_storage;
 265
 266   long  lW;
 267   long  W;
 268   long  nW;
 269   int   pcmend;
 270
 271   int eofflag;
 272   int frameno;
 273   int sequence;
 274   vorbis_dsp_state *vd; /* For read-only access of configuration */
 275
 276   long gluebits;
 277   long time_envelope_bits;
 278   long spectral_envelope_bits;
 279   long spectral_residue_bits;
 280
 281 } vorbis_block;
 282
 283 /* libvorbis encodes in two abstraction layers; first we perform DSP
 284    and produce a packet (see docs/analysis.txt).  The packet is then
 285    coded into a framed OggSquish bitstream by the second layer (see
 286    docs/framing.txt).  Decode is the reverse process; we sync/frame
 287    the bitstream and extract individual packets, then decode the
 288    packet back into PCM audio.
 289
 290    The extra framing/packetizing is used in streaming formats, such as
 291    files.  Over the net (such as with UDP), the framing and
 292    packetization aren't necessary as they're provided by the transport
 293    and the streaming layer is not used */
 294
 295 /* OggSquish BITSREAM PRIMITIVES: encoding **************************/
 296
 297 extern int     ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
 298 extern int     ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
 299
 300 /* OggSquish BITSREAM PRIMITIVES: decoding **************************/
 301
 302 extern int     ogg_sync_init(ogg_sync_state *oy);
 303 extern int     ogg_sync_clear(ogg_sync_state *oy);
 304 extern int     ogg_sync_destroy(ogg_sync_state *oy);
 305 extern int     ogg_sync_reset(ogg_sync_state *oy);
 306
 307 extern char   *ogg_sync_buffer(ogg_sync_state *oy, long size);
 308 extern int     ogg_sync_wrote(ogg_sync_state *oy, long bytes);
 309 extern long    ogg_sync_pageseek(ogg_sync_state *oy,ogg_page *og);
 310 extern int     ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
 311 extern int     ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
 312 extern int     ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
 313
 314 /* OggSquish BITSREAM PRIMITIVES: general ***************************/
 315
 316 extern int     ogg_stream_init(ogg_stream_state *os,int serialno);
 317 extern int     ogg_stream_clear(ogg_stream_state *os);
 318 extern int     ogg_stream_reset(ogg_stream_state *os,long expected_pageno);
 319 extern int     ogg_stream_destroy(ogg_stream_state *os);
 320 extern int     ogg_stream_eof(ogg_stream_state *os);
 321
 322 extern int     ogg_page_version(ogg_page *og);
 323 extern int     ogg_page_continued(ogg_page *og);
 324 extern int     ogg_page_bos(ogg_page *og);
 325 extern int     ogg_page_eos(ogg_page *og);
 326 extern int64_t ogg_page_frameno(ogg_page *og);
 327 extern int     ogg_page_serialno(ogg_page *og);
 328 extern int     ogg_page_pageno(ogg_page *og);
 329
 330 /* Vorbis PRIMITIVES: general ***************************************/
 331
 332 extern void vorbis_dsp_clear(vorbis_dsp_state *v);
 333
 334 extern void vorbis_info_init(vorbis_info *vi);
 335 extern void vorbis_info_clear(vorbis_info *vi);
 336 extern int  vorbis_info_modeset(vorbis_info *vi, int mode);
 337 extern int  vorbis_info_addcomment(vorbis_info *vi, char *comment);
 338 extern int  vorbis_info_headerin(vorbis_info *vi,ogg_packet *op);
 339 extern int  vorbis_info_headerout(vorbis_info *vi,
 340                                   ogg_packet *op,
 341                                   ogg_packet *op_comm,
 342                                   ogg_packet *op_code);
 343
 344 extern int  vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb);
 345 extern int  vorbis_block_clear(vorbis_block *vb);
 346
 347 /* Vorbis PRIMITIVES: analysis/DSP layer ****************************/
 348 extern int      vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
 349
 350 extern double **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
 351 extern int      vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
 352 extern int      vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
 353 extern int      vorbis_analysis(vorbis_block *vb,ogg_packet *op);
 354
 355 /* Vorbis PRIMITIVES: synthesis layer *******************************/
 356 extern int vorbis_synthesis_init(vorbis_dsp_state *v,vorbis_info *vi);
 357
 358 extern int vorbis_synthesis(vorbis_block *vb,ogg_packet *op);
 359 extern int vorbis_synthesis_blockin(vorbis_dsp_state *v,vorbis_block *vb);
 360 extern int vorbis_synthesis_pcmout(vorbis_dsp_state *v,double ***pcm);
 361 extern int vorbis_synthesis_read(vorbis_dsp_state *v,int samples);
 362
 363 #endif
 364