AConvertAFile(3X)

NAME

AConvertAFile − convert the format of audio file data

SYNOPSIS

#include <Alib.h> void
AConvertAFile (

Audio ∗ audio,

char ∗ src_pathname,

AFileFormat src_file_format,

char ∗ dest_pathname,

AFileFormat dest_file_format,

AudioAttrMask dest_attr_mask,

AudioAttributes ∗ dest_attributes,

long ∗ status_return );

DESCRIPTION

AConvertAFile() converts the data in src_pathname according to the format specified in dest_file_format and the attributes in dest_attributes. The results are written to dest_pathname.

audio the audio structure associated with this connection.

src_pathname the pathname of the source file.

src_file_format the file format of the source file. One of the following values:

AFFUnknown − Have the Audio library determine the file type (see below).

AFFRiffWave − Microsoft RIFF waveform

AFFSun − Sun(NeXT) format. This is the default format.

AFFRawMuLaw MuLaw format

AFFRawALaw ALaw format

AFFRawLin16 − Linear16 (16-bit signed) format

AFFRawLin8 − Linear8 (8-bit signed) format

AFFRawLin8Offset − Linear8Offset (8-bit unsigned)

If this parameter is set to AFFUnknown, the conversion utility attempts to determine the file format from the file header if one exists, or from the filename extension.

If there is no determinable file format, an error is returned; there is no default.

Valid file type extensions are:

.u raw Mulaw

.al raw Alaw

.au Sun (NeXT)

.wav Riff

.snd NeXT

.l16 raw linear16

.l8 raw linear8

.lo8 raw linear8Offset

dest_pathname the pathname of the destination file.

dest_file_format the file format of the destination file. If this is AFFUnknown and the target file already exists, the Audio Library will try to determine the format of the existing file and use that. Otherwise, the Audio Library will look for a valid filename extension. An error will be returned if the destination format is specified as AFFUnknown and can’t be determined.

dest_attr_mask the audio attributes to be used in dest_attributes. The mask is the bitwise inclusive OR of one or more of the mask values listed in the Structures section.

If this mask is set to 0, values are used from the source file wherever they are appropriate for files of type dest_file_format. If the corresponding values in the source file are not appropriate, the Audio Library will choose the closest fit and convert the data to it.

dest_attributes the attributes that are affected by the mask; if set to NULL, the attribute mask is cleared, and values are used from the source file wherever they are appropriate for files of type dest_file_format. For attributes to be valid, type must be set (i.e., ATSampled), separate from the mask.

status_return receives the returned status of the operation, unless this parameter is passed in as a NULL pointer. If status_return is set to NULL, Alib will do the error handling.

STRUCTURES

The following are defined in /opt/audio/include/Alib.h.

typedef long                    AudioAttrMask;
#define ASDataFormatMask        ( 1 << ASAFDataFormat )
#define ASBitsPerSampleMask     ( 1 << ASAFBitsPerSample )
#define ASSamplingRateMask      ( 1 << ASAFSamplingRate )
#define ASChannelsMask          ( 1 << ASAFChannels )
#define ASInterleaveMask        ( 1 << ASAFInterleave )
#define ASDurationMask          ( 1 << ASAFDuration )

ERRORS

If status_return is not set to NULL, it can return one of the following values:

0 AENoError No error - the call completed successfully.

1 AESystemCall A file read, write, or open failed with an error other than File Not Found.

2 AEBadAudio The audio structure is invalid. A pointer to a valid audio structure may be missing (use AOpenAudio() to get a valid pointer)

6 AEBadFileFormat The specified file format is currently unsupported.

7 AEBadDataFormat The data format specified in an attributes structure is either not appropriate for the file format or is not one of the supported data formats.

8 AEFileNotFound The Audio Library could not find the specified file.

11 AEBadFileHdr The specified file type requires a header, but the file lacks a valid header for that file type.

13 AEBadAttribute The specified audio attributes structure contains an unsupported or inconsistent value.

16 AECantDetermineFormat AFFUnknown was specified for either the source or destination file format, but there is no valid header or filename extension, so Alib cannot determine the format.

17 AEOutOfMemory Alib attempted to malloc space but failed. A possible cause is the use of sound buckets with large audio files.

EXAMPLE

The following example converts the data in /mydir/aufile.wav to a 30-second Sun (NeXT) format "mono" Mulaw file, sampled at 8000 samples per second, and writes the result in /mydir/aufile.au.

Audio ∗ audio; /∗ audio connection ∗/

AFileFormat src_fmt; /∗ source file format ∗/

AFileFormat dest_fmt; /∗ destination file format ∗/

AudioAttrMask a_mask; /∗ audio attributes mask ∗/

AudioAttributes dest_attr; /∗ destination attributes ∗/

long status; /∗ error status ∗/

static char s_name[] = {"/mydir/aufile.wav"};

static char d_name[] = {"/mydir/aufile.au"};
.
.
.

/∗ convert audio file ∗/

dest_fmt = AFFSun; /∗ Sun (NeXT) format ∗/

a_mask = 0;

dest_attr.type = ATSampled; /∗ must set this ∗/

dest_attr.attr.sampled_attr.data_format = ADFMuLaw;

a_mask = a_mask | ASDataFormatMask;

dest_attr.attr.sampled_attr.sampling_rate = 8000;

a_mask = a_mask | ASSamplingRateMask;

dest_attr.attr.sampled_attr.channels = 1;

a_mask = a_mask | ASChannelsMask;

dest_attr.attr.sampled_attr.duration.type = ATTMilliSeconds;

dest_attr.attr.sampled_attr.duration.u.milliseconds = 30000;

a_mask = a_mask | ASDurationMask;

AConvertAFile(audio, s_name, src_fmt, d_name, dest_fmt,

a_mask, &dest_attr,&status);

NOTE

In order to ensure that the compiler finds the Audio Library (libAlib.sl) and the Alib.h header file, you must add the following switches:

-L /opt/audio/lib
-I/opt/audio/include

DEPENDENCIES

This function belongs to the Audio Library of functions that manage connections to an audio server. The audio server must run on a system that has audio hardware. To find out whether or not your system has audio hardware, refer to Using the Audio Developer’s Kit or the online help for the Audio control panel. For information about the audio capabilities of a particular system use the online example audioinfo.c.

AUTHOR

AConvertAFile() was developed by HP.

Museum

Related Articles