afNewFileSetup(3dm) afNewFileSetup(3dm)
afNewFileSetup - create and initialize an AFfilesetup structure
#include <dmedia/audiofile.h>
AFfilesetup afNewFileSetup(void) [Toc] [Back]
An opaque AFfilesetup structure initialized to the default configuration
for a new audio file opened with write access, or for opening a raw
(headerless) audio file for read access.
Use afNewFileSetup() to create and initialize an AFfilesetup structure.
This structure passes configuration parameters to afOpenFile(3dm), which
formats the skeleton for a new file accordingly.
When an AFfilesetup structure is no longer needed it should be discarded
with afFreeFileSetup(3dm). Freeing an AFfilesetup will not affect any
open AFfilehandle structure.
Configuration parameters include:
- the desired audio file format
- the number of audio tracks and the type of sample data stored in each
- the number of markers allocated for each track
- the number of instrument configurations (including loop points)
- the number of loops allocated for each instrument
- the number, types, and sizes of miscellaneous data chunks (strings,
etc)
- integer ID's for tracks, instruments, markers, loops, miscellaneous
data
For AIFF-C (and AIFF) files, the above list of parameters simplifies a
bit. There is always one audio track per file. There is at most one
instrument configuration per file, and there are always two loops per
instrument.
To initialize the various file configuration parameters stored in an
AFfilesetup structure, see the initialization routines mentioned below in
SEE ALSO.
Page 1
afNewFileSetup(3dm) afNewFileSetup(3dm)
DEFAULT FILE SETUP CONFIGURATION
The default parameter values in a new AFfilesetup structure are listed
here.
- file format
defaults to AIFF-C, denoted by the constant AF_FILE_AIFFC
- default audio track
one track per file, with track ID AF_DEFAULT_TRACK
- markers for audio track
four markers with ID's {1,2,3,4}
- interleaved channels for audio track
2 (stereo)
- sample format for audio track
two's complement 16-bit linear PCM, given by the constant
AF_SAMPFMT_TWOSCOMP with width 16
- compression used on audio track
no compression, specified by the constant AF_COMPRESSION_NONE
- default instrument configuration
one instrument configuration, with instrument ID AF_DEFAULT_INST
- instrument configuration parameters
default instrument configuration for AIFF-C (and AIFF) is:
AF_INST_MIDI_BASENOTE 60 MIDI
AF_INST_NUMCENTS_DETUNE 0 cents
AF_INST_MIDI_LONOTE 0 MIDI
AF_INST_MIDI_HINOTE 127 MIDI
AF_INST_MIDI_LOVELOCITY 1 MIDI
AF_INST_MIDI_HIVELOCITY 127 MIDI
AF_INST_NUMDBS_GAIN 0 dB
AF_INST_SUSLOOPID 1 loop ID for sustain loop
AF_INST_RELLOOPID 2 loop ID for release loop
- loops
two loops with ID's {1,2}
default mode for each loop is AF_LOOP_MODE_NOLOOP (ignore loop)
For file formats other than AIFF and AIFF-C, a default audio format and
file configuration (i.e., number of tracks, insts, loops, etc.) is
generated when afOpenFile(3dm) or its equivalent is called. This means
that an application does not need to initialize any parameters in the
setup structure prior to calling afOpenFile(3dm) other than the sample
format itself (see afInitFileFormat(3dm)), unless a custom configuration
is desired. The afQuery(3dm) routine provides a mechanism for retrieving
informnation about default sample formats and widths for each file
format, plus information about supported track, inst, loop, marker, and
misc chunks.
Page 2
afNewFileSetup(3dm) afNewFileSetup(3dm)
READING RAW AUDIO FILES
When opening raw audio files with read access, i.e., files with no header
or with unrecognizable header formats, afOpenFile(3dm) and its related
routines must be passed a AFfilesetup struct initialized to the exact
format parameters of the raw file. Most especially, the file format
parameter must be set to AF_FILE_RAWDATA for all raw reads, regardless of
the "actual" header type.
The default values produced by afNewFileSetup() are for use when creating
new files with write-access only.
afInitFileFormat(3dm), afInitChannels(3dm), afInitLoopIDs(3dm),
afInitMarkIDs(3dm), afInitMiscIDs(3dm), afInitRate(3dm),
afInitSampleFormat(3dm)
afOpenFile(3dm), afFreeFileSetup(3dm)
afNewFileSetup(3dm) afNewFileSetup(3dm)
afNewFileSetup - create and initialize an AFfilesetup structure
#include <dmedia/audiofile.h>
AFfilesetup afNewFileSetup(void) [Toc] [Back]
An opaque AFfilesetup structure initialized to the default configuration
for a new audio file opened with write access, or for opening a raw
(headerless) audio file for read access.
Use afNewFileSetup() to create and initialize an AFfilesetup structure.
This structure passes configuration parameters to afOpenFile(3dm), which
formats the skeleton for a new file accordingly.
When an AFfilesetup structure is no longer needed it should be discarded
with afFreeFileSetup(3dm). Freeing an AFfilesetup will not affect any
open AFfilehandle structure.
Configuration parameters include:
- the desired audio file format
- the number of audio tracks and the type of sample data stored in each
- the number of markers allocated for each track
- the number of instrument configurations (including loop points)
- the number of loops allocated for each instrument
- the number, types, and sizes of miscellaneous data chunks (strings,
etc)
- integer ID's for tracks, instruments, markers, loops, miscellaneous
data
For AIFF-C (and AIFF) files, the above list of parameters simplifies a
bit. There is always one audio track per file. There is at most one
instrument configuration per file, and there are always two loops per
instrument.
To initialize the various file configuration parameters stored in an
AFfilesetup structure, see the initialization routines mentioned below in
SEE ALSO.
Page 1
afNewFileSetup(3dm) afNewFileSetup(3dm)
DEFAULT FILE SETUP CONFIGURATION
The default parameter values in a new AFfilesetup structure are listed
here.
- file format
defaults to AIFF-C, denoted by the constant AF_FILE_AIFFC
- default audio track
one track per file, with track ID AF_DEFAULT_TRACK
- markers for audio track
four markers with ID's {1,2,3,4}
- interleaved channels for audio track
2 (stereo)
- sample format for audio track
two's complement 16-bit linear PCM, given by the constant
AF_SAMPFMT_TWOSCOMP with width 16
- compression used on audio track
no compression, specified by the constant AF_COMPRESSION_NONE
- default instrument configuration
one instrument configuration, with instrument ID AF_DEFAULT_INST
- instrument configuration parameters
default instrument configuration for AIFF-C (and AIFF) is:
AF_INST_MIDI_BASENOTE 60 MIDI
AF_INST_NUMCENTS_DETUNE 0 cents
AF_INST_MIDI_LONOTE 0 MIDI
AF_INST_MIDI_HINOTE 127 MIDI
AF_INST_MIDI_LOVELOCITY 1 MIDI
AF_INST_MIDI_HIVELOCITY 127 MIDI
AF_INST_NUMDBS_GAIN 0 dB
AF_INST_SUSLOOPID 1 loop ID for sustain loop
AF_INST_RELLOOPID 2 loop ID for release loop
- loops
two loops with ID's {1,2}
default mode for each loop is AF_LOOP_MODE_NOLOOP (ignore loop)
For file formats other than AIFF and AIFF-C, a default audio format and
file configuration (i.e., number of tracks, insts, loops, etc.) is
generated when afOpenFile(3dm) or its equivalent is called. This means
that an application does not need to initialize any parameters in the
setup structure prior to calling afOpenFile(3dm) other than the sample
format itself (see afInitFileFormat(3dm)), unless a custom configuration
is desired. The afQuery(3dm) routine provides a mechanism for retrieving
informnation about default sample formats and widths for each file
format, plus information about supported track, inst, loop, marker, and
misc chunks.
Page 2
afNewFileSetup(3dm) afNewFileSetup(3dm)
READING RAW AUDIO FILES
When opening raw audio files with read access, i.e., files with no header
or with unrecognizable header formats, afOpenFile(3dm) and its related
routines must be passed a AFfilesetup struct initialized to the exact
format parameters of the raw file. Most especially, the file format
parameter must be set to AF_FILE_RAWDATA for all raw reads, regardless of
the "actual" header type.
The default values produced by afNewFileSetup() are for use when creating
new files with write-access only.
afInitFileFormat(3dm), afInitChannels(3dm), afInitLoopIDs(3dm),
afInitMarkIDs(3dm), afInitMiscIDs(3dm), afInitRate(3dm),
afInitSampleFormat(3dm)
afOpenFile(3dm), afFreeFileSetup(3dm)
PPPPaaaaggggeeee 3333 [ Back ]
|