search

thestk / rtaudio

A set of C++ classes that provide a common API for realtime audio input/output across Linux (native ALSA, JACK, PulseAudio and OSS), Macintosh OS X (CoreAudio and JACK), and Windows (DirectSound, ASIO, and WASAPI) operating systems.
Other
1.49k stars 317 forks source link

clarification on behavior of functions #395

Closed BillyDM closed 1 year ago

BillyDM commented 1 year ago

I'm creating Rust bindings for RtAudio using the C header in https://github.com/thestk/rtaudio/blob/master/rtaudio_c.h.

I have a few questions about the behavior of certain functions. The docs don't make it very clear.

  1. When calling the function rtaudio_open_stream(), is it guaranteed that the rtaudio_cb_t callback will not be called until after the rtaudio_start_stream() method is called?

  2. When calling the function rtaudio_stop_stream(), does it block the calling thread until the stream is successfully stopped?

  3. Likewise, does rtaudio_close_stream() and rtaudio_abort_stream() block the calling thread until the stream is successfully dropped?

  4. When the rtaudio_error_cb_t callback passed to the rtaudio_open_stream() function is called, does it mean that the stream was stopped and/or closed because of an error? If so, do all the error types mean that the stream was closed, or do only certain error types mean that the stream was closed?

BillyDM commented 1 year ago
  1. Also, is rtaudio_stop_stream() guaranteed to stop the stream and rtaudio_close_stream() guaranteed to close the stream? Or is it when those functions return an error, it means that they failed to do that operation?
BillyDM commented 1 year ago

I found the answer to question 1 in the docs. https://www.music.mcgill.ca/~gary/rtaudio/playback.html

garyscavone commented 1 year ago

First of all, I'm not sure which version of RtAudio you are asking questions about. My answers here pertain to RtAudio.cpp version 6.0.0, beta 1 ... I assume the behaviour implemented in the C API (which I did not create) is similar:

  1. The documentation for RtAudio::stopStream() says "Stop a stream, allowing any samples remaining in the output queue to be played." That means that that function blocks (does not return) until samples in the cue are played out (if an output stream). The user provided RtAudioCallback function thus may be called a few times before stopStream() returns.

  2. RtAudio:closeStream() will close the stream immediately, release relevant memory and return. RtAudio::abortStream() will stop the stream immediately and return (though the stream remains open in that case).

  3. Error handling changed in version 6.0.0, beta 1, with C++ exceptions being discontinued. An error callback can report a warning, in which case the stream remains in the state it was in previously. Non-recoverable errors can be returned from only a few functions, such as openStream, startStream, stopStream, and abortStream.

BillyDM commented 1 year ago

Ok, thanks for the clarification!

A follow-up question about error handling: Does the error callback get used at all while the stream is running? Like if the user unplugs a device while the stream is running, does the error callback get called? And if it does, does it mean that the stream is in an invalid state and should be closed, or will the stream keep running regardless?

garyscavone commented 1 year ago

The desired behaviour if a device in use is unplugged is to close the stream and report the problem via the error callback with the RTAUDIO_DEVICE_DISCONNECT type. However, not all APIs have listeners to detect and deal with such disconnections.

BillyDM commented 1 year ago

Ok cool. I figured that's how it works but I wanted to make sure. Thanks again!