Re: [Libvisual-devel] VisAudio overhaul proposal.

[Burkhard P. <pl...@ip...>]

Dennis Smit wrote:
> Heya everyone.
> 
> I wrote the first version of the new VisAudio API proposal.
> 
> It's going to be a complete overhaul, and thus should be done right.
> 
> PLEASE read this document, and comment upon it! 

If you are brave enough to add another dependency to libvisual,
you can use my gavl library for the audio handling:

http://cvs.sourceforge.net/viewcvs.py/gmerlin/gavl/include/gavl/gavl.h?rev=1.24&view=log

It supports the following formats:

- Arbitrary samplerates
- 8, 16 and 32 bit integer and floating point
- 3 different interleave modes: None, All and Interleaved pairs
   of channels (e.g. for 5.1 playback on 3 stereo devices)

- Container structs for Audio format and Audio frame

- Conversion between ALL supported formats including resampling at
   several quality levels (using libsamplerate) and audio dithering

Format definition looks like this:

/* Sample formats: all multibyte numbers are native endian */

typedef enum
   {
     GAVL_SAMPLE_NONE  = 0,
     GAVL_SAMPLE_U8    = 1,
     GAVL_SAMPLE_S8    = 2,
     GAVL_SAMPLE_U16   = 3,
     GAVL_SAMPLE_S16   = 4,
     GAVL_SAMPLE_S32   = 5,
     GAVL_SAMPLE_FLOAT = 6
   } gavl_sample_format_t;

/* Interleave modes */

typedef enum
   {
     GAVL_INTERLEAVE_NONE = 0, /* No interleaving, all channels separate */
     GAVL_INTERLEAVE_2    = 1, /* Interleaved pairs of channels          */
     GAVL_INTERLEAVE_ALL  = 2  /* Everything interleaved                 */
   } gavl_interleave_mode_t;

/*
  *  Audio channel setup: This can be used with
  *  AC3 decoders to support all speaker configurations
  */

typedef enum
   {
     GAVL_CHANNEL_NONE   = 0,
     GAVL_CHANNEL_MONO   = 1,
     GAVL_CHANNEL_STEREO = 2, /* 2 Front channels (Stereo or Dual channels) */
     GAVL_CHANNEL_3F     = 3,
     GAVL_CHANNEL_2F1R   = 4,
     GAVL_CHANNEL_3F1R   = 5,
     GAVL_CHANNEL_2F2R   = 6,
     GAVL_CHANNEL_3F2R   = 7
   } gavl_channel_setup_t;

/* Channel IDs */

typedef enum
   {
     GAVL_CHID_NONE         = 0,
     GAVL_CHID_FRONT,
     GAVL_CHID_FRONT_LEFT,
     GAVL_CHID_FRONT_RIGHT,
     GAVL_CHID_FRONT_CENTER,
     GAVL_CHID_REAR,
     GAVL_CHID_REAR_LEFT,
     GAVL_CHID_REAR_RIGHT,
     GAVL_CHID_LFE
   } gavl_channel_id_t;

/* Structure describing an audio format */

typedef struct gavl_audio_format_s
   {
   int samples_per_frame;  /* Maximum number of samples per frame */
   int samplerate;
   int num_channels;
   gavl_sample_format_t   sample_format;
   gavl_interleave_mode_t interleave_mode;
   gavl_channel_setup_t   channel_setup;
   int lfe;            /* Low frequency effect channel present */

   float center_level; /* linear factor for mixing center to front */
   float rear_level;   /* linear factor for mixing rear to front */

   /* Which channel is stored where */

   gavl_channel_id_t channel_locations[GAVL_MAX_CHANNELS];
   } gavl_audio_format_t;

The audio frame then looks like this:

typedef union gavl_audio_samples_u
   {
   uint8_t * u_8;
   int8_t *  s_8;

   uint16_t * u_16;
   int16_t  * s_16;

   uint32_t * u_32;
   int32_t  * s_32;

   float * f;
   } gavl_audio_samples_t;

/* Container for noninterleaved audio channels */

typedef union gavl_audio_channels_u
   {
   uint8_t * u_8[GAVL_MAX_CHANNELS];
   int8_t *  s_8[GAVL_MAX_CHANNELS];

   uint16_t * u_16[GAVL_MAX_CHANNELS];
   int16_t  * s_16[GAVL_MAX_CHANNELS];

   uint32_t * u_32[GAVL_MAX_CHANNELS];
   int32_t  * s_32[GAVL_MAX_CHANNELS];

   float * f[GAVL_MAX_CHANNELS];

   } gavl_audio_channels_t;

/* Audio frame */

typedef struct gavl_audio_frame_s
   {
   gavl_audio_samples_t  samples;
   gavl_audio_channels_t channels;
   int valid_samples;              /* Real number of samples */
   } gavl_audio_frame_t;

If some source and destination module have different formats,
just fire up a gavl_audio_converter_t, and it will do the conversion.
Futhermore, there are functions for allocating/freeing audio frames
(with memory alignment) as well as a copy function, which lets you
easily create an audio buffer.

I'm using this in my own projects for quite a time now and I never
got a format, which couldn't be handled by gavl.
The only thing which might eventually be missing is 7.1 (2 side channels),
but this could be added as well if needed.

I think it would provide a greater flexibility than the
VisAudioSoundImportType enum :-)

Whether or not the plugins have restrictions concerning the formats is
another question. The 512 samples in each frame seem to be hardcoded
in most plugins and I don't know if this mumber must become variable.

Concerning the samplerate, most material is 44100 but there are also
48000 streams (e.g. from Music DVDs) or 22050 (used by some
web radio stations). So you could let the plugins handle all these rates
or use gavl to resample everything to 44100.

-- 
_____________________________
Dr.-Ing. Burkhard Plaum
Institut fuer Plasmaforschung
Pfaffenwaldring 31
70569 Stuttgart
Tel.: +49 711 685-2187
Fax.:            -3102