Lines Matching +full:is +full:- +full:stream
2 Oboe is a C++ library which makes it easy to build high-performance audio apps on Android. Apps com…
6 …ams*, represented by the class `AudioStream`. The read/write calls can be blocking or non-blocking.
8 A stream is defined by the following:
10 * The *audio* *device* that is the source or sink for the data in the stream.
11 * The *sharing mode* that determines whether a stream has exclusive access to an audio device tha…
12 * The *format* of the audio data in the stream.
16 Each stream is attached to a single audio device.
18 An audio device is a hardware interface or virtual endpoint that acts as a source or sink for a con…
19 (a built-in mic or bluetooth headset) with the *Android device* (the phone or watch) that is runnin…
23 … a unique ID on the Android device. You can use the ID to bind an audio stream to a specific audi…
25 …stream determines whether the stream is for input or output. A stream can only move data in one di…
29 A stream has a sharing mode:
31 …stream has exclusive access to an endpoint on its audio device; the endpoint cannot be used by any…
33 
37 
40 …haring mode when you create a stream, although you are not guaranteed to receive that mode. By def…
44 The data passed through a stream has the usual digital audio attributes, which you must specify whe…
53 | :------------ | :---------- | :---- |
54 | I16 | int16_t | common 16-bit samples, [Q0.15 format](https://source.android.com/devices/audio/da…
55 | Float | float | -1.0 to +1.0 |
57 …is writing AudioFormat::Float data but the HAL uses AudioFormat::I16, Oboe might convert the sampl…
59 AudioFormat dataFormat = stream->getDataFormat();
65 ## Creating an audio stream
69 ### Set the audio stream configuration using an AudioStreamBuilder. argument
71 Use the builder functions that correspond to the stream parameters. These optional set functions ar…
83 …uch as an undefined constant or value out of range. They will be checked when the stream is opened.
85 If you do not specify the deviceId, the default is the primary output device.
86 If you do not specify the stream direction, the default is an output stream.
91 To be safe, check the state of the audio stream after you create it, as explained in step 3, below.
93 ### Open the Stream
95 …stream. Make sure it is declared with the appropriate scope. The best place is as a member variabl…
99 After you've configured the `AudioStreamBuilder`, call `openStream()` to open the stream:
105 "Error opening stream %s",
110 ### Verifying stream configuration and additional properties argument
112 You should verify the stream's configuration after opening it.
124 The following properties may be changed by the underlying stream construction
132 The following properties are only set by the underlying stream. They cannot be
139 * deviceId is respected when the underlying API is AAudio (API level >=28), but not when it
140 is OpenSLES. It can be set regardless, but *will not* throw an error if an OpenSLES stream
141 is used. The default device will be used, rather than whatever is specified.
143 * mAudioApi is only a property of the builder, however
145 stream uses. The property set in the builder is not guaranteed, and in
147 stability considerations. Since Oboe is designed to be as uniform across both
150 * mBufferSizeInFrames can only be set on an already open stream (as opposed to a
151 builder), since it depends on run-time behavior.
155 This feature is not supported when using a callback with OpenSL ES.
157 Many of the stream's properties may vary (whether or not you set
160 the accessor after the stream has been opened. Additionally,
161 the underlying parameters a stream is granted are useful to know if
163 should check the stream's configuration before using it.
166 There are functions to retrieve the stream setting that corresponds to each
171 | :------------------------ | :----------------- |
182 | -- | `getFramesPerBurst()` |
188 they have little effect on the stream, but setting them helps applications
192 The InputPreset may be used by the device to process the input stream (such as gain control). By de…
193 it is set to VoiceRecognition, which is optimized for low latency.
195 * `setUsage(oboe::Usage usage)` - The purpose for creating the stream.
196 * `setContentType(oboe::ContentType contentType)` - The type of content carried
197 by the stream.
198 * `setInputPreset(oboe::InputPreset inputPreset)` - The recording configuration
200 * `setSessionId(SessionId sessionId)` - Allocate SessionID to connect to the
204 ## Using an audio stream
208 An Oboe stream is usually in one of five stable states (the error state, Disconnected, is described…
216 Data only flows through a stream when the stream is in the Started state. To
217 move a stream between states, use one of the functions that request a state
221 result = stream->requestStart();
222 result = stream->requestStop();
223 result = stream->requestPause();
224 result = stream->requestFlush();
226 Note that you can only request pause or flush on an output stream:
229 immediately. When you request a state change, the stream moves to one of the
241 
251 is *different* than `inputState`, which you specify.
253 For example, after requesting to pause, a stream should immediately enter
254 the transient state Pausing, and arrive sometime later at the Paused state - though there's no guar…
262 result = stream->requestPause();
263 result = stream->waitForStateChange(inputState, &nextState, timeoutNanos);
267 If the stream's state is not Pausing (the `inputState`, which we assumed was the
269 blocks until the state is no longer Pausing or the timeout expires. When the
271 stream.
275 `waitForStateChange()` after calling `AudioStream::close()` since the underlying stream resources
277 while `waitForStateChange()` is running in another thread.
279 ### Reading and writing to an audio stream argument
281 There are two ways to move data in or out of a stream.
282 1) Read from or write directly to the stream.
283 2) Specify a data callback object that will get called when the stream is ready.
286 Also, attempting to open a low latency output stream without an audio callback (with the intent to …
287 may result in a non low latency stream.
289 …g both input and output, it is common to use a callback for output and then just do a non-blocking…
291 After the stream is started you can read or write to it using the methods
296 … timeoutNanos greater than zero. For a non-blocking call, set timeoutNanos to zero. In this case t…
303 Result result = mStream->read(audioData, numFrames, timeout);
310 (numFrames - result) * mStream->getBytesPerFrame());
313 You can prime the stream's buffer before starting the stream by writing data or silence into it. Th…
315 The data in the buffer must match the data format returned by `mStream->getDataFormat()`.
317 ### Closing an audio stream argument
319 When you are finished using a stream, close it:
321 stream->close();
323 … not close a stream while it is being written to or read from another thread as this will cause yo…
325 ### Disconnected audio stream argument
327 An audio stream can become disconnected at any time if one of these events happens:
329 * The associated audio device is no longer connected (for example when headphones are unplugged).
331 * An audio device is no longer the primary audio device.
333 …stream is disconnected, it has the state "Disconnected" and calls to `write()` or other functions …
335 If you need to be informed when an audio device is disconnected, write a class
336 …egister your class using `builder.setErrorCallback(yourCallbackClass)`. It is recommended to pass …
337 …ster a callback, then it will automatically close the stream in a separate thread if the stream is…
341 * `onErrorBeforeClose(stream, error)` - called when the stream has been disconnected but not yet cl…
342 so you can still reference the underlying stream (e.g.`getXRunCount()`).
343 You can also inform any other threads that may be calling the stream to stop doing so.
344 Do not delete the stream or modify its stream state in this callback.
345 * `onErrorAfterClose(stream, error)` - called when the stream has been stopped and closed by Oboe s…
346 During this callback, stream properties (those requested by the builder) can be queried, as well as…
347 The stream can be deleted at the end of this method (as long as it not referenced in other threads).
348 Methods that reference the underlying stream should not be called (e.g. `getTimestamp()`, `getXRunC…
349 Opening a separate stream is also a valid use of this callback, especially if the error received is…
350 However, it is important to note that the new audio device may have vastly different properties tha…
356 You can optimize the performance of an audio application by using special high-priority threads.
362 For applications that require low latency, an audio stream can use an asynchronous callback functio…
363 The callback runs in a high-priority thread that has better performance.
366 `AudioStreamDataCallback`. The stream periodically executes `onAudioReady()` (the
369 The total number of samples that you need to fill is numFrames * numChannels.
378 const int numChannels = AAudioStream_getChannelCount(stream);
379 // This code assumes the format is AAUDIO_FORMAT_PCM_FLOAT.
383 float noise = (float)(drand48() - 0.5);
400 Note that the callback must be registered on the stream with `setDataCallback`. Any
401 application-specific data can be included within the class itself.
403 …stream that invoked it. If the callback belongs to an input stream, your code should process the d…
405 …is possible to process more than one stream in the callback. You can use one stream as the master,…
406 stream. The input stream is included in the class.
408 The callback does a non-blocking read from the input stream placing the data into the buffer of the…
417 const int64_t timeoutNanos = 0; // for a non-blocking read
418 auto result = recordingStream->read(audioData, numFrames, timeoutNanos);
419 // result has type ResultWithValue<int32_t>, which for convenience is coerced
425 (numFrames - result.value()) * oboeStream->getBytesPerFrame());
438 void setRecordingStream(AudioStream *stream) {
439 recordingStream = stream;
447 …e it is assumed the input and output streams have the same number of channels, format and sample r…
449 #### Data Callback - Do's and Don'ts
452 - allocate memory using, for example, malloc() or new
453 - file operations such as opening, closing, reading or writing
454 - network operations such as streaming
455 - use mutexes or other synchronization primitives
456 - sleep
457 - stop or close the stream
458 - Call read() or write() on the stream which invoked it
462 - AudioStream::get*()
463 - oboe::convertResultToText()
469 * `PerformanceMode::None` is the default mode. It uses a basic stream that balances latency and pow…
476 If low latency is more important than power savings in your application, use `PerformanceMode::LowL…
477 This is useful for apps that are very interactive, such as games or keyboard synthesizers.
479 If saving power is more important than low latency in your application, use `PerformanceMode::Power…
480 This is typical for apps that play back previously generated music, such as streaming audio or MIDI…
482 …ust use the `PerformanceMode::LowLatency` performance mode along with a high-priority data callbac…
488 // Create a stream builder
496 The Oboe API is not completely [thread safe](https://en.wikipedia.org/wiki/Thread_safety).
498 This is because Oboe avoids using mutexes, which can cause thread preemption and glitches.
500 …tateChange()` or read or write to the same stream from two different threads. Similarly, don't clo…
502 Calls that return stream settings, like `AudioStream::getSampleRate()` and `AudioStream::getChannel…
509 …hen a stream uses an error callback, it's safe to read/write from the callback thread while also c…