carb::audio::OutputStreamer
Defined in carb/audio/AudioStreamerUtils.h
-
class OutputStreamer : public carb::audio::StreamerWrapper
a streamer object to write to a stream to a file.
The stream will be output in realtime by default (ie: writing to file at the same rate as the sound would play back on an audio device). This can be sped up by not specifying the fFlagRealtime flag. When this flag is not set, the stream data will be produced as fast as possible.
An output filename must be set with setFilename() before the streamer can be opened. All other parameters will work properly as their defaults.
Public Types
-
typedef uint32_t Flags
Type definition for the behavioral flags for this streamer.
Public Functions
-
inline OutputStreamer(SampleFormat outputFormat = SampleFormat::eDefault, Flags flags = fFlagRealtime)
Constructor.
- Parameters
outputFormat – [in] The encoded format for the output file.
flags – [in] Behavioral flags for this instance.
-
inline OutputStreamDesc *getDescriptor()
retrieves the descriptor that will be used to open the output stream.
- Returns
the descriptor object. This will never be nullptr. This can be used to manually fill in the descriptor if need be, or to just verify the settings that will be used to open the output stream.
-
inline void setFlags(Flags flags)
sets the flags that will control how data is written to the stream.
- Parameters
flags – [in] the flags that will control how data is written to the stream. This is zero or more of the kFlag* flags.
- Returns
no return value.
-
inline Flags getFlags() const
retrieves the flags that are control how data is written to the stream.
- Returns
the flags that will control how data is written to the stream. This is zero or more of the kFlag* flags.
-
inline void setOutputFormat(SampleFormat format)
sets the output format for the stream.
- Parameters
format – [in] the output format for the stream. This can be SampleFormat::eDefault to use the same format as the input. If this is to be changed, this must be done before open() is called.
- Returns
no return value.
-
inline void setFilename(const char *filename)
sets the filename for the output stream.
- Parameters
filename – [in] the filename to use for the output stream. This must be set before open() is called. This may not be nullptr.
- Returns
no return value.
-
inline const char *getFilename() const
retrieves the filename assigned to this streamer.
- Returns
the filename assigned to this streamer. This will be nullptr if no filename has been set yet.
-
inline void setEncoderSettings(const void *settings, size_t sizeInBytes)
sets the additional encoder settings to use for the output stream.
Remark
This sets the additional encoder settings block to use for the output stream. This block will be copied to be stored internally. This will replace any previous encoder settings block.
- Parameters
settings – [in] the encoder settings block to use to open the output stream. This may be nullptr to clear any previously set encoder settings block.
sizeInBytes – [in] the size of the encoder settings block in bytes.
- Returns
no return value.
-
inline virtual bool open(SoundFormat *format) override
sets the suggested format for this stream output.
Remark
This sets the data format that the streamer will receive its data in. The streamer may change the data format to another valid PCM data format if needed. Note that if the streamer returns a data format that cannot be converted to by the processing engine, the initialization of the output will fail. Also note that if the streamer changes the data format, this will incur a small performance penalty to convert the data to the new format.
Remark
This will be called when the audio context is first created. Once the format is accepted by both the audio context and the streamer, it will remain constant as long as the processing engine is still running on that context. When the engine is stopped (or the context is destroyed), a Streamer::close() call will be performed signaling the end of the stream. If the engine is restarted again, another open() call will be performed to signal the start of a new stream.
Note
This should not be called directly. This will be called by the audio processing engine when this streamer object is first assigned as an output on an audio context.
- Parameters
format – [inout] on input, this contains the suggested data format for the stream. On output, this contains the accepted data format. The streamer may make some changes to the data format including the data type, sample rate, and channel count. It is strongly suggested that the input format be accepted since that will result in the least amount of processing overhead. The format, channels, frameRate, and bitsPerSample members must be valid upon return. If the streamer changes the data format, only PCM data formats are acceptable.
- Returns
true if the data format is accepted by the streamer.
- Returns
false if the streamer can neither handle the requested format nor can it change the requested format to something it likes.
-
inline virtual StreamState writeData(const void *data, size_t bytes) override
writes a buffer of data to the stream.
Remark
This writes a buffer of data to the streamer. The streamer is responsible for doing something useful with the audio data (ie: write it to a file, write it to a memory buffer, stream it to another voice, etc). The caller of this function is not interested in whether the streamer successfully does something with the data - it is always assumed that the operation is successful.
Note
This must execute as quickly as possible. If this call takes too long to return and the output is going to a real audio device (through the streamer or some other means), an audible audio dropout could occur. If the audio context is executing in non-realtime mode (ie: baking audio data), this may take as long as it needs only at the expense of making the overall baking process take longer.
Note
This should not be called directly. This will be called by the audio processing engine when a buffer of new data is produced.
- Parameters
data – [in] the audio data being written to the streamer. This data will be in the format that was decided on in the call to open() during the context creation or the last call to setOutput(). This buffer will not persist upon return. The implementation must copy the contents of the buffer if it still needs to access the data later.
bytes – [in] the number of bytes of valid data in the buffer
data.
- Return values
StreamState::eNormal – if the data was written successfully to the streamer and the data production rate should continue at the current rate.
StreamState::eMore – if the data was written successfully to the streamer and the data production rate should be temporarily increased.
StreamState::eLess – if the data was written successfully to the streamer and the data production rate should be temporarily reduced.
StreamState::eCritical – if the data was written successfully to the streamer and more data needs to be provided as soon as possible.
StreamState::eMuchLess – if the data was written successfully to the streamer and the data rate needs to be halved.
-
inline virtual void close() override
closes the stream.
Remark
This signals that a stream has been finished. This occurs when the engine is stopped or the audio context is destroyed. No more calls to writeData() should be expected until the streamer is opened again.
Note
This should not be called directly. This will be called by the audio processing engine when audio processing engine is stopped or the context is destroyed.
- Returns
no return value.
-
inline void acquire()
acquires a single reference to this streamer object.
Remark
This acquires a new reference to this streamer object. The reference must be released later with release() when it is no longer needed. Each call to acquire() on an object must be balanced with a call to release(). When a new streamer object is created, it should be given a reference count of 1.
- Returns
no return value.
-
inline void release()
releases a single reference to this streamer object.
Remark
This releases a single reference to this streamer object. If the reference count reaches zero, the object will be destroyed. The caller should assume the object to have been destroyed unless it is well known that other local references still exist.
- Returns
no return value.
-
template<class Rep, class Period>
inline bool waitForClose(const std::chrono::duration<Rep, Period> &duration) noexcept Wait until the close() call has been given.
Remark
If you disconnect a streamer via IAudioPlayback::setOutput(), the engine may not be stopped, so the streamer won’t be immediately disconnected. In cases like this, you should call waitForClose() if you need to access the streamer’s written data but don’t have access to the close() call (e.g. if you’re using an OutputStreamer).
- Parameters
duration – [in] The duration to wait before timing out.
- Returns
trueif the close call has been given- Returns
falseif the timeout was reached.
Public Members
-
void (*acquireReference)(Streamer *self)
acquires a single reference to a Streamer object.
Remark
This acquires a new reference to a Streamer object. The reference must be released later with releaseReference() when it is no longer needed. Each call to acquireReference() on an object must be balanced with a call to releaseReference(). When a new streamer object is created, it should be given a reference count of 1.
- Param self
[in] the object to take the reference of.
- Return
no return value.
-
void (*releaseReference)(Streamer *self)
releases a single reference to a Streamer object.
Remark
This releases a single reference to a Streamer object. If the reference count reaches zero, the object will be destroyed.
- Param self
[in] the object to release a reference to. The object may be destroyed if it was the last reference that was released. The caller should consider the object invalid upon return unless it is known that additional local references still exist on it.
- Return
no return value.
-
bool (*openStream)(Streamer *self, SoundFormat *format)
sets the suggested format for the stream output.
Remark
This sets the data format that the streamer will receive its data in. The streamer may change the data format to another valid PCM data format if needed. Note that if the streamer returns a data format that cannot be converted to by the processing engine, the initialization of the output will fail. Also note that if the streamer changes the data format, this will incur a small performance penalty to convert the data to the new format.
Remark
This will be called when the audio context is first created. Once the format is accepted by both the audio context and the streamer, it will remain constant as long as the processing engine is still running on that context. When the engine is stopped (or the context is destroyed), a Streamer::close() call will be performed signaling the end of the stream. If the engine is restarted again, another open() call will be performed to signal the start of a new stream.
- Param self
[in] the streamer object to open the stream for. This will not be nullptr.
- Param format
[inout] on input, this contains the suggested data format for the stream. On output, this contains the accepted data format. The streamer may make some changes to the data format including the data type, sample rate, and channel count. It is strongly suggested that the input format be accepted since that will result in the least amount of processing overhead. The format, channels, frameRate, and bitsPerSample members must be valid upon return. If the streamer changes the data format, only PCM data formats are acceptable.
- Return
true if the data format is accepted by the streamer.
- Return
false if the streamer can neither handle the requested format nor can it change the requested format to something it likes.
-
StreamState (*writeStreamData)(Streamer *self, const void *data, size_t bytes)
writes a buffer of data to the stream.
Remark
This writes a buffer of data to the streamer. The streamer is responsible for doing something useful with the audio data (ie: write it to a file, write it to a memory buffer, stream it to another voice, etc). The caller of this function is not interested in whether the streamer successfully does something with the data - it is always assumed that the operation is successful.
Note
This must execute as quickly as possible. If this call takes too long to return and the output is going to a real audio device (through the streamer or some other means), an audible audio dropout could occur. If the audio context is executing in non-realtime mode (ie: baking audio data), this may take as long as it needs only at the expense of making the overall baking process take longer.
- Param self
[in] the streamer object to write a buffer of data into. This will not be nullptr.
- Param data
[in] the audio data being written to the streamer. This data will be in the format that was decided on in the call to open() during the context creation or the last call to setOutput(). This buffer will not persist upon return. The implementation must copy the contents of the buffer if it still needs to access the data later.
- Param bytes
[in] the number of bytes of valid data in the buffer
data.- Retval StreamState::eNormal
if the data was written successfully to the streamer and the data production rate should continue at the current rate.
- Retval StreamState::eMore
if the data was written successfully to the streamer and the data production rate should be temporarily increased.
- Retval StreamState::eLess
if the data was written successfully to the streamer and the data production rate should be temporarily reduced.
-
void (*closeStream)(Streamer *self)
closes the stream.
Remark
This signals that a stream has been finished. This occurs when the engine is stopped or the audio context is destroyed. No more calls to writeData() should be expected until the streamer is opened again.
- Param self
[in] the streamer object to close the stream for. This will not be nullptr.
- Return
no return value.
Public Static Attributes
Protected Functions
-
inline ~OutputStreamer() override
-
typedef uint32_t Flags