1.\" $OpenBSD: sio_open.3,v 1.21 2009/07/25 11:15:56 ratchov Exp $ 2.\" 3.\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 25 2009 $ 18.Dt SIO_OPEN 3 19.Os 20.Sh NAME 21.Nm sio_open , 22.Nm sio_close , 23.Nm sio_setpar , 24.Nm sio_getpar , 25.Nm sio_getcap , 26.Nm sio_start , 27.Nm sio_stop , 28.Nm sio_read , 29.Nm sio_write , 30.Nm sio_onmove , 31.Nm sio_nfds , 32.Nm sio_pollfd , 33.Nm sio_revents , 34.Nm sio_eof , 35.Nm sio_setvol , 36.Nm sio_onvol , 37.Nm sio_initpar 38.Nd interface to bidirectional audio streams 39.Sh SYNOPSIS 40.Fd #include <sndio.h> 41.Ft "struct sio_hdl *" 42.Fn "sio_open" "const char *name" "unsigned mode" "int nbio_flag" 43.Ft "void" 44.Fn "sio_close" "struct sio_hdl *hdl" 45.Ft "int" 46.Fn "sio_setpar" "struct sio_hdl *hdl" "struct sio_par *par" 47.Ft "int" 48.Fn "sio_getpar" "struct sio_hdl *hdl" "struct sio_par *par" 49.Ft "int" 50.Fn "sio_getcap" "struct sio_hdl *hdl" "struct sio_cap *cap" 51.Ft "int" 52.Fn "sio_start" "struct sio_hdl *hdl" 53.Ft "int" 54.Fn "sio_stop" "struct sio_hdl *hdl" 55.Ft "size_t" 56.Fn "sio_read" "struct sio_hdl *hdl" "void *addr" "size_t nbytes" 57.Ft "size_t" 58.Fn "sio_write" "struct sio_hdl *hdl" "const void *addr" "size_t nbytes" 59.Ft "void" 60.Fn "sio_onmove" "struct sio_hdl *hdl" "void (*cb)(void *arg, int delta)" "void *arg" 61.Ft "int" 62.Fn "sio_nfds" "struct sio_hdl *hdl" 63.Ft "int" 64.Fn "sio_pollfd" "struct sio_hdl *hdl" "struct pollfd *pfd" "int events" 65.Ft "int" 66.Fn "sio_revents" "struct sio_hdl *hdl" "struct pollfd *pfd" 67.Ft "int" 68.Fn "sio_eof" "struct sio_hdl *hdl" 69.Ft "int" 70.Fn "sio_setvol" "struct sio_hdl *hdl" "unsigned vol" 71.Ft "void" 72.Fn "sio_onvol" "struct sio_hdl *hdl" "void (*cb)(void *arg, unsigned vol)" "void *arg" 73.Ft "void" 74.Fn "sio_initpar" "struct sio_par *par" 75.\"Fd #define SIO_BPS(bits) 76.\"Fd #define SIO_LE_NATIVE 77.Sh DESCRIPTION 78The 79.Nm sndio 80library allows user processes to access 81.Xr audio 4 82hardware and the 83.Xr aucat 1 84audio server in a uniform way. 85It supports full-duplex operation, and when 86used with the 87.Xr aucat 1 88server it supports resampling and format 89conversions on the fly. 90.Ss Opening and closing an audio stream 91First the application must call the 92.Fn sio_open 93function to obtain a handle representing the newly created stream; 94later it will be passed as the 95.Ar hdl 96argument of most other functions. 97The 98.Fn sio_open 99function first tries to connect to the 100.Xr aucat 1 101audio server. 102If that fails, it then tries to use the 103.Xr audio 4 104hardware device. 105The 106.Ar name 107parameter gives the device string discussed in 108.Xr sndio 7 . 109In most cases it should be set to NULL to allow 110the user to select it using the 111.Ev AUDIODEVICE 112environment variable. 113.Pp 114The 115.Ar mode 116parameter gives the direction of the stream. 117The following are supported: 118.Bl -tag -width "SIO_PLAY | SIO_REC" 119.It SIO_PLAY 120The stream is play-only; data written to the stream will be played 121by the hardware. 122.It SIO_REC 123The stream is record-only; recorded samples by the hardware 124must be read from the stream. 125.It SIO_PLAY | SIO_REC 126The stream plays and records synchronously; this means that 127the n-th recorded sample was physically sampled exactly when 128the n-th played sample was actually played. 129.El 130.Pp 131If the 132.Ar nbio_flag 133argument is true (i.e. non-zero), then the 134.Fn sio_read 135and 136.Fn sio_write 137functions (see below) will be non-blocking. 138.Pp 139The 140.Fn sio_close 141function closes the stream and frees all allocated resources 142associated with the 143.Nm libsndio 144handle. 145.Ss Negotiating audio parameters 146Audio streams always use linear interleaved encoding. 147A frame consists of one sample for each channel in the stream. 148For example, a 16-bit stereo stream has two samples per frame 149and, typically, two bytes per sample (thus 4 bytes per frame). 150.Pp 151The set of parameters of the stream that can be controlled 152is given by the following structure: 153.Bd -literal 154struct sio_par { 155 unsigned bits; /* bits per sample */ 156 unsigned bps; /* bytes per sample */ 157 unsigned sig; /* 1 = signed, 0 = unsigned */ 158 unsigned le; /* 1 = LE, 0 = BE byte order */ 159 unsigned msb; /* 1 = MSB, 0 = LSB aligned */ 160 unsigned rchan; /* number channels for recording */ 161 unsigned pchan; /* number channels for playback */ 162 unsigned rate; /* frames per second */ 163 unsigned appbufsz; /* minimum buffer size without xruns */ 164 unsigned bufsz; /* end-to-end buffer size (read-only) */ 165 unsigned round; /* optimal buffer size divisor */ 166#define SIO_IGNORE 0 /* pause during xrun */ 167#define SIO_SYNC 1 /* resync after xrun */ 168#define SIO_ERROR 2 /* terminate on xrun */ 169 unsigned xrun; /* what to do on overrun/underrun */ 170}; 171.Ed 172.Pp 173The parameters are as follows: 174.Bl -tag -width "appbufsz" 175.It Va bits 176Number of bits per sample: must be between 1 and 32. 177.It Va bps 178Bytes per samples; if specified, it must be large enough to hold all bits. 179By default it's set to the smallest power of two large enough to hold 180.Va bits . 181.It Va sig 182If set (i.e. non-zero) then the samples are signed, else unsigned. 183.It Va le 184If set, then the byte order is little endian, else big endian; 185it's meaningful only if 186.Va bps 187\*(Gt 1. 188.It Va msb 189If set, then the 190.Va bits 191bits are aligned in the packet to the most significant bit 192(i.e. lower bits are padded), 193else to the least significant bit 194(i.e. higher bits are padded); 195it's meaningful only if 196.Va bits 197\*(Lt 198.Va bps 199* 8. 200.It Va rchan 201The number of recorded channels; meaningful only if 202.Va SIO_REC 203mode was selected. 204.It Va pchan 205The number of played channels; meaningful only if 206.Va SIO_PLAY 207mode was selected. 208.It Va rate 209The sampling frequency in Hz. 210.It Va bufsz 211The maximum number of frames that may be buffered. 212This parameter takes into account any buffers, and 213can be used for latency calculations. 214It is read-only. 215.It Va appbufsz 216Size of the buffer in frames the application must maintain non empty 217(on the play end) or non full (on the record end) by calling 218.Fn sio_write 219or 220.Fn sio_read 221fast enough to avoid overrun or underrun conditions. 222The audio subsystem may use additional buffering, thus this 223parameter cannot be used for latency calculations 224.It Va round 225Optimal number of frames that the application buffers 226should be a multiple of, to get best performance. 227Applications can use this parameter to round their block size. 228.It Va xrun 229The action when the client doesn't accept 230recorded data or doesn't provide data to play fast enough; 231it can be set to one of the 232.Va SIO_IGNORE , 233.Va SIO_SYNC 234or 235.Va SIO_ERROR 236constants. 237.El 238.Pp 239There are two approaches to negotiate parameters of the stream: 240.Bl -bullet 241.It 242Advanced applications may use native parameters of 243the audio subsystem. 244This is the best approach from a performance point of view 245since it involves no extra format conversions. 246The 247.Fn sio_getcap , 248described below, 249can be used to get the list of native parameter sets and then 250.Fn sio_initpar 251and 252.Fn sio_setpar 253can be used to select a working set. 254.It 255Simpler applications that do not have performance constraints may set up 256the audio subsystem to use their own parameters. 257The 258.Va sio_par 259structure must be initialized using the 260.Fn sio_initpar 261function, filled with the desired parameters and 262the 263.Fn sio_setpar 264function must be called. 265Finally, the 266.Fn sio_getpar 267function should be used to ensure that parameters were actually 268accepted. 269Sometimes the rate set can be slightly different to what was requested. 270A difference of about 0.5% is not audible and should be ignored. 271.El 272.Pp 273If 274.Nm libsndio 275is used to connect to the 276.Xr aucat 1 277server, a transparent emulation layer will 278automatically be set up, and in this case any 279parameters are supported. 280.Pp 281To ease filling the 282.Va sio_par 283structure, the 284following macros can be used: 285.Bl -tag -width "SIO_BPS(bits)" 286.It "SIO_BPS(bits)" 287Return the smallest value for 288.Va bps 289that is a power of two and that is large enough to 290hold 291.Va bits . 292.It "SIO_LE_NATIVE" 293Can be used to set the 294.Va le 295parameter when native byte order is required. 296.El 297.Pp 298Note that (once initialized with the 299.Fn sio_initpar 300function), not all fields of the 301.Va sio_par 302structure must be filled; it is recommended to fill only 303the required parameters, as other ones will default to 304reasonable values. 305This approach also ensures that if, in the future, newer parameters 306are added, then older unaware applications will continue to 307behave correctly. 308.Ss Getting stream capabilities 309Advanced applications can fetch the native 310parameters of the audio subsystem and then choose parameters 311optimal for both the application and the audio subsystem. 312In this case applications must be able to do 313the necessary format conversions. 314The 315.Va sio_cap 316structure, filled by the 317.Fn sio_getcap 318function, contains the list of parameter configurations. 319Each configuration contains multiple parameter sets. 320The application must examine all configurations, and 321choose its parameter set from 322.Em one 323of the configurations. 324Parameters of different configurations 325.Em are not 326usable together. 327.Bd -literal 328struct sio_cap { 329 struct sio_enc { /* allowed encodings */ 330 unsigned bits; 331 unsigned bps; 332 unsigned sig; 333 unsigned le; 334 unsigned msb; 335 } enc[SIO_NENC]; 336 unsigned rchan[SIO_NCHAN]; /* allowed rchans */ 337 unsigned pchan[SIO_NCHAN]; /* allowed pchans */ 338 unsigned rate[SIO_NRATE]; /* allowed rates */ 339 unsigned nconf; /* num. of confs[] */ 340 struct sio_conf { 341 unsigned enc; /* bitmask of enc[] indexes */ 342 unsigned rchan; /* bitmask of rchan[] indexes */ 343 unsigned pchan; /* bitmask of pchan[] indexes */ 344 unsigned rate; /* bitmask of rate[] indexes */ 345 } confs[SIO_NCONF]; 346}; 347.Ed 348.Pp 349The parameters are as follows: 350.Bl -tag -width "rchan[SIO_NCHAN]" 351.It Va enc[SIO_NENC] 352Array of supported encodings. 353The tuple of 354.Va bits , 355.Va bps , 356.Va sig , 357.Va le 358and 359.Va msb 360parameters are usable in the corresponding parameters 361of the 362.Va sio_par 363structure. 364.It Va rchan[SIO_NCHAN] 365Array of supported channel numbers for recording usable 366in the 367.Va sio_par 368structure. 369.It Va pchan[SIO_NCHAN] 370Array of supported channel numbers for playback usable 371in the 372.Va sio_par 373structure. 374.It Va rate[SIO_NRATE] 375Array of supported sample rates usable 376in the 377.Va sio_par 378structure. 379.It Va nconf 380Number of different configurations available, i.e. number 381of filled elements of the 382.Va confs[] 383array. 384.It Va confs[SIO_NCONF] 385Array of available configurations. 386Each configuration contains bitmasks indicating which 387elements of the above parameter arrays are valid for the 388given configuration. 389For instance, if the second bit of 390.Va rate 391is set, in the 392.Va sio_conf 393structure, then the second element of the 394.Va rate[SIO_NRATE] 395array of the 396.Va sio_cap 397structure is valid for this configuration. 398.El 399.Ss Starting and stopping the stream 400The 401.Fn sio_start 402function puts the stream in a waiting state: 403the stream will wait for playback data to be provided 404(using the 405.Fn sio_write 406function). 407Once enough data is queued to ensure that play buffers 408will not underrun, actual playback is started automatically. 409If record mode only is selected, then recording starts 410immediately. 411In full-duplex mode, playback and recording will start 412synchronously as soon as enough data to play is available. 413.Pp 414The 415.Fn sio_stop 416function stops playback and recording and puts the audio subsystem 417in the same state as after 418.Fn sio_open 419is called. 420Samples in the play buffers are not discarded, and will continue to 421be played after 422.Fn sio_stop 423returns. 424.Ss Playing and recording 425When record mode is selected, the 426.Fn sio_read 427function must be called to retrieve recorded data; it must be called 428often enough to ensure that internal buffers will not overrun. 429It will store at most 430.Ar nbytes 431bytes at the 432.Ar addr 433location and return the number of bytes stored. 434Unless the 435.Ar nbio_flag 436flag is set, it will block until data becomes available and 437will return zero only on error. 438.Pp 439Similarly, when play mode is selected, the 440.Fn sio_write 441function must be called to provide data to play. 442Unless the 443.Ar nbio_flag 444is set, 445.Fn sio_write 446will block until the requested amount of data is written. 447.Ss Non-blocking mode operation 448If the 449.Ar nbio_flag 450is set on 451.Fn sio_open , 452then the 453.Fn sio_read 454and 455.Fn sio_write 456functions will never block; if no data is available, they will 457return zero immediately. 458.Pp 459Note that non-blocking mode must be used on bidirectional streams. 460For instance, if recording is blocked in 461.Fn sio_read 462then, even if samples can be played, 463.Fn sio_write 464cannot be called and the play buffers may underrun. 465.Pp 466To avoid busy loops when non-blocking mode is used, the 467.Xr poll 2 468system call can be used to check if data can be 469read from or written to the stream. 470The 471.Fn sio_pollfd 472function fills the array 473.Ar pfd 474of 475.Va pollfd 476structures, used by 477.Xr poll 2 , 478with 479.Ar events ; 480the latter is a bit-mask of 481.Va POLLIN 482and 483.Va POLLOUT 484constants; refer to 485.Xr poll 2 486for more details. 487.Fn sio_pollfd 488returns the number of 489.Va pollfd 490structures filled. 491The 492.Fn sio_revents 493function returns the bit-mask set by 494.Xr poll 2 495in the 496.Va pfd 497array of 498.Va pollfd 499structures. 500If 501.Va POLLIN 502is set, 503.Fn sio_read 504can be called without blocking. 505If 506.Va POLLOUT 507is set, 508.Fn sio_write 509can be called without blocking. 510POLLHUP may be set if an error occurs, even if 511it is not selected with 512.Fn sio_pollfd . 513.Pp 514The 515.Fn sio_nfds 516function returns the number of 517.Va pollfd 518structures the caller must preallocate in order to be sure 519that 520.Fn sio_pollfd 521will never overrun. 522.Ss Synchronizing non-audio events to the stream in real-time 523In order to perform actions at precise positions of the stream, 524such as displaying video in sync with the audio stream, 525the application must be notified in real-time of the exact 526position in the stream the hardware is processing. 527.Pp 528The 529.Fn sio_onmove 530function can be used to register the 531.Va cb 532callback function that will be called by the 533.Nm sndio 534library at regular time intervals to notify the application 535the position in the stream changed. 536The 537.Va delta 538argument contains the number of frames the hardware moved in the stream 539since the last call of 540.Va cb . 541The value of the 542.Va arg 543pointer is passed to the callback and can contain anything. 544.Pp 545If desired, the application can maintain the current position by 546starting from zero (when 547.Fn sio_start 548is called) and adding to the current position 549.Va delta 550every time 551.Fn cb 552is called. 553Note that at the beginning the current position might be 554negative indicating that the stream is being buffered, 555but has not reached the hardware yet. 556.Ss Measuring the latency and buffers usage 557The playback latency is the delay it will take for the 558frame just written to become audible, expressed in number of frames. 559The exact playback 560latency can be obtained by subtracting the current position 561from the number of frames written. 562Once playback is actually started (first sample audible) 563the latency will never exceed the 564.Va bufsz 565parameter (see the sections above). 566There's a phase during which 567.Fn sio_write 568only queues data; 569once there's enough data, actual playback starts. 570During this phase the current position is negative and 571the latency might be longer than 572.Va bufsz . 573.Pp 574In any cases, at most 575.Va bufsz 576frames are buffered. 577This value takes into account all buffers, 578including device, kernel and socket buffers. 579During the buffering phase, the number of frames stored 580is equal to the number of frames written. 581Once playback is started, it is equal to the number of frames 582written minus the current position. 583.Pp 584The recording latency is obtained similarly, by subtracting 585the number of frames read from the current position. 586.Pp 587It is strongly discouraged to use the latency and/or the buffer 588usage for anything but monitoring. 589Especially, note that 590.Fn sio_write 591might block even if there is buffer space left; 592using the buffer usage to guess if 593.Fn sio_write 594would block is false and leads to unreliable programs \(en consider using 595.Xr poll 2 596for this. 597.Ss Handling buffer overruns and underruns 598When the application cannot accept recorded data fast enough, 599the record buffer (of size 600.Va appbufsz ) 601might overrun; in this case recorded data is lost. 602Similarly if the application cannot provide data to play 603fast enough, the play buffer underruns and silence is played 604instead. 605Depending on the 606.Va xrun 607parameter of the 608.Va sio_par 609structure, the audio subsystem will behave as follows: 610.Bl -tag -width "SIO_IGNORE" 611.It SIO_IGNORE 612The stream is paused during overruns and underruns, 613thus the current position (obtained through 614.Va sio_onmove ) 615stops being incremented. 616Once the overrun and/or underrun condition is gone, the stream is unpaused; 617play and record are always kept in sync. 618With this mode, the application cannot notice 619underruns and/or overruns and shouldn't care about them. 620.Pp 621This mode is the default. 622It's suitable for applications, 623like audio players and telephony, where time 624is not important and overruns or underruns are not short. 625.It SIO_SYNC 626If the play buffer underruns, then silence is played, 627but in order to reach the right position in time, 628the same amount of written samples will be 629discarded once the application is unblocked. 630Similarly, if the record buffer overruns, then 631samples are discarded, but the same amount of silence will be 632returned later. 633The current position (obtained through 634.Va sio_onmove ) 635is still incremented. 636When the play buffer underruns the play latency might become negative; 637when the record buffer overruns, the record latency might become 638larger than 639.Va bufsz . 640.Pp 641This mode is suitable for applications, like music production, 642where time is important and where underruns or overruns are 643short and rare. 644.It SIO_ERROR 645With this mode, on the first play buffer underrun or 646record buffer overrun, the stream is terminated and 647no other function than 648.Fn sio_close 649will succeed. 650.Pp 651This mode is mostly useful for testing; portable 652applications shouldn't depend on it, since it's not available 653on other systems. 654.El 655.Ss Controlling the volume 656The 657.Fn sio_setvol 658function can be used to set playback attenuation. 659The 660.Va vol 661parameter takes a value between 0 (maximum attenuation) 662and 663.Dv SIO_MAXVOL 664(no attenuation). 665It specifies the weight the audio subsystem will 666give to this stream. 667It is not meant to control hardware parameters like 668speaker gain; the 669.Xr mixerctl 1 670interface should be used for that purpose instead. 671.Pp 672An application can use the 673.Fn sio_onvol 674function to register a callback function that 675will be called each time the volume is changed, 676including when 677.Fn sio_setvol 678is used. 679The callback is always invoked when 680.Fn sio_onvol 681is called in order to provide the initial volume. 682An application can safely assume that once 683.Fn sio_onvol 684returns, the callback has already been invoked and thus 685the current volume is available. 686.Ss Error handling 687Errors related to the audio subsystem 688(like hardware errors, dropped connections) and 689programming errors (e.g. call to 690.Fn sio_read 691on a play-only stream) are considered fatal. 692Once an error occurs, all functions taking a 693.Va sio_hdl 694argument, except 695.Fn sio_close 696and 697.Fn sio_eof , 698stop working (i.e. always return 0). 699.Pp 700The 701.Fn sio_eof 702function can be used at any stage; 703it returns 0 if there's no pending error, and a non-zero 704value if there's an error. 705.Sh RETURN VALUES 706The 707.Fn sio_open 708function returns the newly created handle on success or NULL 709on failure. 710The 711.Fn sio_setpar , 712.Fn sio_getpar , 713.Fn sio_getcap , 714.Fn sio_start , 715.Fn sio_stop , 716.Fn sio_pollfd 717and 718.Fn sio_setvol 719functions return 1 on success and 0 on failure. 720The 721.Fn sio_read 722and 723.Fn sio_write 724functions return the number of bytes transferred. 725.Sh ENVIRONMENT 726.Bl -tag -width "AUDIODEVICEXXX" -compact 727.It Ev AUDIODEVICE 728Device to use if 729.Fn sio_open 730is called with a NULL 731.Va name 732argument. 733.It Ev SIO_DEBUG 734The debug level: 735may be a value between 0 and 2. 736.El 737.Sh FILES 738.Bl -tag -width "/tmp/aucat-<uid>/softaudio0" -compact 739.It Pa /tmp/aucat-<uid>/softaudio0 740Default path to 741.Xr aucat 1 742socket to connect to. 743.It Pa /dev/audio 744Default 745.Xr audio 4 746device to use. 747.El 748.\".Sh EXAMPLES 749.\".Bd -literal -offset indent 750.\".Ed 751.Sh SEE ALSO 752.Xr aucat 1 , 753.Xr audio 4 , 754.Xr sndio 7 , 755.Xr audio 9 756.Sh BUGS 757The 758.Xr audio 4 759driver cannot drain playback buffers in the background, thus if 760.Nm libsndio 761is used to directly access an 762.Xr audio 4 763device, 764the 765.Fn sio_stop 766function will stop playback immediately. 767.Pp 768The 769.Xr aucat 1 770server doesn't implement flow control (for performance reasons). 771If the application doesn't consume recorded data fast enough then 772.Dq "control messages" 773are delayed (or lost) and consequently 774overruns and underruns stay unnoticed by the application in the 775.Va SIO_SYNC 776mode (overruns and underruns are handled on the server side, so 777synchronization is never lost). 778.Pp 779The 780.Fn sio_open , 781.Fn sio_setpar , 782.Fn sio_getpar , 783.Fn sio_getcap , 784.Fn sio_start 785and 786.Fn sio_stop 787functions may block for a very short period of time, thus they should 788be avoided in code sections where blocking is not desirable. 789