home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / Sound / LAME / src / lame.h < prev    next >
C/C++ Source or Header  |  2000-08-06  |  14KB  |  404 lines
  1. /*
  2.  *    Interface to MP3 LAME encoding engine
  3.  *
  4.  *    Copyright (c) 1999 Mark Taylor
  5.  *
  6.  * This program is free software; you can redistribute it and/or modify
  7.  * it under the terms of the GNU General Public License as published by
  8.  * the Free Software Foundation; either version 2, or (at your option)
  9.  * any later version.
  10.  *
  11.  * This program is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; see the file COPYING.  If not, write to
  18.  * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  19.  */
  20. #ifndef LAME_H_INCLUDE
  21. #define LAME_H_INCLUDE
  22. #include <stdio.h>
  23. #if defined(__cplusplus)
  24. extern "C" {
  25. #endif
  26.  
  27.  
  28.  
  29. /* maximum size of mp3buffer needed if you encode at most 1152 samples for
  30.    each call to lame_encode_buffer.  see lame_encode_buffer() below  
  31.    (LAME_MAXMP3BUFFER is now obsolete)  */
  32. #define LAME_MAXMP3BUFFER 16384
  33.  
  34.  
  35. typedef enum sound_file_format_e {
  36.   sf_unknown, sf_wave, sf_aiff, sf_mp3, sf_raw, sf_ogg 
  37. } sound_file_format;
  38.  
  39.  
  40. typedef enum vbr_mode_e {
  41.   vbr_off=0,
  42.   vbr_mt=1,
  43.   vbr_rh=2,
  44.   vbr_abr=3,
  45.   vbr_default=vbr_rh  /* change this to change the default VBR mode of LAME */ 
  46. } vbr_mode;
  47.  
  48.  
  49. struct id3tag_spec
  50. {
  51.     /* private data members */
  52.     int flags;
  53.     const char *title;
  54.     const char *artist;
  55.     const char *album;
  56.     int year;
  57.     const char *comment;
  58.     int track;
  59.     int genre;
  60. };
  61.  
  62.  
  63.  
  64.  
  65. /***********************************************************************
  66. *
  67. *  Control Parameters set by User
  68. *
  69. *  substantiated by calling program
  70. *
  71. *  Initilized and default values set by lame_init(&gf)
  72. *
  73. *
  74. ***********************************************************************/
  75. typedef struct  {
  76.   /* input file description */
  77.   unsigned long num_samples;  /* number of samples. default=2^32-1    */
  78.   int num_channels;           /* input number of channels. default=2  */
  79.   int in_samplerate;          /* input_samp_rate. default=44.1kHz     */
  80.   int out_samplerate;         /* output_samp_rate. (usually determined automatically)   */ 
  81.  
  82.   /* general control params */
  83.   int gtkflag;                /* run frame analyzer?       */
  84.   int bWriteVbrTag;           /* add Xing VBR tag?         */
  85.   int disable_waveheader;     /* disable writing of .wav header, when *decoding* */
  86.   int decode_only;            /* use lame/mpglib to convert mp3 to wav */
  87.   int ogg;                    /* encode to Vorbis .ogg file */
  88.  
  89.   int quality;                /* quality setting 0=best,  9=worst  */
  90.   int silent;                 /* disable some status output */
  91.   int brhist_disp;            /* enable VBR bitrate histogram display */
  92.   int mode;                       /* 0,1,2,3 stereo,jstereo,dual channel,mono */
  93.   int mode_fixed;                 /* use specified the mode, do not use lame's opinion of the best mode */
  94.   int force_ms;                   /* force M/S mode.  requires mode=1 */
  95.   int brate;                      /* bitrate */
  96.   float compression_ratio;          /* user specified compression ratio, instead of brate */
  97.   int free_format;                /* use free format? */
  98.  
  99.   /* frame params */
  100.   int copyright;                  /* mark as copyright. default=0 */
  101.   int original;                   /* mark as original. default=1 */
  102.   int error_protection;           /* use 2 bytes per frame for a CRC checksum. default=0*/
  103.   int padding_type;               /* 0=no padding, 1=always pad, 2=adjust padding */
  104.   int extension;                  /* the MP3 'private extension' bit.  meaningless */
  105.   int strict_ISO;                 /* enforce ISO spec as much as possible */
  106.  
  107.   /* quantization/noise shaping */
  108.   int disable_reservoir;          /* use bit reservoir? */
  109.   int experimentalX;            
  110.   int experimentalY;
  111.   int experimentalZ;
  112.   int exp_nspsytune;
  113.  
  114.   /* VBR control */
  115.   vbr_mode VBR;
  116.   int VBR_q;
  117.   int VBR_mean_bitrate_kbps;
  118.   int VBR_min_bitrate_kbps;
  119.   int VBR_max_bitrate_kbps;
  120.   int VBR_hard_min;             /* strictly enforce VBR_min_bitrate*/
  121.                                 /* normaly, it will be violated for analog silence */
  122.  
  123.  
  124.   /* resampling and filtering */
  125.   int lowpassfreq;                /* freq in Hz. 0=lame choses. -1=no filter */
  126.   int highpassfreq;               /* freq in Hz. 0=lame choses. -1=no filter */
  127.   int lowpasswidth;               /* freq width of filter, in Hz (default=15%)*/
  128.   int highpasswidth;              /* freq width of filter, in Hz (default=15%)*/
  129.  
  130.  
  131.   /* I/O - not used if calling program does the i/o */
  132.   sound_file_format input_format;   
  133.   FILE * musicin;             /* file pointer to input file */
  134.   int swapbytes;              /* force byte swapping   default=0*/
  135. #define         MAX_NAME_SIZE           1000
  136.   char inPath[MAX_NAME_SIZE];
  137.   /* Note: outPath must be set if you want Xing VBR or ID3 version 1 tags written */
  138.   char outPath[MAX_NAME_SIZE];
  139.  
  140.  
  141.  
  142.   /* optional ID3 tags  */
  143.   int id3v1_enabled;
  144.   struct id3tag_spec tag_spec;
  145.  
  146.  
  147.   /* psycho acoustics and other aguments which you should not change 
  148.    * unless you know what you are doing  */
  149.   int ATHonly;                    /* only use ATH */
  150.   int ATHshort;                   /* only use ATH for short blocks */
  151.   int noATH;                      /* disable ATH */
  152.   int ATHlower;                   /* lower ATH by this many db */
  153.   float cwlimit;                  /* predictability limit */
  154.   int allow_diff_short;       /* allow blocktypes to differ between channels ? */
  155.   int no_short_blocks;        /* disable short blocks       */
  156.   int emphasis;                   /* obsolete */
  157.  
  158.  
  159.  
  160.  
  161.   /************************************************************************/
  162.   /* internal variables, do not set... */
  163.   /************************************************************************/
  164.   int version;                /* 0=MPEG2  1=MPEG1 */
  165.   long int frameNum;              /* frame counter */
  166.   long totalframes;               /* frames: 0..totalframes-1 (estimate)*/
  167.   int encoder_delay;
  168.   int framesize;                  
  169.  
  170.  
  171.   /* VBR tags */
  172.   int nZeroStreamSize;
  173.   int TotalFrameSize;
  174.   int* pVbrFrames;
  175.   int nVbrNumFrames;
  176.   int nVbrFrameBufferSize;
  177.  
  178.  
  179.   /************************************************************************/
  180.   /* more internal variables, which will not exist after lame_encode_finish() */
  181.   /************************************************************************/
  182.   void *internal_flags;
  183.  
  184. } lame_global_flags;
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191. /*
  192.  
  193. The LAME API
  194.  
  195.  */
  196.  
  197.  
  198. /* REQUIRED: initialize the encoder.  sets default for all encoder paramters,
  199.  * returns -1 if some malloc()'s failed
  200.  * otherwise returns 0
  201.  * 
  202.  */
  203. int lame_init(lame_global_flags *);
  204.  
  205.  
  206.  
  207.  
  208. /*********************************************************************
  209.  * command line argument parsing & option setting.  Only supported
  210.  * if libmp3lame compiled with LAMEPARSE defined 
  211.  *********************************************************************/
  212. /* OPTIONAL: call this to print an error with a brief command line usage guide and quit 
  213.  * only supported if libmp3lame compiled with LAMEPARSE defined.  
  214.  */
  215. void lame_usage(lame_global_flags *, char *);
  216.  
  217. /* OPTIONAL: call this to print a command line interface usage guide and quit   */
  218. void lame_help(lame_global_flags *, char *);
  219.  
  220. /* OPTIONAL: get the version number, in a string. of the form:  "3.63 (beta)" or 
  221.    just "3.63".  Max allows length is 20 characters  */
  222. void lame_version(lame_global_flags *, char *);
  223.  
  224.  
  225. /* OPTIONAL: set internal options via command line argument parsing 
  226.  * You can skip this call if you like the default values, or if
  227.  * set the encoder parameters your self 
  228.  */
  229. void lame_parse_args(lame_global_flags *, int argc, char **argv);
  230.  
  231.  
  232.  
  233.  
  234.  
  235. /* REQUIRED:  sets more internal configuration based on data provided
  236.  * above.  returns -1 if something failed.
  237.  */
  238. int lame_init_params(lame_global_flags *);
  239.  
  240.  
  241. /* OPTONAL:  print internal lame configuration on stderr*/
  242. void lame_print_config(lame_global_flags *);
  243.  
  244.  
  245.  
  246. /* OPTONAL:  add ID3 version 2 tag to output file */
  247. void lame_id3v2_tag(lame_global_flags *,FILE *);
  248.  
  249.  
  250.  
  251.  
  252. /* input pcm data, output (maybe) mp3 frames.
  253.  * This routine handles all buffering, resampling and filtering for you.
  254.  * 
  255.  * leftpcm[]       array of 16bit pcm data, left channel
  256.  * rightpcm[]      array of 16bit pcm data, right channel
  257.  * num_samples     number of samples in leftpcm[] and rightpcm[] (if stereo)
  258.  * mp3buffer       pointer to buffer where mp3 output is written
  259.  * mp3buffer_size  size of mp3buffer, in bytes
  260.  * return code     number of bytes output in mp3buffer.  can be 0 
  261.  *                 -1:  mp3buffer was too small
  262.  *                 -2:  malloc() problem
  263.  *                 -3:  lame_init_params() not called
  264.  *                 -4:  psycho acoustic problems 
  265.  *                 -5:  ogg cleanup encoding error
  266.  *                 -6:  ogg frame encoding error
  267.  *
  268.  * The required mp3buffer_size can be computed from num_samples, 
  269.  * samplerate and encoding rate, but here is a worst case estimate:
  270.  *
  271.  * mp3buffer_size in bytes = 1.25*num_samples + 7200
  272.  *
  273.  * I think a tighter bound could be:  (mt, March 2000)
  274.  * MPEG1:
  275.  *    num_samples*(bitrate/8)/samplerate + 4*1152*(bitrate/8)/samplerate + 512
  276.  * MPEG2:
  277.  *    num_samples*(bitrate/8)/samplerate + 4*576*(bitrate/8)/samplerate + 256
  278.  *
  279.  * but test first if you use that!
  280.  *
  281.  * set mp3buffer_size = 0 and LAME will not check if mp3buffer_size is
  282.  * large enough.
  283.  *
  284.  * NOTE: if gfp->num_channels=2, but gfp->mode = 3 (mono), the L & R channels
  285.  * will be averaged into the L channel before encoding only the L channel
  286.  * This will overwrite the data in leftpcm[] and rightpcm[].
  287.  * 
  288. */
  289. int lame_encode_buffer(lame_global_flags *,short int leftpcm[], short int rightpcm[],int num_samples,
  290. char *mp3buffer,int  mp3buffer_size);
  291.  
  292. /* as above, but input has L & R channel data interleaved.  Note: 
  293.  * num_samples = number of samples in the L (or R)
  294.  * channel, not the total number of samples in pcm[]  
  295.  */
  296. int lame_encode_buffer_interleaved(lame_global_flags *,short int pcm[], 
  297. int num_samples, char *mp3buffer,int  mp3buffer_size);
  298.  
  299.  
  300.  
  301. /* input 1 pcm frame, output (maybe) 1 mp3 frame.  
  302.  * return code = number of bytes output in mp3buffer.  can be 0 
  303.  * NOTE: this interface is outdated, please use lame_encode_buffer() instead 
  304.  * declair mp3buffer with:  char mp3buffer[LAME_MAXMP3BUFFER] 
  305.  * if return code = -1:  mp3buffer was too small 
  306.  */
  307. int lame_encode(lame_global_flags *,short int Buffer[2][1152],char *mp3buffer,int mp3buffer_size);
  308.  
  309.  
  310.  
  311. /* REQUIRED:  lame_encode_finish will flush the buffers and may return a 
  312.  * final few mp3 frames.  mp3buffer should be at least 7200 bytes.
  313.  *
  314.  * return code = number of bytes output to mp3buffer.  can be 0
  315.  */
  316. int lame_encode_finish(lame_global_flags *,char *mp3buffer, int size);
  317.  
  318.  
  319. /* OPTIONAL:  lame_mp3_tags will append ID3 version 1 and Xing VBR tags to
  320. the mp3 file with name given by gf->outPath.  These calls open the file,
  321. write tags, and close the file, so make sure the the encoding is finished
  322. before calling these routines.  
  323. Note: if VBR and ID3 version 1 tags are turned off by the user, or turned off
  324. by LAME because the output is not a regular file, this call does nothing
  325. */
  326. void lame_mp3_tags(lame_global_flags *);
  327.  
  328.  
  329.  
  330.  
  331. /*********************************************************************
  332.  * lame file i/o.  Only supported
  333.  * if libmp3lame compiled with LAMESNDFILE or LIBSNDFILE
  334.  *********************************************************************/
  335. /* OPTIONAL: open the input file, and parse headers if possible 
  336.  * you can skip this call if you will do your own PCM input 
  337.  */
  338. void lame_init_infile(lame_global_flags *);
  339.  
  340. /* OPTIONAL:  read one frame of PCM data from audio input file opened by 
  341.  * lame_init_infile.  Input file can be wav, aiff, raw pcm, anything
  342.  * supported by libsndfile, or an mp3 file
  343.  */
  344. int lame_readframe(lame_global_flags *,short int Buffer[2][1152]);
  345.  
  346. /* OPTIONAL: close the sound input file if lame_init_infile() was used */
  347. void lame_close_infile(lame_global_flags *);
  348.  
  349.  
  350.  
  351.  
  352.  
  353. /*********************************************************************
  354.  * a simple interface to mpglib, part of mpg123, is also included if
  355.  * libmp3lame is compiled with HAVEMPGLIB
  356.  * input 1 mp3 frame, output (maybe) pcm data.  
  357.  * lame_decode return code:  -1: error.  0: need more data.  n>0: size of pcm output
  358.  *********************************************************************/
  359. typedef struct {
  360.   int stereo;      /* number of channels */
  361.   int samplerate;  /* sample rate */
  362.   int bitrate;     /* bitrate */
  363.   unsigned long nsamp;    /* number of samples in mp3 file, estimated */
  364. } mp3data_struct;
  365.  
  366.  
  367. int lame_decode_init(void);
  368. int lame_decode(char *mp3buf,int len,short pcm_l[],short pcm_r[]);
  369.  
  370. /* same as lame_decode, but returns at most one frame */
  371. int lame_decode1(char *mp3buf,int len,short pcm_l[],short pcm_r[]);
  372.  
  373.  
  374. /* read mp3 file until mpglib returns one frame of PCM data */
  375. #ifdef AMIGA_MPEGA
  376. int lame_decode_initfile(const char *fullname,mp3data_struct *mp3data);
  377. int lame_decode_fromfile(FILE *fd,short int pcm_l[], short int pcm_r[],mp3data_struct *mp3data);
  378. #else
  379. int lame_decode_initfile(FILE *fd,mp3data_struct *mp3data);
  380. int lame_decode_fromfile(FILE *fd,short int pcm_l[],short int pcm_r[],mp3data_struct *mp3data);
  381. #endif
  382.  
  383. /* and for Vorbis: */
  384. int lame_decode_ogg_initfile(FILE *fd,mp3data_struct *mp3data);
  385. int lame_decode_ogg_fromfile(FILE *fd,short int pcm_l[],short int pcm_r[],mp3data_struct *mp3data);
  386.  
  387. /* the simple lame decoder (interface to above routines) */
  388. /* After calling lame_init(), lame_init_params() and
  389.  * lame_init_infile(), call this routine to read the input MP3 file 
  390.  * and output .wav data to the specified file pointer*/
  391. /* lame_decoder will ignore the first 528 samples, since these samples
  392.  * represent the mpglib delay (and are all 0).  skip = number of additional
  393.  * samples to skip, to (for example) compensate for the encoder delay,
  394.  * only used when decoding mp3 */
  395. int lame_decoder(lame_global_flags *gfp,FILE *outf,int skip);
  396.  
  397.  
  398. #if defined(__cplusplus)
  399. }
  400. #endif
  401.  
  402.  
  403. #endif
  404.