carb::audio::EventStreamer

Defined in carb/audio/AudioStreamerUtils.h

class EventStreamer : public carb::audio::StreamerWrapper

A events::IEvents based audio streamer.

This will send a stream of audio data through events::IEvents then pumps the event stream asynchronously. This is ideal for use cases where audio streaming is needed, but the component receiving audio is unable to meet the latency requirements of other audio streamers.

To receive data from this, you will need to create an EventListener with the event stream returned from the getEventStream() call on this class.

Public Functions

inline EventStreamer()

inline bool isWorking() noexcept

Check if the class actually initialized successfully.

Returns

whether the class actually initialized successfully.

inline void setFormat(const SoundFormat *format) noexcept

Specify a desired format for the audio stream.

Parameters

format – [in] The format that you want to be used. This can be nullptr to just use the default format.

inline EventListener *createListener(std::function<void(const carb::audio::SoundFormat *fmt)> open, std::function<void(const void *data, size_t bytes)> writeData, std::function<void()> close)

Create an EventListener for this streamer.

Remark

These callbacks will be fired until the EventListener is deleted. Note that you must create the listener before the audio stream opens, otherwise the open event will never be received, so you will not receive data until the stream closes and re-opens.

Parameters

• open – [in] The callback which is sent when the audio stream is first opened. This is used to provide information about the data in the audio stream.

• writeData – [in] The callback which is sent when a buffer of data is sent from the stream. These callbacks are only sent after an open() callback has been sent. Note that the data sent here may not be properly aligned for its data type due to the nature of events::IEvents, so you should memcpy the data somewhere that’s aligned for safety.

• close – [in] This is called when the audio stream is closed.

Returns

An event listener.

Returns

nullptr if an out of memory error occurs.

inline carb::events::IEventStreamPtr getEventStream() noexcept

Retrieve the event stream used by the data streamer.

Remark

This event stream is exposed to be subscribed to. Sending other events into this stream will cause errors.

Returns

The event stream used by the data streamer.

inline void flush() noexcept

Wait for all asynchronous tasks created by this stream to finish.

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

true if the close call has been given

Returns

false if 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.