1 module soundio.api; 2 3 extern (C): @nogc: nothrow: 4 5 /// See also ::soundio_strerror 6 enum SoundIoError 7 { 8 None = 0, 9 /// Out of memory. 10 NoMem = 1, 11 /// The backend does not appear to be active or running. 12 InitAudioBackend = 2, 13 /// A system resource other than memory was not available. 14 SystemResources = 3, 15 /// Attempted to open a device and failed. 16 OpeningDevice = 4, 17 NoSuchDevice = 5, 18 /// The programmer did not comply with the API. 19 Invalid = 6, 20 /// libsoundio was compiled without support for that backend. 21 BackendUnavailable = 7, 22 /// An open stream had an error that can only be recovered from by 23 /// destroying the stream and creating it again. 24 Streaming = 8, 25 /// Attempted to use a device with parameters it cannot support. 26 IncompatibleDevice = 9, 27 /// When JACK returns `JackNoSuchClient` 28 NoSuchClient = 10, 29 /// Attempted to use parameters that the backend cannot support. 30 IncompatibleBackend = 11, 31 /// Backend server shutdown or became inactive. 32 BackendDisconnected = 12, 33 Interrupted = 13, 34 /// Buffer underrun occurred. 35 Underflow = 14, 36 /// Unable to convert to or from UTF-8 to the native string format. 37 EncodingString = 15 38 } 39 40 enum SoundIoErrorNone = SoundIoError.None; /// ditto 41 enum SoundIoErrorNoMem = SoundIoError.NoMem; /// ditto 42 enum SoundIoErrorInitAudioBackend = SoundIoError.InitAudioBackend; /// ditto 43 enum SoundIoErrorSystemResources = SoundIoError.SystemResources; /// ditto 44 enum SoundIoErrorOpeningDevice = SoundIoError.OpeningDevice; /// ditto 45 enum SoundIoErrorNoSuchDevice = SoundIoError.NoSuchDevice; /// ditto 46 enum SoundIoErrorInvalid = SoundIoError.Invalid; /// ditto 47 enum SoundIoErrorBackendUnavailable = SoundIoError.BackendUnavailable; /// ditto 48 enum SoundIoErrorStreaming = SoundIoError.Streaming; /// ditto 49 enum SoundIoErrorIncompatibleDevice = SoundIoError.IncompatibleDevice; /// ditto 50 enum SoundIoErrorNoSuchClient = SoundIoError.NoSuchClient; /// ditto 51 enum SoundIoErrorIncompatibleBackend = SoundIoError.IncompatibleBackend; /// ditto 52 enum SoundIoErrorBackendDisconnected = SoundIoError.BackendDisconnected; /// ditto 53 enum SoundIoErrorInterrupted = SoundIoError.Interrupted; /// ditto 54 enum SoundIoErrorUnderflow = SoundIoError.Underflow; /// ditto 55 enum SoundIoErrorEncodingString = SoundIoError.EncodingString; /// ditto 56 57 58 /// Specifies where a channel is physically located. 59 enum SoundIoChannelId 60 { 61 Invalid = 0, 62 63 FrontLeft = 1, ///< First of the more commonly supported ids. 64 FrontRight = 2, 65 FrontCenter = 3, 66 Lfe = 4, 67 BackLeft = 5, 68 BackRight = 6, 69 FrontLeftCenter = 7, 70 FrontRightCenter = 8, 71 BackCenter = 9, 72 SideLeft = 10, 73 SideRight = 11, 74 TopCenter = 12, 75 TopFrontLeft = 13, 76 TopFrontCenter = 14, 77 TopFrontRight = 15, 78 TopBackLeft = 16, 79 TopBackCenter = 17, 80 TopBackRight = 18, ///< Last of the more commonly supported ids. 81 82 BackLeftCenter = 19, ///< First of the less commonly supported ids. 83 BackRightCenter = 20, 84 FrontLeftWide = 21, 85 FrontRightWide = 22, 86 FrontLeftHigh = 23, 87 FrontCenterHigh = 24, 88 FrontRightHigh = 25, 89 TopFrontLeftCenter = 26, 90 TopFrontRightCenter = 27, 91 TopSideLeft = 28, 92 TopSideRight = 29, 93 LeftLfe = 30, 94 RightLfe = 31, 95 Lfe2 = 32, 96 BottomCenter = 33, 97 BottomLeftCenter = 34, 98 BottomRightCenter = 35, 99 100 /// Mid/side recording 101 MsMid = 36, 102 MsSide = 37, 103 104 /// first order ambisonic channels 105 AmbisonicW = 38, 106 AmbisonicX = 39, 107 AmbisonicY = 40, 108 AmbisonicZ = 41, 109 110 /// X-Y Recording 111 XyX = 42, 112 XyY = 43, 113 114 HeadphonesLeft = 44, ///< First of the "other" channel ids 115 HeadphonesRight = 45, 116 ClickTrack = 46, 117 ForeignLanguage = 47, 118 HearingImpaired = 48, 119 Narration = 49, 120 Haptic = 50, 121 DialogCentricMix = 51, ///< Last of the "other" channel ids 122 123 Aux = 52, 124 Aux0 = 53, 125 Aux1 = 54, 126 Aux2 = 55, 127 Aux3 = 56, 128 Aux4 = 57, 129 Aux5 = 58, 130 Aux6 = 59, 131 Aux7 = 60, 132 Aux8 = 61, 133 Aux9 = 62, 134 Aux10 = 63, 135 Aux11 = 64, 136 Aux12 = 65, 137 Aux13 = 66, 138 Aux14 = 67, 139 Aux15 = 68 140 } 141 142 /// Built-in channel layouts for convenience. 143 enum SoundIoChannelLayoutId 144 { 145 Mono = 0, 146 Stereo = 1, 147 _2Point1 = 2, 148 _3Point0 = 3, 149 _3Point0Back = 4, 150 _3Point1 = 5, 151 _4Point0 = 6, 152 Quad = 7, 153 QuadSide = 8, 154 _4Point1 = 9, 155 _5Point0Back = 10, 156 _5Point0Side = 11, 157 _5Point1 = 12, 158 _5Point1Back = 13, 159 _6Point0Side = 14, 160 _6Point0Front = 15, 161 Hexagonal = 16, 162 _6Point1 = 17, 163 _6Point1Back = 18, 164 _6Point1Front = 19, 165 _7Point0 = 20, 166 _7Point0Front = 21, 167 _7Point1 = 22, 168 _7Point1Wide = 23, 169 _7Point1WideBack = 24, 170 Octagonal = 25 171 } 172 173 /// 174 enum SoundIoBackend 175 { 176 None = 0, 177 Jack = 1, 178 PulseAudio = 2, 179 Alsa = 3, 180 CoreAudio = 4, 181 Wasapi = 5, 182 Dummy = 6 183 } 184 185 enum SoundIoBackendNone = SoundIoBackend.None; /// ditto 186 enum SoundIoBackendJack = SoundIoBackend.Jack; /// ditto 187 enum SoundIoBackendPulseAudio = SoundIoBackend.PulseAudio; /// ditto 188 enum SoundIoBackendAlsa = SoundIoBackend.Alsa; /// ditto 189 enum SoundIoBackendCoreAudio = SoundIoBackend.CoreAudio; /// ditto 190 enum SoundIoBackendWasapi = SoundIoBackend.Wasapi; /// ditto 191 enum SoundIoBackendDummy = SoundIoBackend.Dummy; /// ditto 192 193 /// Whether a device is an input device or output device 194 enum SoundIoDeviceAim 195 { 196 Input = 0, ///< capture / recording 197 Output = 1 ///< playback 198 } 199 enum SoundIoDeviceAimInput = SoundIoDeviceAim.Input; /// ditto 200 enum SoundIoDeviceAimOutput = SoundIoDeviceAim.Output; /// ditto 201 202 /// For your convenience, Native Endian and Foreign Endian constants are defined 203 /// which point to the respective SoundIoFormat values. 204 enum SoundIoFormat 205 { 206 Invalid = 0, 207 S8 = 1, ///< Signed 8 bit 208 U8 = 2, ///< Unsigned 8 bit 209 S16LE = 3, ///< Signed 16 bit Little Endian 210 S16BE = 4, ///< Signed 16 bit Big Endian 211 U16LE = 5, ///< Unsigned 16 bit Little Endian 212 U16BE = 6, ///< Unsigned 16 bit Big Endian 213 S24LE = 7, ///< Signed 24 bit Little Endian using low three bytes in 32-bit word 214 S24BE = 8, ///< Signed 24 bit Big Endian using low three bytes in 32-bit word 215 U24LE = 9, ///< Unsigned 24 bit Little Endian using low three bytes in 32-bit word 216 U24BE = 10, ///< Unsigned 24 bit Big Endian using low three bytes in 32-bit word 217 S32LE = 11, ///< Signed 32 bit Little Endian 218 S32BE = 12, ///< Signed 32 bit Big Endian 219 U32LE = 13, ///< Unsigned 32 bit Little Endian 220 U32BE = 14, ///< Unsigned 32 bit Big Endian 221 Float32LE = 15, ///< Float 32 bit Little Endian, Range -1.0 to 1.0 222 Float32BE = 16, ///< Float 32 bit Big Endian, Range -1.0 to 1.0 223 Float64LE = 17, ///< Float 64 bit Little Endian, Range -1.0 to 1.0 224 Float64BE = 18, ///< Float 64 bit Big Endian, Range -1.0 to 1.0 225 S16NE = SoundIoFormatS16NE, 226 U16NE = SoundIoFormatU16NE, 227 S24NE = SoundIoFormatS24NE, 228 U24NE = SoundIoFormatU24NE, 229 S32NE = SoundIoFormatS32NE, 230 U32NE = SoundIoFormatU32NE, 231 Float32NE = SoundIoFormatFloat32NE, 232 Float64NE = SoundIoFormatFloat64NE, 233 S16FE = SoundIoFormatS16FE, 234 U16FE = SoundIoFormatU16FE, 235 S24FE = SoundIoFormatS24FE, 236 U24FE = SoundIoFormatU24FE, 237 S32FE = SoundIoFormatS32FE, 238 U32FE = SoundIoFormatU32FE, 239 Float32FE = SoundIoFormatFloat32FE, 240 Float64FE = SoundIoFormatFloat64FE, 241 } 242 243 enum SoundIoFormatInvalid = SoundIoFormat.Invalid; /// ditto 244 enum SoundIoFormatS8 = SoundIoFormat.S8; /// ditto 245 enum SoundIoFormatU8 = SoundIoFormat.U8; /// ditto 246 enum SoundIoFormatS16LE = SoundIoFormat.S16LE; /// ditto 247 enum SoundIoFormatS16BE = SoundIoFormat.S16BE; /// ditto 248 enum SoundIoFormatU16LE = SoundIoFormat.U16LE; /// ditto 249 enum SoundIoFormatU16BE = SoundIoFormat.U16BE; /// ditto 250 enum SoundIoFormatS24LE = SoundIoFormat.S24LE; /// ditto 251 enum SoundIoFormatS24BE = SoundIoFormat.S24BE; /// ditto 252 enum SoundIoFormatU24LE = SoundIoFormat.U24LE; /// ditto 253 enum SoundIoFormatU24BE = SoundIoFormat.U24BE; /// ditto 254 enum SoundIoFormatS32LE = SoundIoFormat.S32LE; /// ditto 255 enum SoundIoFormatS32BE = SoundIoFormat.S32BE; /// ditto 256 enum SoundIoFormatU32LE = SoundIoFormat.U32LE; /// ditto 257 enum SoundIoFormatU32BE = SoundIoFormat.U32BE; /// ditto 258 enum SoundIoFormatFloat32LE = SoundIoFormat.Float32LE; /// ditto 259 enum SoundIoFormatFloat32BE = SoundIoFormat.Float32BE; /// ditto 260 enum SoundIoFormatFloat64LE = SoundIoFormat.Float64LE; /// ditto 261 enum SoundIoFormatFloat64BE = SoundIoFormat.Float64BE; /// ditto 262 263 /// Note that we build the documentation in Little Endian mode, 264 /// so all the "NE" macros in the docs point to "LE" and 265 /// "FE" macros point to "BE". On a Big Endian system it is the 266 /// other way around. 267 version(LittleEndian) { 268 enum SoundIoFormatS16NE = SoundIoFormat.S16LE; /// ditto 269 enum SoundIoFormatU16NE = SoundIoFormat.U16LE; /// ditto 270 enum SoundIoFormatS24NE = SoundIoFormat.S24LE; /// ditto 271 enum SoundIoFormatU24NE = SoundIoFormat.U24LE; /// ditto 272 enum SoundIoFormatS32NE = SoundIoFormat.S32LE; /// ditto 273 enum SoundIoFormatU32NE = SoundIoFormat.U32LE; /// ditto 274 enum SoundIoFormatFloat32NE = SoundIoFormat.Float32LE; /// ditto 275 enum SoundIoFormatFloat64NE = SoundIoFormat.Float64LE; /// ditto 276 277 enum SoundIoFormatS16FE = SoundIoFormat.S16BE; /// ditto 278 enum SoundIoFormatU16FE = SoundIoFormat.U16BE; /// ditto 279 enum SoundIoFormatS24FE = SoundIoFormat.S24BE; /// ditto 280 enum SoundIoFormatU24FE = SoundIoFormat.U24BE; /// ditto 281 enum SoundIoFormatS32FE = SoundIoFormat.S32BE; /// ditto 282 enum SoundIoFormatU32FE = SoundIoFormat.U32BE; /// ditto 283 enum SoundIoFormatFloat32FE = SoundIoFormat.Float32BE; /// ditto 284 enum SoundIoFormatFloat64FE = SoundIoFormat.Float64BE; /// ditto 285 } else version(BigEndian) { 286 enum SoundIoFormatS16NE = SoundIoFormat.S16BE; /// ditto 287 enum SoundIoFormatU16NE = SoundIoFormat.U16BE; /// ditto 288 enum SoundIoFormatS24NE = SoundIoFormat.S24BE; /// ditto 289 enum SoundIoFormatU24NE = SoundIoFormat.U24BE; /// ditto 290 enum SoundIoFormatS32NE = SoundIoFormat.S32BE; /// ditto 291 enum SoundIoFormatU32NE = SoundIoFormat.U32BE; /// ditto 292 enum SoundIoFormatFloat32NE = SoundIoFormat.Float32BE; /// ditto 293 enum SoundIoFormatFloat64NE = SoundIoFormat.Float64BE; /// ditto 294 295 enum SoundIoFormatS16FE = SoundIoFormat.S16LE; /// ditto 296 enum SoundIoFormatU16FE = SoundIoFormat.U16LE; /// ditto 297 enum SoundIoFormatS24FE = SoundIoFormat.S24LE; /// ditto 298 enum SoundIoFormatU24FE = SoundIoFormat.U24LE; /// ditto 299 enum SoundIoFormatS32FE = SoundIoFormat.S32LE; /// ditto 300 enum SoundIoFormatU32FE = SoundIoFormat.U32LE; /// ditto 301 enum SoundIoFormatFloat32FE = SoundIoFormat.Float32LE; /// ditto 302 enum SoundIoFormatFloat64FE = SoundIoFormat.Float64LE; /// ditto 303 } else { 304 static assert(0, "no endian"); 305 } 306 307 enum SOUNDIO_MAX_CHANNELS = 24; 308 /// The size of this struct is OK to use. 309 struct SoundIoChannelLayout 310 { 311 const(char)* name; 312 int channel_count; 313 SoundIoChannelId[SOUNDIO_MAX_CHANNELS] channels; 314 } 315 316 /// The size of this struct is OK to use. 317 struct SoundIoSampleRateRange 318 { 319 int min; 320 int max; 321 } 322 323 /// The size of this struct is OK to use. 324 struct SoundIoChannelArea 325 { 326 /// Base address of buffer. 327 char* ptr; 328 /// How many bytes it takes to get from the beginning of one sample to 329 /// the beginning of the next sample. 330 int step; 331 } 332 333 /// The size of this struct is not part of the API or ABI. 334 struct SoundIo 335 { 336 extern(C): @nogc: nothrow: 337 /// Optional. Put whatever you want here. Defaults to NULL. 338 void* userdata; 339 /// Optional callback. Called when the list of devices change. Only called 340 /// during a call to ::soundio_flush_events or ::soundio_wait_events. 341 void function (SoundIo*) on_devices_change; 342 /// Optional callback. Called when the backend disconnects. For example, 343 /// when the JACK server shuts down. When this happens, listing devices 344 /// and opening streams will always fail with 345 /// SoundIoErrorBackendDisconnected. This callback is only called during a 346 /// call to ::soundio_flush_events or ::soundio_wait_events. 347 /// If you do not supply a callback, the default will crash your program 348 /// with an error message. This callback is also called when the thread 349 /// that retrieves device information runs into an unrecoverable condition 350 /// such as running out of memory. 351 /// 352 /// Possible errors: 353 /// * #SoundIoErrorBackendDisconnected 354 /// * #SoundIoErrorNoMem 355 /// * #SoundIoErrorSystemResources 356 /// * #SoundIoErrorOpeningDevice - unexpected problem accessing device 357 /// information 358 void function (SoundIo*, int err) on_backend_disconnect; 359 /// Optional callback. Called from an unknown thread that you should not use 360 /// to call any soundio functions. You may use this to signal a condition 361 /// variable to wake up. Called when ::soundio_wait_events would be woken up. 362 void function (SoundIo*) on_events_signal; 363 364 /// Read-only. After calling ::soundio_connect or ::soundio_connect_backend, 365 /// this field tells which backend is currently connected. 366 SoundIoBackend current_backend; 367 368 /// Optional: Application name. 369 /// PulseAudio uses this for "application name". 370 /// JACK uses this for `client_name`. 371 /// Must not contain a colon (":"). 372 const(char)* app_name; 373 374 /// Optional: Real time priority warning. 375 /// This callback is fired when making thread real-time priority failed. By 376 /// default, it will print to stderr only the first time it is called 377 /// a message instructing the user how to configure their system to allow 378 /// real-time priority threads. This must be set to a function not NULL. 379 /// To silence the warning, assign this to a function that does nothing. 380 void function () emit_rtprio_warning; 381 382 /// Optional: JACK info callback. 383 /// By default, libsoundio sets this to an empty function in order to 384 /// silence stdio messages from JACK. You may override the behavior by 385 /// setting this to `NULL` or providing your own function. This is 386 /// registered with JACK regardless of whether ::soundio_connect_backend 387 /// succeeds. 388 void function (const(char)* msg) jack_info_callback; 389 /// Optional: JACK error callback. 390 /// See SoundIo::jack_info_callback 391 void function (const(char)* msg) jack_error_callback; 392 } 393 394 /// The size of this struct is not part of the API or ABI. 395 struct SoundIoDevice 396 { 397 /// Read-only. Set automatically. 398 SoundIo* soundio; 399 400 /// A string of bytes that uniquely identifies this device. 401 /// 402 /// If the same physical device supports both input and output, that makes 403 /// one SoundIoDevice for the input and one SoundIoDevice for the output. 404 /// In this case, the id of each SoundIoDevice will be the same, and 405 /// SoundIoDevice::aim will be different. Additionally, if the device 406 /// supports raw mode, there may be up to four devices with the same id: 407 /// one for each value of SoundIoDevice::is_raw and one for each value of 408 /// SoundIoDevice::aim. 409 char* id; 410 /// User-friendly UTF-8 encoded text to describe the device. 411 char* name; 412 413 /// Tells whether this device is an input device or an output device. 414 SoundIoDeviceAim aim; 415 416 /// Channel layouts are handled similarly to SoundIoDevice::formats. 417 /// 418 /// If this information is missing due to a SoundIoDevice::probe_error, 419 /// layouts will be NULL. It's OK to modify this data, for example calling 420 /// ::soundio_sort_channel_layouts on it. 421 /// Devices are guaranteed to have at least 1 channel layout. 422 SoundIoChannelLayout* layouts; 423 int layout_count; 424 /// See SoundIoDevice::current_format 425 SoundIoChannelLayout current_layout; 426 427 /// List of formats this device supports. See also 428 /// SoundIoDevice::current_format. 429 SoundIoFormat* formats; 430 /// How many formats are available in SoundIoDevice::formats. 431 int format_count; 432 /// A device is either a raw device or it is a virtual device that is 433 /// provided by a software mixing service such as dmix or PulseAudio (see 434 /// SoundIoDevice::is_raw). If it is a raw device, 435 /// current_format is meaningless; 436 /// the device has no current format until you open it. On the other hand, 437 /// if it is a virtual device, current_format describes the 438 /// destination sample format that your audio will be converted to. Or, 439 /// if you're the lucky first application to open the device, you might 440 /// cause the current_format to change to your format. 441 /// Generally, you want to ignore current_format and use 442 /// whatever format is most convenient 443 /// for you which is supported by the device, because when you are the only 444 /// application left, the mixer might decide to switch 445 /// current_format to yours. You can learn the supported formats via 446 /// formats and SoundIoDevice::format_count. If this information is missing 447 /// due to a probe error, formats will be `NULL`. If current_format is 448 /// unavailable, it will be set to #SoundIoFormatInvalid. 449 /// Devices are guaranteed to have at least 1 format available. 450 SoundIoFormat current_format; 451 452 /// Sample rate is the number of frames per second. 453 /// Sample rate is handled very similar to SoundIoDevice::formats. 454 /// If sample rate information is missing due to a probe error, the field 455 /// will be set to NULL. 456 /// Devices which have SoundIoDevice::probe_error set to #SoundIoErrorNone are 457 /// guaranteed to have at least 1 sample rate available. 458 SoundIoSampleRateRange* sample_rates; 459 /// How many sample rate ranges are available in 460 /// SoundIoDevice::sample_rates. 0 if sample rate information is missing 461 /// due to a probe error. 462 int sample_rate_count; 463 /// See SoundIoDevice::current_format 464 /// 0 if sample rate information is missing due to a probe error. 465 int sample_rate_current; 466 467 /// Software latency minimum in seconds. If this value is unknown or 468 /// irrelevant, it is set to 0.0. 469 /// For PulseAudio and WASAPI this value is unknown until you open a 470 /// stream. 471 double software_latency_min; 472 /// Software latency maximum in seconds. If this value is unknown or 473 /// irrelevant, it is set to 0.0. 474 /// For PulseAudio and WASAPI this value is unknown until you open a 475 /// stream. 476 double software_latency_max; 477 /// Software latency in seconds. If this value is unknown or 478 /// irrelevant, it is set to 0.0. 479 /// For PulseAudio and WASAPI this value is unknown until you open a 480 /// stream. 481 /// See SoundIoDevice::current_format 482 double software_latency_current; 483 484 /// Raw means that you are directly opening the hardware device and not 485 /// going through a proxy such as dmix, PulseAudio, or JACK. When you open a 486 /// raw device, other applications on the computer are not able to 487 /// simultaneously access the device. Raw devices do not perform automatic 488 /// resampling and thus tend to have fewer formats available. 489 bool is_raw; 490 491 /// Devices are reference counted. See ::soundio_device_ref and 492 /// ::soundio_device_unref. 493 int ref_count; 494 495 /// This is set to a SoundIoError representing the result of the device 496 /// probe. Ideally this will be SoundIoErrorNone in which case all the 497 /// fields of the device will be populated. If there is an error code here 498 /// then information about formats, sample rates, and channel layouts might 499 /// be missing. 500 /// 501 /// Possible errors: 502 /// * #SoundIoErrorOpeningDevice 503 /// * #SoundIoErrorNoMem 504 int probe_error; 505 } 506 507 /// The size of this struct is not part of the API or ABI. 508 struct SoundIoOutStream 509 { 510 extern(C): @nogc: nothrow: 511 /// Populated automatically when you call ::soundio_outstream_create. 512 SoundIoDevice* device; 513 514 /// Defaults to #SoundIoFormatFloat32NE, followed by the first one 515 /// supported. 516 SoundIoFormat format; 517 518 /// Sample rate is the number of frames per second. 519 /// Defaults to 48000 (and then clamped into range). 520 int sample_rate; 521 522 /// Defaults to Stereo, if available, followed by the first layout 523 /// supported. 524 SoundIoChannelLayout layout; 525 526 /// Ignoring hardware latency, this is the number of seconds it takes for 527 /// the last sample in a full buffer to be played. 528 /// After you call ::soundio_outstream_open, this value is replaced with the 529 /// actual software latency, as near to this value as possible. 530 /// On systems that support clearing the buffer, this defaults to a large 531 /// latency, potentially upwards of 2 seconds, with the understanding that 532 /// you will call ::soundio_outstream_clear_buffer when you want to reduce 533 /// the latency to 0. On systems that do not support clearing the buffer, 534 /// this defaults to a reasonable lower latency value. 535 /// 536 /// On backends with high latencies (such as 2 seconds), `frame_count_min` 537 /// will be 0, meaning you don't have to fill the entire buffer. In this 538 /// case, the large buffer is there if you want it; you only have to fill 539 /// as much as you want. On backends like JACK, `frame_count_min` will be 540 /// equal to `frame_count_max` and if you don't fill that many frames, you 541 /// will get glitches. 542 /// 543 /// If the device has unknown software latency min and max values, you may 544 /// still set this, but you might not get the value you requested. 545 /// For PulseAudio, if you set this value to non-default, it sets 546 /// `PA_STREAM_ADJUST_LATENCY` and is the value used for `maxlength` and 547 /// `tlength`. 548 /// 549 /// For JACK, this value is always equal to 550 /// SoundIoDevice::software_latency_current of the device. 551 double software_latency; 552 /// Core Audio and WASAPI only: current output Audio Unit volume. Float, 0.0-1.0. 553 float volume; 554 /// Defaults to NULL. Put whatever you want here. 555 void* userdata; 556 /// In this callback, you call ::soundio_outstream_begin_write and 557 /// ::soundio_outstream_end_write as many times as necessary to write 558 /// at minimum `frame_count_min` frames and at maximum `frame_count_max` 559 /// frames. `frame_count_max` will always be greater than 0. Note that you 560 /// should write as many frames as you can; `frame_count_min` might be 0 and 561 /// you can still get a buffer underflow if you always write 562 /// `frame_count_min` frames. 563 /// 564 /// For Dummy, ALSA, and PulseAudio, `frame_count_min` will be 0. For JACK 565 /// and CoreAudio `frame_count_min` will be equal to `frame_count_max`. 566 /// 567 /// The code in the supplied function must be suitable for real-time 568 /// execution. That means that it cannot call functions that might block 569 /// for a long time. This includes all I/O functions (disk, TTY, network), 570 /// malloc, free, printf, pthread_mutex_lock, sleep, wait, poll, select, 571 /// pthread_join, pthread_cond_wait, etc. 572 void function ( 573 SoundIoOutStream*, 574 int frame_count_min, 575 int frame_count_max) write_callback; 576 /// This optional callback happens when the sound device runs out of 577 /// buffered audio data to play. After this occurs, the outstream waits 578 /// until the buffer is full to resume playback. 579 /// This is called from the SoundIoOutStream::write_callback thread context. 580 void function (SoundIoOutStream*) underflow_callback; 581 /// Optional callback. `err` is always SoundIoErrorStreaming. 582 /// SoundIoErrorStreaming is an unrecoverable error. The stream is in an 583 /// invalid state and must be destroyed. 584 /// If you do not supply error_callback, the default callback will print 585 /// a message to stderr and then call `abort`. 586 /// This is called from the SoundIoOutStream::write_callback thread context. 587 void function (SoundIoOutStream*, int err) error_callback; 588 589 /// Optional: Name of the stream. Defaults to "SoundIoOutStream" 590 /// PulseAudio uses this for the stream name. 591 /// JACK uses this for the client name of the client that connects when you 592 /// open the stream. 593 /// WASAPI uses this for the session display name. 594 /// Must not contain a colon (":"). 595 const(char)* name; 596 597 /// Optional: Hint that this output stream is nonterminal. This is used by 598 /// JACK and it means that the output stream data originates from an input 599 /// stream. Defaults to `false`. 600 bool non_terminal_hint; 601 602 /// computed automatically when you call ::soundio_outstream_open 603 int bytes_per_frame; 604 /// computed automatically when you call ::soundio_outstream_open 605 int bytes_per_sample; 606 607 /// If setting the channel layout fails for some reason, this field is set 608 /// to an error code. Possible error codes are: 609 /// * #SoundIoErrorIncompatibleDevice 610 int layout_error; 611 } 612 613 /// The size of this struct is not part of the API or ABI. 614 struct SoundIoInStream 615 { 616 extern(C): @nogc: nothrow: 617 /// Populated automatically when you call ::soundio_outstream_create. 618 SoundIoDevice* device; 619 620 /// Defaults to #SoundIoFormatFloat32NE, followed by the first one 621 /// supported. 622 SoundIoFormat format; 623 624 /// Sample rate is the number of frames per second. 625 /// Defaults to max(sample_rate_min, min(sample_rate_max, 48000)) 626 int sample_rate; 627 628 /// Defaults to Stereo, if available, followed by the first layout 629 /// supported. 630 SoundIoChannelLayout layout; 631 632 /// Ignoring hardware latency, this is the number of seconds it takes for a 633 /// captured sample to become available for reading. 634 /// After you call ::soundio_instream_open, this value is replaced with the 635 /// actual software latency, as near to this value as possible. 636 /// A higher value means less CPU usage. Defaults to a large value, 637 /// potentially upwards of 2 seconds. 638 /// If the device has unknown software latency min and max values, you may 639 /// still set this, but you might not get the value you requested. 640 /// For PulseAudio, if you set this value to non-default, it sets 641 /// `PA_STREAM_ADJUST_LATENCY` and is the value used for `fragsize`. 642 /// For JACK, this value is always equal to 643 /// SoundIoDevice::software_latency_current 644 double software_latency; 645 646 /// Defaults to NULL. Put whatever you want here. 647 void* userdata; 648 /// In this function call ::soundio_instream_begin_read and 649 /// ::soundio_instream_end_read as many times as necessary to read at 650 /// minimum `frame_count_min` frames and at maximum `frame_count_max` 651 /// frames. If you return from read_callback without having read 652 /// `frame_count_min`, the frames will be dropped. `frame_count_max` is how 653 /// many frames are available to read. 654 /// 655 /// The code in the supplied function must be suitable for real-time 656 /// execution. That means that it cannot call functions that might block 657 /// for a long time. This includes all I/O functions (disk, TTY, network), 658 /// malloc, free, printf, pthread_mutex_lock, sleep, wait, poll, select, 659 /// pthread_join, pthread_cond_wait, etc. 660 void function (SoundIoInStream*, int frame_count_min, int frame_count_max) read_callback; 661 /// This optional callback happens when the sound device buffer is full, 662 /// yet there is more captured audio to put in it. 663 /// This is never fired for PulseAudio. 664 /// This is called from the SoundIoInStream::read_callback thread context. 665 void function (SoundIoInStream*) overflow_callback; 666 /// Optional callback. `err` is always SoundIoErrorStreaming. 667 /// SoundIoErrorStreaming is an unrecoverable error. The stream is in an 668 /// invalid state and must be destroyed. 669 /// If you do not supply `error_callback`, the default callback will print 670 /// a message to stderr and then abort(). 671 /// This is called from the SoundIoInStream::read_callback thread context. 672 void function (SoundIoInStream*, int err) error_callback; 673 674 /// Optional: Name of the stream. Defaults to "SoundIoInStream"; 675 /// PulseAudio uses this for the stream name. 676 /// JACK uses this for the client name of the client that connects when you 677 /// open the stream. 678 /// WASAPI uses this for the session display name. 679 /// Must not contain a colon (":"). 680 const(char)* name; 681 682 /// Optional: Hint that this input stream is nonterminal. This is used by 683 /// JACK and it means that the data received by the stream will be 684 /// passed on or made available to another stream. Defaults to `false`. 685 bool non_terminal_hint; 686 687 /// computed automatically when you call ::soundio_instream_open 688 int bytes_per_frame; 689 /// computed automatically when you call ::soundio_instream_open 690 int bytes_per_sample; 691 692 /// If setting the channel layout fails for some reason, this field is set 693 /// to an error code. Possible error codes are: #SoundIoErrorIncompatibleDevice 694 int layout_error; 695 } 696 697 /// See also ::soundio_version_major, ::soundio_version_minor, ::soundio_version_patch 698 const(char)* soundio_version_string (); 699 /// See also ::soundio_version_string, ::soundio_version_minor, ::soundio_version_patch 700 int soundio_version_major (); 701 /// See also ::soundio_version_major, ::soundio_version_string, ::soundio_version_patch 702 int soundio_version_minor (); 703 /// See also ::soundio_version_major, ::soundio_version_minor, ::soundio_version_string 704 int soundio_version_patch (); 705 706 /// Create a SoundIo context. You may create multiple instances of this to 707 /// connect to multiple backends. Sets all fields to defaults. 708 /// Returns `NULL` if and only if memory could not be allocated. 709 /// See also ::soundio_destroy 710 SoundIo* soundio_create (); 711 /// ditto 712 void soundio_destroy (SoundIo* soundio); 713 714 /// Tries ::soundio_connect_backend on all available backends in order. 715 /// Possible errors: 716 /// * #SoundIoErrorInvalid - already connected 717 /// * #SoundIoErrorNoMem 718 /// * #SoundIoErrorSystemResources 719 /// * #SoundIoErrorNoSuchClient - when JACK returns `JackNoSuchClient` 720 /// See also ::soundio_disconnect 721 int soundio_connect (SoundIo* soundio); 722 /// Instead of calling ::soundio_connect you may call this function to try a 723 /// specific backend. 724 /// Possible errors: 725 /// * #SoundIoErrorInvalid - already connected or invalid backend parameter 726 /// * #SoundIoErrorNoMem 727 /// * #SoundIoErrorBackendUnavailable - backend was not compiled in 728 /// * #SoundIoErrorSystemResources 729 /// * #SoundIoErrorNoSuchClient - when JACK returns `JackNoSuchClient` 730 /// * #SoundIoErrorInitAudioBackend - requested `backend` is not active 731 /// * #SoundIoErrorBackendDisconnected - backend disconnected while connecting 732 /// See also ::soundio_disconnect 733 int soundio_connect_backend (SoundIo* soundio, SoundIoBackend backend); 734 /// ditto 735 void soundio_disconnect (SoundIo* soundio); 736 737 /// Get a string representation of a #SoundIoError 738 const(char)* soundio_strerror (int error); 739 /// Get a string representation of a #SoundIoBackend 740 const(char)* soundio_backend_name (SoundIoBackend backend); 741 742 /// Returns the number of available backends. 743 int soundio_backend_count (SoundIo* soundio); 744 /// get the available backend at the specified index 745 /// (0 <= index < ::soundio_backend_count) 746 SoundIoBackend soundio_get_backend (SoundIo* soundio, int index); 747 748 /// Returns whether libsoundio was compiled with backend. 749 bool soundio_have_backend (SoundIoBackend backend); 750 751 /// Atomically update information for all connected devices. Note that calling 752 /// this function merely flips a pointer; the actual work of collecting device 753 /// information is done elsewhere. It is performant to call this function many 754 /// times per second. 755 /// 756 /// When you call this, the following callbacks might be called: 757 /// * SoundIo::on_devices_change 758 /// * SoundIo::on_backend_disconnect 759 /// This is the only time those callbacks can be called. 760 /// 761 /// This must be called from the same thread as the thread in which you call 762 /// these functions: 763 /// * ::soundio_input_device_count 764 /// * ::soundio_output_device_count 765 /// * ::soundio_get_input_device 766 /// * ::soundio_get_output_device 767 /// * ::soundio_default_input_device_index 768 /// * ::soundio_default_output_device_index 769 /// 770 /// Note that if you do not care about learning about updated devices, you 771 /// might call this function only once ever and never call 772 /// ::soundio_wait_events. 773 void soundio_flush_events (SoundIo* soundio); 774 775 /// This function calls ::soundio_flush_events then blocks until another event 776 /// is ready or you call ::soundio_wakeup. Be ready for spurious wakeups. 777 void soundio_wait_events (SoundIo* soundio); 778 779 /// Makes ::soundio_wait_events stop blocking. 780 void soundio_wakeup (SoundIo* soundio); 781 782 /// If necessary you can manually trigger a device rescan. Normally you will 783 /// not ever have to call this function, as libsoundio listens to system events 784 /// for device changes and responds to them by rescanning devices and preparing 785 /// the new device information for you to be atomically replaced when you call 786 /// ::soundio_flush_events. However you might run into cases where you want to 787 /// force trigger a device rescan, for example if an ALSA device has a 788 /// SoundIoDevice::probe_error. 789 /// 790 /// After you call this you still have to use ::soundio_flush_events or 791 /// ::soundio_wait_events and then wait for the 792 /// SoundIo::on_devices_change callback. 793 /// 794 /// This can be called from any thread context except for 795 /// SoundIoOutStream::write_callback and SoundIoInStream::read_callback 796 void soundio_force_device_scan (SoundIo* soundio); 797 798 // Channel Layouts 799 800 /// Returns whether the channel count field and each channel id matches in 801 /// the supplied channel layouts. 802 bool soundio_channel_layout_equal ( 803 const(SoundIoChannelLayout)* a, 804 const(SoundIoChannelLayout)* b); 805 806 const(char)* soundio_get_channel_name (SoundIoChannelId id); 807 /// Given UTF-8 encoded text which is the name of a channel such as 808 /// "Front Left", "FL", or "front-left", return the corresponding 809 /// SoundIoChannelId. Returns SoundIoChannelIdInvalid for no match. 810 SoundIoChannelId soundio_parse_channel_id (const(char)* str, int str_len); 811 812 /// Returns the number of builtin channel layouts. 813 int soundio_channel_layout_builtin_count (); 814 /// Returns a builtin channel layout. 0 <= `index` < ::soundio_channel_layout_builtin_count 815 /// 816 /// Although `index` is of type `int`, it should be a valid 817 /// #SoundIoChannelLayoutId enum value. 818 const(SoundIoChannelLayout)* soundio_channel_layout_get_builtin (int index); 819 820 /// Get the default builtin channel layout for the given number of channels. 821 const(SoundIoChannelLayout)* soundio_channel_layout_get_default (int channel_count); 822 823 /// Return the index of `channel` in `layout`, or `-1` if not found. 824 int soundio_channel_layout_find_channel ( 825 const(SoundIoChannelLayout)* layout, 826 SoundIoChannelId channel); 827 828 /// Populates the name field of layout if it matches a builtin one. 829 /// returns whether it found a match 830 bool soundio_channel_layout_detect_builtin (SoundIoChannelLayout* layout); 831 832 /// Iterates over preferred_layouts. Returns the first channel layout in 833 /// preferred_layouts which matches one of the channel layouts in 834 /// available_layouts. Returns NULL if none matches. 835 const(SoundIoChannelLayout)* soundio_best_matching_channel_layout ( 836 const(SoundIoChannelLayout)* preferred_layouts, 837 int preferred_layout_count, 838 const(SoundIoChannelLayout)* available_layouts, 839 int available_layout_count); 840 841 /// Sorts by channel count, descending. 842 void soundio_sort_channel_layouts (SoundIoChannelLayout* layouts, int layout_count); 843 844 // Sample Formats 845 846 /// Returns -1 on invalid format. 847 int soundio_get_bytes_per_sample (SoundIoFormat format); 848 849 /// A frame is one sample per channel. 850 pragma(inline, true) int soundio_get_bytes_per_frame(SoundIoFormat format, int channel_count) { 851 return soundio_get_bytes_per_sample(format) * channel_count; 852 } 853 854 /// Sample rate is the number of frames per second. 855 pragma(inline, true) int soundio_get_bytes_per_second( 856 SoundIoFormat format, int channel_count, int sample_rate 857 ) { 858 return soundio_get_bytes_per_frame(format, channel_count) * sample_rate; 859 } 860 861 /// Returns string representation of `format`. 862 const(char)* soundio_format_string (SoundIoFormat format); 863 864 // Devices 865 866 /// When you call ::soundio_flush_events, a snapshot of all device state is 867 /// saved and these functions merely access the snapshot data. When you want 868 /// to check for new devices, call ::soundio_flush_events. Or you can call 869 /// ::soundio_wait_events to block until devices change. If an error occurs 870 /// scanning devices in a background thread, SoundIo::on_backend_disconnect is called 871 /// with the error code. 872 873 /// Get the number of input devices. 874 /// Returns -1 if you never called ::soundio_flush_events. 875 int soundio_input_device_count (SoundIo* soundio); 876 /// Get the number of output devices. 877 /// Returns -1 if you never called ::soundio_flush_events. 878 int soundio_output_device_count (SoundIo* soundio); 879 880 /// Always returns a device. Call ::soundio_device_unref when done. 881 /// `index` must be 0 <= index < ::soundio_input_device_count 882 /// Returns NULL if you never called ::soundio_flush_events or if you provide 883 /// invalid parameter values. 884 SoundIoDevice* soundio_get_input_device (SoundIo* soundio, int index); 885 /// Always returns a device. Call ::soundio_device_unref when done. 886 /// `index` must be 0 <= index < ::soundio_output_device_count 887 /// Returns NULL if you never called ::soundio_flush_events or if you provide 888 /// invalid parameter values. 889 SoundIoDevice* soundio_get_output_device (SoundIo* soundio, int index); 890 891 /// returns the index of the default input device 892 /// returns -1 if there are no devices or if you never called 893 /// ::soundio_flush_events. 894 int soundio_default_input_device_index (SoundIo* soundio); 895 896 /// returns the index of the default output device 897 /// returns -1 if there are no devices or if you never called 898 /// ::soundio_flush_events. 899 int soundio_default_output_device_index (SoundIo* soundio); 900 901 /// Add 1 to the reference count of `device`. 902 void soundio_device_ref (SoundIoDevice* device); 903 /// Remove 1 to the reference count of `device`. Clean up if it was the last 904 /// reference. 905 void soundio_device_unref (SoundIoDevice* device); 906 907 /// Return `true` if and only if the devices have the same SoundIoDevice::id, 908 /// SoundIoDevice::is_raw, and SoundIoDevice::aim are the same. 909 bool soundio_device_equal (const(SoundIoDevice)* a, const(SoundIoDevice)* b); 910 911 /// Sorts channel layouts by channel count, descending. 912 void soundio_device_sort_channel_layouts (SoundIoDevice* device); 913 914 /// Convenience function. Returns whether `format` is included in the device's 915 /// supported formats. 916 bool soundio_device_supports_format ( 917 SoundIoDevice* device, 918 SoundIoFormat format); 919 920 /// Convenience function. Returns whether `layout` is included in the device's 921 /// supported channel layouts. 922 bool soundio_device_supports_layout ( 923 SoundIoDevice* device, 924 const(SoundIoChannelLayout)* layout); 925 926 /// Convenience function. Returns whether `sample_rate` is included in the 927 /// device's supported sample rates. 928 bool soundio_device_supports_sample_rate ( 929 SoundIoDevice* device, 930 int sample_rate); 931 932 /// Convenience function. Returns the available sample rate nearest to 933 /// `sample_rate`, rounding up. 934 int soundio_device_nearest_sample_rate (SoundIoDevice* device, int sample_rate); 935 936 // Output Streams 937 /// Allocates memory and sets defaults. Next you should fill out the struct fields 938 /// and then call ::soundio_outstream_open. Sets all fields to defaults. 939 /// Returns `NULL` if and only if memory could not be allocated. 940 /// See also ::soundio_outstream_destroy 941 SoundIoOutStream* soundio_outstream_create (SoundIoDevice* device); 942 /// You may not call this function from the SoundIoOutStream::write_callback thread context. 943 void soundio_outstream_destroy (SoundIoOutStream* outstream); 944 945 /// After you call this function, SoundIoOutStream::software_latency is set to 946 /// the correct value. 947 /// 948 /// The next thing to do is call ::soundio_outstream_start. 949 /// If this function returns an error, the outstream is in an invalid state and 950 /// you must call ::soundio_outstream_destroy on it. 951 /// 952 /// Possible errors: 953 /// * #SoundIoErrorInvalid 954 /// * SoundIoDevice::aim is not #SoundIoDeviceAimOutput 955 /// * SoundIoOutStream::format is not valid 956 /// * SoundIoOutStream::channel_count is greater than #SOUNDIO_MAX_CHANNELS 957 /// * #SoundIoErrorNoMem 958 /// * #SoundIoErrorOpeningDevice 959 /// * #SoundIoErrorBackendDisconnected 960 /// * #SoundIoErrorSystemResources 961 /// * #SoundIoErrorNoSuchClient - when JACK returns `JackNoSuchClient` 962 /// * #SoundIoErrorIncompatibleBackend - SoundIoOutStream::channel_count is 963 /// greater than the number of channels the backend can handle. 964 /// * #SoundIoErrorIncompatibleDevice - stream parameters requested are not 965 /// compatible with the chosen device. 966 int soundio_outstream_open (SoundIoOutStream* outstream); 967 968 /// After you call this function, SoundIoOutStream::write_callback will be called. 969 /// 970 /// This function might directly call SoundIoOutStream::write_callback. 971 /// 972 /// Possible errors: 973 /// * #SoundIoErrorStreaming 974 /// * #SoundIoErrorNoMem 975 /// * #SoundIoErrorSystemResources 976 /// * #SoundIoErrorBackendDisconnected 977 int soundio_outstream_start (SoundIoOutStream* outstream); 978 979 /// Call this function when you are ready to begin writing to the device buffer. 980 /// * `outstream` - (in) The output stream you want to write to. 981 /// * `areas` - (out) The memory addresses you can write data to, one per 982 /// channel. It is OK to modify the pointers if that helps you iterate. 983 /// * `frame_count` - (in/out) Provide the number of frames you want to write. 984 /// Returned will be the number of frames you can actually write, which is 985 /// also the number of frames that will be written when you call 986 /// ::soundio_outstream_end_write. The value returned will always be less 987 /// than or equal to the value provided. 988 /// It is your responsibility to call this function exactly as many times as 989 /// necessary to meet the `frame_count_min` and `frame_count_max` criteria from 990 /// SoundIoOutStream::write_callback. 991 /// You must call this function only from the SoundIoOutStream::write_callback thread context. 992 /// After calling this function, write data to `areas` and then call 993 /// ::soundio_outstream_end_write. 994 /// If this function returns an error, do not call ::soundio_outstream_end_write. 995 /// 996 /// Possible errors: 997 /// * #SoundIoErrorInvalid 998 /// * `*frame_count` <= 0 999 /// * `*frame_count` < `frame_count_min` or `*frame_count` > `frame_count_max` 1000 /// * function called too many times without respecting `frame_count_max` 1001 /// * #SoundIoErrorStreaming 1002 /// * #SoundIoErrorUnderflow - an underflow caused this call to fail. You might 1003 /// also get a SoundIoOutStream::underflow_callback, and you might not get 1004 /// this error code when an underflow occurs. Unlike #SoundIoErrorStreaming, 1005 /// the outstream is still in a valid state and streaming can continue. 1006 /// * #SoundIoErrorIncompatibleDevice - in rare cases it might just now 1007 /// be discovered that the device uses non-byte-aligned access, in which 1008 /// case this error code is returned. 1009 int soundio_outstream_begin_write ( 1010 SoundIoOutStream* outstream, 1011 SoundIoChannelArea** areas, 1012 int* frame_count); 1013 1014 /// Commits the write that you began with ::soundio_outstream_begin_write. 1015 /// You must call this function only from the SoundIoOutStream::write_callback thread context. 1016 /// 1017 /// Possible errors: 1018 /// * #SoundIoErrorStreaming 1019 /// * #SoundIoErrorUnderflow - an underflow caused this call to fail. You might 1020 /// also get a SoundIoOutStream::underflow_callback, and you might not get 1021 /// this error code when an underflow occurs. Unlike #SoundIoErrorStreaming, 1022 /// the outstream is still in a valid state and streaming can continue. 1023 int soundio_outstream_end_write (SoundIoOutStream* outstream); 1024 1025 /// Clears the output stream buffer. 1026 /// This function can be called from any thread. 1027 /// This function can be called regardless of whether the outstream is paused 1028 /// or not. 1029 /// Some backends do not support clearing the buffer. On these backends this 1030 /// function will return SoundIoErrorIncompatibleBackend. 1031 /// Some devices do not support clearing the buffer. On these devices this 1032 /// function might return SoundIoErrorIncompatibleDevice. 1033 /// Possible errors: 1034 /// 1035 /// * #SoundIoErrorStreaming 1036 /// * #SoundIoErrorIncompatibleBackend 1037 /// * #SoundIoErrorIncompatibleDevice 1038 int soundio_outstream_clear_buffer (SoundIoOutStream* outstream); 1039 1040 /// If the underlying backend and device support pausing, this pauses the 1041 /// stream. SoundIoOutStream::write_callback may be called a few more times if 1042 /// the buffer is not full. 1043 /// Pausing might put the hardware into a low power state which is ideal if your 1044 /// software is silent for some time. 1045 /// This function may be called from any thread context, including 1046 /// SoundIoOutStream::write_callback. 1047 /// Pausing when already paused or unpausing when already unpaused has no 1048 /// effect and returns #SoundIoErrorNone. 1049 /// 1050 /// Possible errors: 1051 /// * #SoundIoErrorBackendDisconnected 1052 /// * #SoundIoErrorStreaming 1053 /// * #SoundIoErrorIncompatibleDevice - device does not support 1054 /// pausing/unpausing. This error code might not be returned even if the 1055 /// device does not support pausing/unpausing. 1056 /// * #SoundIoErrorIncompatibleBackend - backend does not support 1057 /// pausing/unpausing. 1058 /// * #SoundIoErrorInvalid - outstream not opened and started 1059 int soundio_outstream_pause (SoundIoOutStream* outstream, bool pause); 1060 1061 /// Obtain the total number of seconds that the next frame written after the 1062 /// last frame written with ::soundio_outstream_end_write will take to become 1063 /// audible. This includes both software and hardware latency. In other words, 1064 /// if you call this function directly after calling ::soundio_outstream_end_write, 1065 /// this gives you the number of seconds that the next frame written will take 1066 /// to become audible. 1067 /// 1068 /// This function must be called only from within SoundIoOutStream::write_callback. 1069 /// 1070 /// Possible errors: 1071 /// * #SoundIoErrorStreaming 1072 int soundio_outstream_get_latency ( 1073 SoundIoOutStream* outstream, 1074 double* out_latency); 1075 1076 int soundio_outstream_set_volume (SoundIoOutStream* outstream, double volume); 1077 1078 // Input Streams 1079 /// Allocates memory and sets defaults. Next you should fill out the struct fields 1080 /// and then call ::soundio_instream_open. Sets all fields to defaults. 1081 /// Returns `NULL` if and only if memory could not be allocated. 1082 /// See also ::soundio_instream_destroy 1083 SoundIoInStream* soundio_instream_create (SoundIoDevice* device); 1084 /// You may not call this function from SoundIoInStream::read_callback. 1085 void soundio_instream_destroy (SoundIoInStream* instream); 1086 1087 /// After you call this function, SoundIoInStream::software_latency is set to the correct 1088 /// value. 1089 /// The next thing to do is call ::soundio_instream_start. 1090 /// If this function returns an error, the instream is in an invalid state and 1091 /// you must call ::soundio_instream_destroy on it. 1092 /// 1093 /// Possible errors: 1094 /// * #SoundIoErrorInvalid 1095 /// * device aim is not #SoundIoDeviceAimInput 1096 /// * format is not valid 1097 /// * requested layout channel count > #SOUNDIO_MAX_CHANNELS 1098 /// * #SoundIoErrorOpeningDevice 1099 /// * #SoundIoErrorNoMem 1100 /// * #SoundIoErrorBackendDisconnected 1101 /// * #SoundIoErrorSystemResources 1102 /// * #SoundIoErrorNoSuchClient 1103 /// * #SoundIoErrorIncompatibleBackend 1104 /// * #SoundIoErrorIncompatibleDevice 1105 int soundio_instream_open (SoundIoInStream* instream); 1106 1107 /// After you call this function, SoundIoInStream::read_callback will be called. 1108 /// 1109 /// Possible errors: 1110 /// * #SoundIoErrorBackendDisconnected 1111 /// * #SoundIoErrorStreaming 1112 /// * #SoundIoErrorOpeningDevice 1113 /// * #SoundIoErrorSystemResources 1114 int soundio_instream_start (SoundIoInStream* instream); 1115 1116 /// Call this function when you are ready to begin reading from the device 1117 /// buffer. 1118 /// * `instream` - (in) The input stream you want to read from. 1119 /// * `areas` - (out) The memory addresses you can read data from. It is OK 1120 /// to modify the pointers if that helps you iterate. There might be a "hole" 1121 /// in the buffer. To indicate this, `areas` will be `NULL` and `frame_count` 1122 /// tells how big the hole is in frames. 1123 /// * `frame_count` - (in/out) - Provide the number of frames you want to read; 1124 /// returns the number of frames you can actually read. The returned value 1125 /// will always be less than or equal to the provided value. If the provided 1126 /// value is less than `frame_count_min` from SoundIoInStream::read_callback this function 1127 /// returns with #SoundIoErrorInvalid. 1128 /// It is your responsibility to call this function no more and no fewer than the 1129 /// correct number of times according to the `frame_count_min` and 1130 /// `frame_count_max` criteria from SoundIoInStream::read_callback. 1131 /// You must call this function only from the SoundIoInStream::read_callback thread context. 1132 /// After calling this function, read data from `areas` and then use 1133 /// ::soundio_instream_end_read` to actually remove the data from the buffer 1134 /// and move the read index forward. ::soundio_instream_end_read should not be 1135 /// called if the buffer is empty (`frame_count` == 0), but it should be called 1136 /// if there is a hole. 1137 /// 1138 /// Possible errors: 1139 /// * #SoundIoErrorInvalid 1140 /// * `*frame_count` < `frame_count_min` or `*frame_count` > `frame_count_max` 1141 /// * #SoundIoErrorStreaming 1142 /// * #SoundIoErrorIncompatibleDevice - in rare cases it might just now 1143 /// be discovered that the device uses non-byte-aligned access, in which 1144 /// case this error code is returned. 1145 int soundio_instream_begin_read ( 1146 SoundIoInStream* instream, 1147 SoundIoChannelArea** areas, 1148 int* frame_count); 1149 /// This will drop all of the frames from when you called 1150 /// ::soundio_instream_begin_read. 1151 /// You must call this function only from the SoundIoInStream::read_callback thread context. 1152 /// You must call this function only after a successful call to 1153 /// ::soundio_instream_begin_read. 1154 /// 1155 /// Possible errors: 1156 /// * #SoundIoErrorStreaming 1157 int soundio_instream_end_read (SoundIoInStream* instream); 1158 1159 /// If the underyling device supports pausing, this pauses the stream and 1160 /// prevents SoundIoInStream::read_callback from being called. Otherwise this returns 1161 /// #SoundIoErrorIncompatibleDevice. 1162 /// This function may be called from any thread. 1163 /// Pausing when already paused or unpausing when already unpaused has no 1164 /// effect and always returns #SoundIoErrorNone. 1165 /// 1166 /// Possible errors: 1167 /// * #SoundIoErrorBackendDisconnected 1168 /// * #SoundIoErrorStreaming 1169 /// * #SoundIoErrorIncompatibleDevice - device does not support pausing/unpausing 1170 int soundio_instream_pause (SoundIoInStream* instream, bool pause); 1171 1172 /// Obtain the number of seconds that the next frame of sound being 1173 /// captured will take to arrive in the buffer, plus the amount of time that is 1174 /// represented in the buffer. This includes both software and hardware latency. 1175 /// 1176 /// This function must be called only from within SoundIoInStream::read_callback. 1177 /// 1178 /// Possible errors: 1179 /// * #SoundIoErrorStreaming 1180 int soundio_instream_get_latency ( 1181 SoundIoInStream* instream, 1182 double* out_latency); 1183 1184 struct SoundIoRingBuffer; 1185 1186 /// A ring buffer is a single-reader single-writer lock-free fixed-size queue. 1187 /// libsoundio ring buffers use memory mapping techniques to enable a 1188 /// contiguous buffer when reading or writing across the boundary of the ring 1189 /// buffer's capacity. 1190 /// `requested_capacity` in bytes. 1191 /// Returns `NULL` if and only if memory could not be allocated. 1192 /// Use ::soundio_ring_buffer_capacity to get the actual capacity, which might 1193 /// be greater for alignment purposes. 1194 /// See also ::soundio_ring_buffer_destroy 1195 SoundIoRingBuffer* soundio_ring_buffer_create (SoundIo* soundio, int requested_capacity); 1196 /// ditto 1197 void soundio_ring_buffer_destroy (SoundIoRingBuffer* ring_buffer); 1198 1199 /// When you create a ring buffer, capacity might be more than the requested 1200 /// capacity for alignment purposes. This function returns the actual capacity. 1201 int soundio_ring_buffer_capacity (SoundIoRingBuffer* ring_buffer); 1202 1203 /// Do not write more than capacity. 1204 char* soundio_ring_buffer_write_ptr (SoundIoRingBuffer* ring_buffer); 1205 /// `count` in bytes. 1206 void soundio_ring_buffer_advance_write_ptr (SoundIoRingBuffer* ring_buffer, int count); 1207 1208 /// Do not read more than capacity. 1209 char* soundio_ring_buffer_read_ptr (SoundIoRingBuffer* ring_buffer); 1210 /// `count` in bytes. 1211 void soundio_ring_buffer_advance_read_ptr (SoundIoRingBuffer* ring_buffer, int count); 1212 1213 /// Returns: how many bytes of the buffer is used, ready for reading. 1214 int soundio_ring_buffer_fill_count (SoundIoRingBuffer* ring_buffer); 1215 1216 /// Returns: how many bytes of the buffer is free, ready for writing. 1217 int soundio_ring_buffer_free_count (SoundIoRingBuffer* ring_buffer); 1218 1219 /// Must be called by the writer. 1220 void soundio_ring_buffer_clear (SoundIoRingBuffer* ring_buffer); 1221