The base class for all audio input streams.
Inherited from std::istream
.
read()
: extracts blocks of charactersgcount()
: returns number of characters extracted by last unformatted input operation⚠️ Using these operations should be avoided. They are provided for maximum flexibility if clients need to operate on the raw pcm data. In most use cases, formatted input operations can and should be used as they provide type safety and are optimized for best performance.
Inherited from std::istream
.
⚠️ Using these operations should be avoided. They are provided for maximum flexibility if clients need to operate on the raw pcm data. It is the clients reponsibility to ensure that the position is aligned withing a sample or frame. Therefore it is recommended to use [sample based positioning operations (#sample-based-positioning-operations) instead.
Inherited from std::basic_ios
.
good()
: checks if no error has occurred i.e. I/O operations are availableeof()
: checks if end-of-file has been reachedfail()
: checks if an error has occurredbad()
: checks if a non-recoverable error has occurredoperator!()
: checks if an error has occurred (synonym of fail()
)operator bool()
: checks if no error has occurred (synonym of !fail()
)rdstate()
: returns state flagssetstate()
: sets state flagsclear()
: modifies state flagsrdbuf
: Returns the associated stream buffer. If there is no associated stream buffer, returns a null pointer.Accessing the associated stream buffer might be usefull for i.e. wrapping an audio::stream into an std::istream (and interface with other std functions) :
std::string to_string(audio::istream& stream)
{
std::istream ref_stream( stream.rdbuf() ); // a reference to the stream
return { std::istreambuf_iterator<char>(ref_stream), std::istreambuf_iterator<char>() };
}
These operations extracts one or more samples from the stream, by converting the underlying pcm data sequence into a sequence of samples. The sample format can be any floating point type ( i.e. float
, double
) or integral type (e.g int8_t
, int16_t
, int32_t
, int64_t
, uint8_t
, uint16_t
, uint32_t
, uint64_t
)
operator>>
: extracts samples from the stream.
std::istream
::
operator>>
.eof
) during this operation, the remaining samples in the range will be set to the sample format’s neutral element (which is 0 in most cases). This comes in handy as audio processing is mostly block-based and the last block usually needs to be zero-padded anyways.⚠️ It is highly recommended to use the range-based version instead of the value-based version as this will result in a better performance (during pcm conversion).
I.e. clients should stream block wise:
void process(audio::istream& stream)
{
std::vector<float> buffer(256);
while (stream >> buffer)
{
// process whole buffer
}
}
rather than sample wise:
void process(audio::istream& stream)
{
float value;
while (stream >> value)
{
// process sample
}
}
sample_tellg()
: returns the input position indicator of the current sampleframe_tellg()
: returns the input position indicator of the current framesample_seekg()
: sets the input position indicator to the sample positionframe_seekg()
: sets the input position indicator to the frame positioninfo()
: returns the stream info audio::istream_info
with contains audio specific information like:
num_channels
: the number of channelsnum_frames
: the number of sample frames ( one frame consist of num_channels samples )sample_rate
: the sample rateformat
: the pcm format the audio data is stored in⚠️ The info may contain erroneous information in case the stream is corrupted. Clients have to check if the info is plausible in their own context (i.e. num_channels <= 2
when expecting
stereo data).