1 /********************************************************************
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. *
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/ *
12 ********************************************************************
14 function: libvorbis codec headers
15 last mod: $Id: codec.h,v 1.29 2000/08/30 07:09:46 xiphmont Exp $
17 ********************************************************************/
19 #ifndef _vorbis_codec_h_
20 #define _vorbis_codec_h_
25 #endif /* __cplusplus */
30 #include "vorbis/codebook.h"
31 #include "vorbis/internal.h"
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;
44 /* mode ************************************************************/
52 /* psychoacoustic setup ********************************************/
55 typedef struct vorbis_info_psy{
61 double noisecull_barkwidth;
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 */
71 double toneatt[P_BANDS][P_LEVELS];
74 double peakatt[P_BANDS][P_LEVELS];
77 double noiseatt[P_BANDS][P_LEVELS];
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
90 *********************************************************************/
92 typedef struct vorbis_info{
97 /* The below bitrate declarations are *hints*.
98 Combinations of the three values carry the following implications:
100 all three set to the same value:
101 implies a fixed rate bitstream
103 implies a VBR stream that averages the nominal bitrate. No hard
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.
109 the coder does not care to speculate.
113 long bitrate_nominal;
116 /* Vorbis supports only short and long blocks, but allows the
117 encoder to choose the sizes */
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 */
132 int psys; /* encode only */
134 vorbis_info_mode *mode_param[64];
136 vorbis_info_mapping *map_param[64];
138 vorbis_info_time *time_param[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 */
146 /* for block long/sort tuning; encode only */
148 double preecho_thresh;
149 double preecho_clamp;
150 double preecho_minenergy;
153 /* ogg_page is used to encapsulate the data in one Ogg bitstream page *****/
156 unsigned char *header;
162 /* ogg_stream_state contains the current encode/decode state of a logical
163 Ogg bitstream **********************************************************/
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 */
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
179 long lacing_returned;
181 unsigned char header[282]; /* working space for header encode */
184 int e_o_s; /* set when we have buffered the last packet in the
186 int b_o_s; /* set after we've written the initial page
187 of a logical bitstream */
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 */
199 /* ogg_packet is used to encapsulate the data and metadata belonging
200 to a single raw Ogg/Vorbis packet *************************************/
203 unsigned char *packet;
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 */
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{
251 ogg_int64_t sequence;
253 ogg_int64_t glue_bits;
254 ogg_int64_t time_bits;
255 ogg_int64_t floor_bits;
256 ogg_int64_t res_bits;
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 */
263 /* backend lookups are tied to the mode, not the backend or naked mapping */
264 vorbis_look_mapping **mode;
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;
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. *************************************************/
283 struct alloc_chain *next;
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 */
299 ogg_int64_t sequence;
300 vorbis_dsp_state *vd; /* For read-only access of configuration */
302 /* local storage to avoid remallocing; it's up to the mapping to
308 struct alloc_chain *reap;
310 /* bitmetrics for the frame */
318 #include "vorbis/backends.h"
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 *********************************************************************/
326 /* the comments are not part of vorbis_info so that vorbis_info can be
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;
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.
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 */
351 /* OggSquish BITSREAM PRIMITIVES: encoding **************************/
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);
357 /* OggSquish BITSREAM PRIMITIVES: decoding **************************/
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);
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);
371 /* OggSquish BITSREAM PRIMITIVES: general ***************************/
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);
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);
387 /* Vorbis PRIMITIVES: general ***************************************/
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);
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);
403 /* Vorbis PRIMITIVES: analysis/DSP layer ****************************/
405 extern int vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
406 extern int vorbis_analysis_headerout(vorbis_dsp_state *v,
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);
416 /* Vorbis PRIMITIVES: synthesis layer *******************************/
417 extern int vorbis_synthesis_headerin(vorbis_info *vi,vorbis_comment *vc,
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);
428 #endif /* __cplusplus */