afReadFrames(3dm) afReadFrames(3dm)
afReadFrames - read sample frames from a specified audio track in an
audio file
#include <dmedia/audiofile.h>
int afReadFrames(const AFfilehandle file, int track,
void *samples, const int count)
file is the AFfilehandle structure for the audio file from which
audio sample data will be read. This structure is usually the
returned value of a call to afOpenFile(3dm).
track is an integer which identifies an audio track in a file.
Since all currently supported file formats allow at most one
audio track per file, the value AF_DEFAULT_TRACK should always
be used for this argument for now.
samples is a pointer to a buffer into which you want to transfer the
samples read from the audio file. Note that the data type of
the samples in this buffer can vary depending on the sample
format and sample width of the file.
count is the number of sample frames to be read from the audio track.
For monaural data a sample frame is a single sample; for stereo
data a sample frame is a pair of samples, etc.
afReadFrames() returns the number of sample frames actually read from the
file. In the event of error, -1 is returned and oserror(3C) will be set
to the appropriate error code.
afReadFrames() transfers data from the specified track of an audio file
to the samples buffer. samples should be of type char*, short*, int*,
unsigned int*, float*, or double* depending on the width and format of
the samples in the audio track as retrieved using afGetSampleFormat(3dm),
or the virtual format specified by afSetVirtualSampleFormat(3dm).
afReadFrames() attempts to read count sample frames from the file,
starting at the current location of the file read pointer.
When a file is opened with read access by afOpenFD(3dm),
afOpenNamedFD(3dm), or afOpenFile(3dm), the file pointer for each audio
track is initialized to point to the first sample frame in the audio
track. The pointer may be moved to any sample frame location within a
specified track by a call to afSeekFrame(3dm).
Page 1
afReadFrames(3dm) afReadFrames(3dm)
Before returning, afReadFrames() automatically updates the read pointer
for track so that it points to the sample frame following the last one
copied into samples.
Note that the data type of the samples in this buffer can vary depending
on the sample format and sample width of the samples in the track. The
samples buffer is interpreted differently depending on the current
configuration of the audio track. The sampwidth parameter returned by
afGetSampleFormat(3dm) may or may not be meaningful, depending on the
value of sampfmt. See afGetSampleFormat(3dm) for a full explanation of
sample representations.
afReadFrames() automatically decompresses data which was encoded with the
CCITT G.722, CCITT G.711, MPEG, and Aware compression. By default, the
data for all currently supported compression formats is presented to
application programs in the standard two's complement linear PCM format,
but this is by no means guaranteed for future compression types. See
afGetCompression(3dm) and afSetVirtualSampleFormat for further
information. To achieve real-time G.722 compression, the application
process may require non-degrading scheduling priority (see schedctl(2) or
npri(1))
If an audio track contains data for more than a single audio channel, the
data returned in the samples buffer will be interleaved. For stereo
data, the samples are always grouped in left/right pairs (sample frames).
For reference, interleave conventions for files containing multichannel
data are stated in the AIFF-C spec.
To read 10000 stereo sample frames (i.e., 20000 individual audio samples)
from a stereo AIFF-C file which contains G.722-encoded data, declare
samples to be a short[] buffer (since G.722 encodes 16-bit data) with at
least 20000 locations, and call afReadFrames() with count set to 10000.
This routine will not function correctly if the user changes the file
position on the file descriptor for the AFfilehandle being manipulated.
See afSaveFilePosition(3dm) and the section CAVEATS FOR USING THE
HANDLE'S FILE DESCRIPTOR in afIntro(3dm) for some important information
about how to deal with this situation.
afOpenFile(3dm), afSeekFrame(3dm), afGetSampleFormat(3dm),
afWriteFrames(3dm), afGetCompression(3dm), afSetVirtualSampleFormat(3dm),
afGetVirtualSampleFormat(3dm)
afReadFrames(3dm) afReadFrames(3dm)
afReadFrames - read sample frames from a specified audio track in an
audio file
#include <dmedia/audiofile.h>
int afReadFrames(const AFfilehandle file, int track,
void *samples, const int count)
file is the AFfilehandle structure for the audio file from which
audio sample data will be read. This structure is usually the
returned value of a call to afOpenFile(3dm).
track is an integer which identifies an audio track in a file.
Since all currently supported file formats allow at most one
audio track per file, the value AF_DEFAULT_TRACK should always
be used for this argument for now.
samples is a pointer to a buffer into which you want to transfer the
samples read from the audio file. Note that the data type of
the samples in this buffer can vary depending on the sample
format and sample width of the file.
count is the number of sample frames to be read from the audio track.
For monaural data a sample frame is a single sample; for stereo
data a sample frame is a pair of samples, etc.
afReadFrames() returns the number of sample frames actually read from the
file. In the event of error, -1 is returned and oserror(3C) will be set
to the appropriate error code.
afReadFrames() transfers data from the specified track of an audio file
to the samples buffer. samples should be of type char*, short*, int*,
unsigned int*, float*, or double* depending on the width and format of
the samples in the audio track as retrieved using afGetSampleFormat(3dm),
or the virtual format specified by afSetVirtualSampleFormat(3dm).
afReadFrames() attempts to read count sample frames from the file,
starting at the current location of the file read pointer.
When a file is opened with read access by afOpenFD(3dm),
afOpenNamedFD(3dm), or afOpenFile(3dm), the file pointer for each audio
track is initialized to point to the first sample frame in the audio
track. The pointer may be moved to any sample frame location within a
specified track by a call to afSeekFrame(3dm).
Page 1
afReadFrames(3dm) afReadFrames(3dm)
Before returning, afReadFrames() automatically updates the read pointer
for track so that it points to the sample frame following the last one
copied into samples.
Note that the data type of the samples in this buffer can vary depending
on the sample format and sample width of the samples in the track. The
samples buffer is interpreted differently depending on the current
configuration of the audio track. The sampwidth parameter returned by
afGetSampleFormat(3dm) may or may not be meaningful, depending on the
value of sampfmt. See afGetSampleFormat(3dm) for a full explanation of
sample representations.
afReadFrames() automatically decompresses data which was encoded with the
CCITT G.722, CCITT G.711, MPEG, and Aware compression. By default, the
data for all currently supported compression formats is presented to
application programs in the standard two's complement linear PCM format,
but this is by no means guaranteed for future compression types. See
afGetCompression(3dm) and afSetVirtualSampleFormat for further
information. To achieve real-time G.722 compression, the application
process may require non-degrading scheduling priority (see schedctl(2) or
npri(1))
If an audio track contains data for more than a single audio channel, the
data returned in the samples buffer will be interleaved. For stereo
data, the samples are always grouped in left/right pairs (sample frames).
For reference, interleave conventions for files containing multichannel
data are stated in the AIFF-C spec.
To read 10000 stereo sample frames (i.e., 20000 individual audio samples)
from a stereo AIFF-C file which contains G.722-encoded data, declare
samples to be a short[] buffer (since G.722 encodes 16-bit data) with at
least 20000 locations, and call afReadFrames() with count set to 10000.
This routine will not function correctly if the user changes the file
position on the file descriptor for the AFfilehandle being manipulated.
See afSaveFilePosition(3dm) and the section CAVEATS FOR USING THE
HANDLE'S FILE DESCRIPTOR in afIntro(3dm) for some important information
about how to deal with this situation.
afOpenFile(3dm), afSeekFrame(3dm), afGetSampleFormat(3dm),
afWriteFrames(3dm), afGetCompression(3dm), afSetVirtualSampleFormat(3dm),
afGetVirtualSampleFormat(3dm)
PPPPaaaaggggeeee 2222 [ Back ]
|
