1 /* Copyright (c) 2012 The Chromium OS Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 * 5 * This API creates multiple threads, one for control, and a thread per audio 6 * stream. The control thread is used to receive messages and notifications 7 * from the audio server, and manage the per-stream threads. API calls below 8 * may send messages to the control thread, or directly to the server. It is 9 * required that the control thread is running in order to support audio 10 * streams and notifications from the server. 11 * 12 * The API has multiple initialization sequences, but some of those can block 13 * while waiting for a response from the server. 14 * 15 * The following is the non-blocking API initialization sequence: 16 * cras_client_create() 17 * cras_client_set_connection_status_cb() (optional) 18 * cras_client_run_thread() 19 * cras_client_connect_async() 20 * 21 * The connection callback is executed asynchronously from the control thread 22 * when the connection has been established. The connection callback should be 23 * used to turn on or off interactions with any API call that communicates with 24 * the audio server or starts/stops audio streams. The above is implemented by 25 * cras_helper_create_connect_async(). 26 * 27 * The following alternative (deprecated) initialization sequence can ensure 28 * that the connection is established synchronously. 29 * 30 * Just connect to the server (no control thread): 31 * cras_client_create() 32 * cras_client_set_server_connection_cb() (optional) 33 * one of: 34 * cras_client_connect() (blocks forever) 35 * or 36 * cras_client_connect_timeout() (blocks for timeout) 37 * 38 * For API calls below that require the control thread to be running: 39 * cras_client_run_thread(); 40 * cras_client_connected_wait(); (blocks up to 1 sec.) 41 * 42 * The above minus setting the connection callback is implemented within 43 * cras_helper_create_connect(). 44 */ 45 46 #ifndef CRAS_CLIENT_H_ 47 #define CRAS_CLIENT_H_ 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 #include <stdbool.h> 54 #include <stdint.h> 55 #include <sys/select.h> 56 57 #include "cras_iodev_info.h" 58 #include "cras_types.h" 59 #include "cras_util.h" 60 61 struct cras_client; 62 struct cras_stream_params; 63 64 /* Callback for audio received or transmitted. 65 * Args (All pointer will be valid - except user_arg, that's up to the user): 66 * client: The client requesting service. 67 * stream_id - Unique identifier for the stream needing data read/written. 68 * samples - Read or write samples to/form here. 69 * frames - Maximum number of frames to read or write. 70 * sample_time - Playback time for the first sample read/written. 71 * user_arg - Value passed to add_stream; 72 * Return: 73 * Returns the number of frames read or written on success, or a negative 74 * number if there is a stream-fatal error. Returns EOF when the end of the 75 * stream is reached. 76 */ 77 typedef int (*cras_playback_cb_t)(struct cras_client *client, 78 cras_stream_id_t stream_id, 79 uint8_t *samples, 80 size_t frames, 81 const struct timespec *sample_time, 82 void *user_arg); 83 84 /* Callback for audio received and/or transmitted. 85 * Args (All pointer will be valid - except user_arg, that's up to the user): 86 * client: The client requesting service. 87 * stream_id - Unique identifier for the stream needing data read/written. 88 * captured_samples - Read samples form here. 89 * playback_samples - Read or write samples to here. 90 * frames - Maximum number of frames to read or write. 91 * captured_time - Time the first sample was read. 92 * playback_time - Playback time for the first sample written. 93 * user_arg - Value passed to add_stream; 94 * Return: 95 * Returns the number of frames read or written on success, or a negative 96 * number if there is a stream-fatal error. Returns EOF when the end of the 97 * stream is reached. 98 */ 99 typedef int (*cras_unified_cb_t)(struct cras_client *client, 100 cras_stream_id_t stream_id, 101 uint8_t *captured_samples, 102 uint8_t *playback_samples, 103 unsigned int frames, 104 const struct timespec *captured_time, 105 const struct timespec *playback_time, 106 void *user_arg); 107 108 /* Callback for handling stream errors. 109 * Args: 110 * client - The client created with cras_client_create(). 111 * stream_id - The ID for this stream. 112 * error - The error code, 113 * user_arg - The argument defined in cras_client_*_params_create(). 114 */ 115 typedef int (*cras_error_cb_t)(struct cras_client *client, 116 cras_stream_id_t stream_id, 117 int error, 118 void *user_arg); 119 120 /* Callback for handling server error. DEPRECATED 121 * 122 * Deprecated by cras_server_connection_status_cb_t: use that instead. 123 * This is equivalent to CRAS_CONN_STATUS_FAILED. 124 * 125 * This callback is executed rarely: only when the connection to the server has 126 * already been interrupted and could not be re-established due to resource 127 * allocation failure (memory or file-descriptors). The caller may attempt 128 * to reestablish communication once those resources are available with 129 * cras_client_connect_async(), or (blocking) cras_client_connect(). 130 * 131 * Args: 132 * client - The client created with cras_client_create(). 133 * user_arg - The argument defined in cras_client_set_server_errro_cb(). 134 */ 135 typedef void (*cras_server_error_cb_t)(struct cras_client *client, 136 void *user_arg); 137 138 /* Server connection status. */ 139 typedef enum cras_connection_status { 140 CRAS_CONN_STATUS_FAILED, 141 /* Resource allocation problem. Free resources, and retry the 142 * connection with cras_client_connect_async(), or (blocking) 143 * cras_client_connect(). Do not call cras_client_connect(), 144 * cras_client_connect_timeout(), or cras_client_destroy() 145 * from the callback. */ 146 CRAS_CONN_STATUS_DISCONNECTED, 147 /* The control thread is attempting to reconnect to the 148 * server in the background. Any attempt to access the 149 * server will fail or block (see 150 * cras_client_set_server_message_blocking(). */ 151 CRAS_CONN_STATUS_CONNECTED, 152 /* Connection is established. All state change callbacks 153 * have been re-registered, but audio streams must be 154 * restarted, and node state data must be updated. */ 155 } cras_connection_status_t; 156 157 /* Callback for handling server connection status. 158 * 159 * See also cras_client_set_connection_status_cb(). Do not call 160 * cras_client_connect(), cras_client_connect_timeout(), or 161 * cras_client_destroy() from this callback. 162 * 163 * Args: 164 * client - The client created with cras_client_create(). 165 * status - The status of the connection to the server. 166 * user_arg - The argument defined in 167 * cras_client_set_connection_status_cb(). 168 */ 169 typedef void (*cras_connection_status_cb_t)(struct cras_client *client, 170 cras_connection_status_t status, 171 void *user_arg); 172 173 /* Callback for setting thread priority. */ 174 typedef void (*cras_thread_priority_cb_t)(struct cras_client *client); 175 176 /* Callback for handling get hotword models reply. */ 177 typedef void (*get_hotword_models_cb_t)(struct cras_client *client, 178 const char *hotword_models); 179 180 /* 181 * Client handling. 182 */ 183 184 /* Creates a new client. 185 * Args: 186 * client - Filled with a pointer to the new client. 187 * Returns: 188 * 0 on success (*client is filled with a valid cras_client pointer). 189 * Negative error code on failure(*client will be NULL). 190 */ 191 int cras_client_create(struct cras_client **client); 192 193 /* Destroys a client. 194 * Args: 195 * client - returned from "cras_client_create". 196 */ 197 void cras_client_destroy(struct cras_client *client); 198 199 /* Connects a client to the running server. 200 * Waits forever (until interrupted or connected). 201 * Args: 202 * client - pointer returned from "cras_client_create". 203 * Returns: 204 * 0 on success, or a negative error code on failure (from errno.h). 205 */ 206 int cras_client_connect(struct cras_client *client); 207 208 /* Connects a client to the running server, retries until timeout. 209 * Args: 210 * client - pointer returned from "cras_client_create". 211 * timeout_ms - timeout in milliseconds or negative to wait forever. 212 * Returns: 213 * 0 on success, or a negative error code on failure (from errno.h). 214 */ 215 int cras_client_connect_timeout(struct cras_client *client, 216 unsigned int timeout_ms); 217 218 /* Begins running the client control thread. 219 * 220 * Required for stream operations and other operations noted below. 221 * 222 * Args: 223 * client - the client to start (from cras_client_create). 224 * Returns: 225 * 0 on success or if the thread is already running, -EINVAL if the client 226 * pointer is NULL, or the negative result of pthread_create(). 227 */ 228 int cras_client_run_thread(struct cras_client *client); 229 230 /* Stops running a client. 231 * This function is executed automatically by cras_client_destroy(). 232 * Args: 233 * client - the client to stop (from cras_client_create). 234 * Returns: 235 * 0 on success or if the thread was already stopped, -EINVAL if the client 236 * isn't valid. 237 */ 238 int cras_client_stop(struct cras_client *client); 239 240 /* Wait up to 1 second for the client thread to complete the server connection. 241 * 242 * After cras_client_run_thread() is executed, this function can be used to 243 * ensure that the connection has been established with the server and ensure 244 * that any information about the server is up to date. If 245 * cras_client_run_thread() has not yet been executed, or cras_client_stop() 246 * was executed and thread isn't running, then this function returns -EINVAL. 247 * 248 * Args: 249 * client - pointer returned from "cras_client_create". 250 * Returns: 251 * 0 on success, or a negative error code on failure (from errno.h). 252 */ 253 int cras_client_connected_wait(struct cras_client *client); 254 255 /* Ask the client control thread to connect to the audio server. 256 * 257 * After cras_client_run_thread() is executed, this function can be used 258 * to ask the control thread to connect to the audio server asynchronously. 259 * The callback set with cras_client_set_connection_status_cb() will be 260 * executed when the connection is established. 261 * 262 * Args: 263 * client - The client from cras_client_create(). 264 * Returns: 265 * 0 on success, or a negative error code on failure (from errno.h). 266 * -EINVAL if the client pointer is invalid or the control thread is 267 * not running. 268 */ 269 int cras_client_connect_async(struct cras_client *client); 270 271 /* Sets server error callback. DEPRECATED 272 * 273 * See cras_server_error_cb_t for more information about this callback. 274 * 275 * Args: 276 * client - The client from cras_client_create. 277 * err_cb - The callback function to register. 278 * user_arg - Pointer that will be passed to the callback. 279 */ 280 void cras_client_set_server_error_cb(struct cras_client *client, 281 cras_server_error_cb_t err_cb, 282 void *user_arg); 283 284 /* Sets server connection status callback. 285 * 286 * See cras_connection_status_t for a description of the connection states 287 * and appropriate user action. 288 * 289 * Args: 290 * client - The client from cras_client_create. 291 * connection_cb - The callback function to register. 292 * user_arg - Pointer that will be passed to the callback. 293 */ 294 void cras_client_set_connection_status_cb( 295 struct cras_client *client, 296 cras_connection_status_cb_t connection_cb, 297 void *user_arg); 298 299 /* Sets callback for setting thread priority. 300 * Args: 301 * client - The client from cras_client_create. 302 * cb - The thread priority callback. 303 */ 304 void cras_client_set_thread_priority_cb(struct cras_client *client, 305 cras_thread_priority_cb_t cb); 306 307 /* Returns the current list of output devices. 308 * 309 * Requires that the connection to the server has been established. 310 * 311 * Data is copied and thus can become out of date. This call must be 312 * re-executed to get updates. 313 * 314 * Args: 315 * client - The client from cras_client_create. 316 * devs - Array that will be filled with device info. 317 * nodes - Array that will be filled with node info. 318 * *num_devs - Maximum number of devices to put in the array. 319 * *num_nodes - Maximum number of nodes to put in the array. 320 * Returns: 321 * 0 on success, -EINVAL if the client isn't valid or isn't running. 322 * *num_devs is set to the actual number of devices info filled. 323 * *num_nodes is set to the actual number of nodes info filled. 324 */ 325 int cras_client_get_output_devices(const struct cras_client *client, 326 struct cras_iodev_info *devs, 327 struct cras_ionode_info *nodes, 328 size_t *num_devs, size_t *num_nodes); 329 330 /* Returns the current list of input devices. 331 * 332 * Requires that the connection to the server has been established. 333 * 334 * Data is copied and thus can become out of date. This call must be 335 * re-executed to get updates. 336 * 337 * Args: 338 * client - The client from cras_client_create. 339 * devs - Array that will be filled with device info. 340 * nodes - Array that will be filled with node info. 341 * *num_devs - Maximum number of devices to put in the array. 342 * *num_nodes - Maximum number of nodes to put in the array. 343 * Returns: 344 * 0 on success, -EINVAL if the client isn't valid or isn't running. 345 * *num_devs is set to the actual number of devices info filled. 346 * *num_nodes is set to the actual number of nodes info filled. 347 */ 348 int cras_client_get_input_devices(const struct cras_client *client, 349 struct cras_iodev_info *devs, 350 struct cras_ionode_info *nodes, 351 size_t *num_devs, size_t *num_nodes); 352 353 /* Returns the current list of clients attached to the server. 354 * 355 * Requires that the connection to the server has been established. 356 * 357 * Data is copied and thus can become out of date. This call must be 358 * re-executed to get updates. 359 * 360 * Args: 361 * client - This client (from cras_client_create). 362 * clients - Array that will be filled with a list of attached clients. 363 * max_clients - Maximum number of clients to put in the array. 364 * Returns: 365 * The number of attached clients. This may be more that max_clients passed 366 * in, this indicates that all of the clients wouldn't fit in the provided 367 * array. 368 */ 369 int cras_client_get_attached_clients(const struct cras_client *client, 370 struct cras_attached_client_info *clients, 371 size_t max_clients); 372 373 /* Find a node info with the matching node id. 374 * 375 * Requires that the connection to the server has been established. 376 * 377 * Data is copied and thus can become out of date. This call must be 378 * re-executed to get updates. 379 * 380 * Args: 381 * client - This client (from cras_client_create). 382 * input - Non-zero for input nodes, zero for output nodes. 383 * node_id - The node id to look for. 384 * node_info - The information about the ionode will be returned here. 385 * Returns: 386 * 0 if successful, negative on error; -ENOENT if the node cannot be found. 387 */ 388 int cras_client_get_node_by_id(const struct cras_client *client, 389 int input, 390 const cras_node_id_t node_id, 391 struct cras_ionode_info* node_info); 392 393 /* Checks if the output device with the given name is currently plugged in. 394 * 395 * For internal devices this checks that jack state, for USB devices this will 396 * always be true if they are present. The name parameter can be the complete 397 * name or any unique prefix of the name. If the name is not unique the first 398 * matching name will be checked. 399 * 400 * Requires that the connection to the server has been established. 401 * 402 * Data is copied and thus can become out of date. This call must be 403 * re-executed to get updates. 404 * 405 * Args: 406 * client - The client from cras_client_create. 407 * name - Name of the device to check. 408 * Returns: 409 * 1 if the device exists and is plugged, 0 otherwise. 410 */ 411 int cras_client_output_dev_plugged(const struct cras_client *client, 412 const char *name); 413 414 /* Set the value of an attribute of an ionode. 415 * 416 * Args: 417 * client - The client from cras_client_create. 418 * node_id - The id of the ionode. 419 * attr - the attribute we want to change. 420 * value - the value we want to set. 421 * Returns: 422 * Returns 0 for success, negative on error (from errno.h). 423 */ 424 int cras_client_set_node_attr(struct cras_client *client, 425 cras_node_id_t node_id, 426 enum ionode_attr attr, 427 int value); 428 429 /* Select the preferred node for playback/capture. 430 * 431 * Args: 432 * client - The client from cras_client_create. 433 * direction - The direction of the ionode. 434 * node_id - The id of the ionode. If node_id is the special value 0, then 435 * the preference is cleared and cras will choose automatically. 436 */ 437 int cras_client_select_node(struct cras_client *client, 438 enum CRAS_STREAM_DIRECTION direction, 439 cras_node_id_t node_id); 440 441 /* Adds an active node for playback/capture. 442 * 443 * Args: 444 * client - The client from cras_client_create. 445 * direction - The direction of the ionode. 446 * node_id - The id of the ionode. If there's no node matching given 447 * id, nothing will happen in CRAS. 448 */ 449 int cras_client_add_active_node(struct cras_client *client, 450 enum CRAS_STREAM_DIRECTION direction, 451 cras_node_id_t node_id); 452 453 /* Removes an active node for playback/capture. 454 * 455 * Args: 456 * client - The client from cras_client_create. 457 * direction - The direction of the ionode. 458 * node_id - The id of the ionode. If there's no node matching given 459 * id, nothing will happen in CRAS. 460 */ 461 int cras_client_rm_active_node(struct cras_client *client, 462 enum CRAS_STREAM_DIRECTION direction, 463 cras_node_id_t node_id); 464 465 466 /* Asks the server to reload dsp plugin configuration from the ini file. 467 * 468 * Args: 469 * client - The client from cras_client_create. 470 * Returns: 471 * 0 on success, -EINVAL if the client isn't valid or isn't running. 472 */ 473 int cras_client_reload_dsp(struct cras_client *client); 474 475 /* Asks the server to dump current dsp information to syslog. 476 * 477 * Args: 478 * client - The client from cras_client_create. 479 * Returns: 480 * 0 on success, -EINVAL if the client isn't valid or isn't running. 481 */ 482 int cras_client_dump_dsp_info(struct cras_client *client); 483 484 /* Asks the server to dump current audio thread information. 485 * 486 * Args: 487 * client - The client from cras_client_create. 488 * cb - A function to call when the data is received. 489 * Returns: 490 * 0 on success, -EINVAL if the client isn't valid or isn't running. 491 */ 492 int cras_client_update_audio_debug_info( 493 struct cras_client *client, void (*cb)(struct cras_client *)); 494 495 /* 496 * Stream handling. 497 */ 498 499 /* Setup stream configuration parameters. 500 * Args: 501 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 502 * buffer_frames - total number of audio frames to buffer (dictates latency). 503 * cb_threshold - For playback, call back for more data when the buffer 504 * reaches this level. For capture, this is ignored (Audio callback will 505 * be called when buffer_frames have been captured). 506 * unused - No longer used. 507 * stream_type - media or talk (currently only support "default"). 508 * flags - None currently used. 509 * user_data - Pointer that will be passed to the callback. 510 * aud_cb - Called when audio is needed(playback) or ready(capture). Allowed 511 * return EOF to indicate that the stream should terminate. 512 * err_cb - Called when there is an error with the stream. 513 * format - The format of the audio stream. Specifies bits per sample, 514 * number of channels, and sample rate. 515 */ 516 struct cras_stream_params *cras_client_stream_params_create( 517 enum CRAS_STREAM_DIRECTION direction, 518 size_t buffer_frames, 519 size_t cb_threshold, 520 size_t unused, 521 enum CRAS_STREAM_TYPE stream_type, 522 uint32_t flags, 523 void *user_data, 524 cras_playback_cb_t aud_cb, 525 cras_error_cb_t err_cb, 526 struct cras_audio_format *format); 527 528 /* Setup stream configuration parameters. 529 * Args: 530 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT) or 531 * loopback(CRAS_STREAM_POST_MIX_PRE_DSP). 532 * block_size - The number of frames per callback(dictates latency). 533 * stream_type - media or talk (currently only support "default"). 534 * flags - None currently used. 535 * user_data - Pointer that will be passed to the callback. 536 * unified_cb - Called for streams that do simultaneous input/output. 537 * err_cb - Called when there is an error with the stream. 538 * format - The format of the audio stream. Specifies bits per sample, 539 * number of channels, and sample rate. 540 */ 541 struct cras_stream_params *cras_client_unified_params_create( 542 enum CRAS_STREAM_DIRECTION direction, 543 unsigned int block_size, 544 enum CRAS_STREAM_TYPE stream_type, 545 uint32_t flags, 546 void *user_data, 547 cras_unified_cb_t unified_cb, 548 cras_error_cb_t err_cb, 549 struct cras_audio_format *format); 550 551 /* Destroy stream params created with cras_client_stream_params_create. */ 552 void cras_client_stream_params_destroy(struct cras_stream_params *params); 553 554 /* Creates a new stream and return the stream id or < 0 on error. 555 * 556 * Requires execution of cras_client_run_thread(), and an active connection 557 * to the audio server. 558 * 559 * Args: 560 * client - The client to add the stream to (from cras_client_create). 561 * stream_id_out - On success will be filled with the new stream id. 562 * Guaranteed to be set before any callbacks are made. 563 * config - The cras_stream_params struct specifying the parameters for the 564 * stream. 565 * Returns: 566 * 0 on success, negative error code on failure (from errno.h). 567 */ 568 int cras_client_add_stream(struct cras_client *client, 569 cras_stream_id_t *stream_id_out, 570 struct cras_stream_params *config); 571 572 /* Creates a pinned stream and return the stream id or < 0 on error. 573 * 574 * Requires execution of cras_client_run_thread(), and an active connection 575 * to the audio server. 576 * 577 * Args: 578 * client - The client to add the stream to (from cras_client_create). 579 * dev_idx - Index of the device to attach the newly created stream. 580 * stream_id_out - On success will be filled with the new stream id. 581 * Guaranteed to be set before any callbacks are made. 582 * config - The cras_stream_params struct specifying the parameters for the 583 * stream. 584 * Returns: 585 * 0 on success, negative error code on failure (from errno.h). 586 */ 587 int cras_client_add_pinned_stream(struct cras_client *client, 588 uint32_t dev_idx, 589 cras_stream_id_t *stream_id_out, 590 struct cras_stream_params *config); 591 592 /* Removes a currently playing/capturing stream. 593 * 594 * Requires execution of cras_client_run_thread(). 595 * 596 * Args: 597 * client - Client to remove the stream (returned from cras_client_create). 598 * stream_id - ID returned from cras_client_add_stream to identify the stream 599 to remove. 600 * Returns: 601 * 0 on success negative error code on failure (from errno.h). 602 */ 603 int cras_client_rm_stream(struct cras_client *client, 604 cras_stream_id_t stream_id); 605 606 /* Sets the volume scaling factor for the given stream. 607 * 608 * Requires execution of cras_client_run_thread(). 609 * 610 * Args: 611 * client - Client owning the stream. 612 * stream_id - ID returned from cras_client_add_stream. 613 * volume_scaler - 0.0-1.0 the new value to scale this stream by. 614 */ 615 int cras_client_set_stream_volume(struct cras_client *client, 616 cras_stream_id_t stream_id, 617 float volume_scaler); 618 619 /* 620 * System level functions. 621 */ 622 623 /* Sets the volume of the system. 624 * 625 * Volume here ranges from 0 to 100, and will be translated to dB based on the 626 * output-specific volume curve. 627 * 628 * Args: 629 * client - The client from cras_client_create. 630 * volume - 0-100 the new volume index. 631 * Returns: 632 * 0 for success, -EPIPE if there is an I/O error talking to the server, or 633 * -EINVAL if 'client' is invalid. 634 */ 635 int cras_client_set_system_volume(struct cras_client *client, size_t volume); 636 637 /* Sets the capture gain of the system. 638 * 639 * Gain is specified in dBFS * 100. For example 5dB of gain would be specified 640 * with an argument of 500, while -10 would be specified with -1000. 641 * 642 * Args: 643 * client - The client from cras_client_create. 644 * gain - The gain in dBFS * 100. 645 * Returns: 646 * 0 for success, -EPIPE if there is an I/O error talking to the server, or 647 * -EINVAL if 'client' is invalid. 648 */ 649 int cras_client_set_system_capture_gain(struct cras_client *client, long gain); 650 651 /* Sets the mute state of the system. 652 * 653 * Args: 654 * client - The client from cras_client_create. 655 * mute - 0 is un-mute, 1 is muted. 656 * Returns: 657 * 0 for success, -EPIPE if there is an I/O error talking to the server, or 658 * -EINVAL if 'client' is invalid. 659 */ 660 int cras_client_set_system_mute(struct cras_client *client, int mute); 661 662 /* Sets the user mute state of the system. 663 * 664 * This is used for mutes caused by user interaction. Like the mute key. 665 * 666 * Args: 667 * client - The client from cras_client_create. 668 * mute - 0 is un-mute, 1 is muted. 669 * Returns: 670 * 0 for success, -EPIPE if there is an I/O error talking to the server, or 671 * -EINVAL if 'client' is invalid. 672 */ 673 int cras_client_set_user_mute(struct cras_client *client, int mute); 674 675 /* Sets the mute locked state of the system. 676 * 677 * Changing mute state is impossible when this flag is set to locked. 678 * 679 * Args: 680 * client - The client from cras_client_create. 681 * locked - 0 is un-locked, 1 is locked. 682 * Returns: 683 * 0 for success, -EPIPE if there is an I/O error talking to the server, or 684 * -EINVAL if 'client' is invalid. 685 */ 686 int cras_client_set_system_mute_locked(struct cras_client *client, int locked); 687 688 /* Sets the capture mute state of the system. 689 * 690 * Recordings will be muted when this is set. 691 * 692 * Args: 693 * client - The client from cras_client_create. 694 * mute - 0 is un-mute, 1 is muted. 695 * Returns: 696 * 0 for success, -EPIPE if there is an I/O error talking to the server, or 697 * -EINVAL if 'client' is invalid. 698 */ 699 int cras_client_set_system_capture_mute(struct cras_client *client, int mute); 700 701 /* Sets the capture mute locked state of the system. 702 * 703 * Changing mute state is impossible when this flag is set to locked. 704 * 705 * Args: 706 * client - The client from cras_client_create. 707 * locked - 0 is un-locked, 1 is locked. 708 * Returns: 709 * 0 for success, -EPIPE if there is an I/O error talking to the server, or 710 * -EINVAL if 'client' is invalid. 711 */ 712 int cras_client_set_system_capture_mute_locked(struct cras_client *client, 713 int locked); 714 715 /* Gets the current system volume. 716 * 717 * Requires that the connection to the server has been established. 718 * 719 * Args: 720 * client - The client from cras_client_create. 721 * Returns: 722 * The current system volume between 0 and 100. 723 */ 724 size_t cras_client_get_system_volume(const struct cras_client *client); 725 726 /* Gets the current system capture gain. 727 * 728 * Requires that the connection to the server has been established. 729 * 730 * Args: 731 * client - The client from cras_client_create. 732 * Returns: 733 * The current system capture volume in dB * 100. 734 */ 735 long cras_client_get_system_capture_gain(const struct cras_client *client); 736 737 /* Gets the current system mute state. 738 * 739 * Requires that the connection to the server has been established. 740 * 741 * Args: 742 * client - The client from cras_client_create. 743 * Returns: 744 * 0 if not muted, 1 if it is. 745 */ 746 int cras_client_get_system_muted(const struct cras_client *client); 747 748 /* Gets the current user mute state. 749 * 750 * Requires that the connection to the server has been established. 751 * 752 * Args: 753 * client - The client from cras_client_create. 754 * Returns: 755 * 0 if not muted, 1 if it is. 756 */ 757 int cras_client_get_user_muted(const struct cras_client *client); 758 759 /* Gets the current system capture mute state. 760 * 761 * Requires that the connection to the server has been established. 762 * 763 * Args: 764 * client - The client from cras_client_create. 765 * Returns: 766 * 0 if capture is not muted, 1 if it is. 767 */ 768 int cras_client_get_system_capture_muted(const struct cras_client *client); 769 770 /* Gets the current minimum system volume. 771 * Args: 772 * client - The client from cras_client_create. 773 * Returns: 774 * The minimum value for the current output device in dBFS * 100. This is 775 * the level of attenuation at volume == 1. 776 */ 777 long cras_client_get_system_min_volume(const struct cras_client *client); 778 779 /* Gets the current maximum system volume. 780 * Args: 781 * client - The client from cras_client_create. 782 * Returns: 783 * The maximum value for the current output device in dBFS * 100. This is 784 * the level of attenuation at volume == 100. 785 */ 786 long cras_client_get_system_max_volume(const struct cras_client *client); 787 788 /* Gets the current minimum system capture gain. 789 * 790 * Requires that the connection to the server has been established. 791 * 792 * Args: 793 * client - The client from cras_client_create. 794 * Returns: 795 * The minimum capture gain for the current input device in dBFS * 100. 796 */ 797 long cras_client_get_system_min_capture_gain(const struct cras_client *client); 798 799 /* Gets the current maximum system capture gain. 800 * 801 * Requires that the connection to the server has been established. 802 * 803 * Args: 804 * client - The client from cras_client_create. 805 * Returns: 806 * The maximum capture gain for the current input device in dBFS * 100. 807 */ 808 long cras_client_get_system_max_capture_gain(const struct cras_client *client); 809 810 /* Gets audio debug info. 811 * 812 * Requires that the connection to the server has been established. 813 * Access to the resulting pointer is not thread-safe. 814 * 815 * Args: 816 * client - The client from cras_client_create. 817 * Returns: 818 * A pointer to the debug info. This info is only updated when requested by 819 * calling cras_client_update_audio_debug_info. 820 */ 821 const struct audio_debug_info *cras_client_get_audio_debug_info( 822 const struct cras_client *client); 823 824 /* Gets the number of streams currently attached to the server. 825 * 826 * This is the total number of capture and playback streams. If the ts argument 827 * is not null, then it will be filled with the last time audio was played or 828 * recorded. ts will be set to the current time if streams are currently 829 * active. 830 * 831 * Requires that the connection to the server has been established. 832 * 833 * Args: 834 * client - The client from cras_client_create. 835 * ts - Filled with the timestamp of the last stream. 836 * Returns: 837 * The number of active streams. 838 */ 839 unsigned cras_client_get_num_active_streams(const struct cras_client *client, 840 struct timespec *ts); 841 842 843 /* 844 * Utility functions. 845 */ 846 847 /* Returns the number of bytes in an audio frame for a stream. 848 * Args: 849 * format - The format of the audio stream. Specifies bits per sample, 850 * number of channels, and sample rate. 851 * Returns: 852 * Positive number of bytes in a frame, or a negative error code if fmt is 853 * NULL. 854 */ 855 int cras_client_format_bytes_per_frame(struct cras_audio_format *fmt); 856 857 /* For playback streams, calculates the latency of the next sample written. 858 * Only valid when called from the audio callback function for the stream 859 * (aud_cb). 860 * Args: 861 * sample_time - The sample time stamp passed in to aud_cb. 862 * delay - Out parameter will be filled with the latency. 863 * Returns: 864 * 0 on success, -EINVAL if delay is NULL. 865 */ 866 int cras_client_calc_playback_latency(const struct timespec *sample_time, 867 struct timespec *delay); 868 869 /* For capture returns the latency of the next frame to be read from the buffer 870 * (based on when it was captured). Only valid when called from the audio 871 * callback function for the stream (aud_cb). 872 * Args: 873 * sample_time - The sample time stamp passed in to aud_cb. 874 * delay - Out parameter will be filled with the latency. 875 * Returns: 876 * 0 on success, -EINVAL if delay is NULL. 877 */ 878 int cras_client_calc_capture_latency(const struct timespec *sample_time, 879 struct timespec *delay); 880 881 /* Set the volume of the given output node. Only for output nodes. 882 * 883 * Args: 884 * client - The client from cras_client_create. 885 * node_id - ID of the node. 886 * volume - New value for node volume. 887 */ 888 int cras_client_set_node_volume(struct cras_client *client, 889 cras_node_id_t node_id, 890 uint8_t volume); 891 892 /* Swap the left and right channel of the given node. 893 * 894 * Args: 895 * client - The client from cras_client_create. 896 * node_id - ID of the node. 897 * enable - 1 to enable swap mode, 0 to disable. 898 */ 899 int cras_client_swap_node_left_right(struct cras_client *client, 900 cras_node_id_t node_id, int enable); 901 902 /* Set the capture gain of the given input node. Only for input nodes. 903 * 904 * Args: 905 * client - The client from cras_client_create. 906 * node_id - ID of the node. 907 * gain - New capture gain for the node. 908 */ 909 int cras_client_set_node_capture_gain(struct cras_client *client, 910 cras_node_id_t node_id, 911 long gain); 912 913 /* Add a test iodev to the iodev list. 914 * 915 * Args: 916 * client - The client from cras_client_create. 917 * type - The type of test iodev, see cras_types.h 918 */ 919 int cras_client_add_test_iodev(struct cras_client *client, 920 enum TEST_IODEV_TYPE type); 921 922 /* Send a test command to a test iodev. 923 * 924 * Args: 925 * client - The client from cras_client_create. 926 * iodev_idx - The index of the test iodev. 927 * command - The command to send. 928 * data_len - Length of command data. 929 * data - Command data. 930 */ 931 int cras_client_test_iodev_command(struct cras_client *client, 932 unsigned int iodev_idx, 933 enum CRAS_TEST_IODEV_CMD command, 934 unsigned int data_len, 935 const uint8_t *data); 936 937 /* Finds the first device that contains a node of the given type. 938 * 939 * This is used for finding a special hotword device. 940 * 941 * Requires that the connection to the server has been established. 942 * 943 * Args: 944 * client - The client from cras_client_create. 945 * type - The type of device to find. 946 * direction - Search input or output devices. 947 * Returns the device index of a negative error on failure. 948 */ 949 int cras_client_get_first_dev_type_idx(const struct cras_client *client, 950 enum CRAS_NODE_TYPE type, 951 enum CRAS_STREAM_DIRECTION direction); 952 953 /* Sets the suspend state of audio playback and capture. 954 * 955 * Set this before putting the system into suspend. 956 * 957 * Args: 958 * client - The client from cras_client_create. 959 * suspend - Suspend the system if non-zero, otherwise resume. 960 */ 961 int cras_client_set_suspend(struct cras_client *client, int suspend); 962 963 /* Configures the global converter for output remixing. 964 * 965 * Args: 966 * client - The client from cras_client_create. 967 * num_channels - Number of output channels. 968 * coefficient - Float array representing |num_channels| * |num_channels| 969 * matrix. Channels of mixed PCM output will be remixed by 970 * multiplying this matrix. 971 */ 972 int cras_client_config_global_remix(struct cras_client *client, 973 unsigned num_channels, 974 float *coefficient); 975 976 /* Gets the set of supported hotword language models on a node. The supported 977 * models may differ on different nodes. 978 * 979 * Args: 980 * client - The client from cras_client_create. 981 * node_id - ID of a hotword input node (CRAS_NODE_TYPE_HOTWORD). 982 * cb - The function to be called when hotword models are ready. 983 * Returns: 984 * 0 on success. 985 */ 986 int cras_client_get_hotword_models(struct cras_client *client, 987 cras_node_id_t node_id, 988 get_hotword_models_cb_t cb); 989 990 /* Sets the hotword language model on a node. If there are existing streams on 991 * the hotword input node when this function is called, they need to be closed 992 * then re-opend for the model change to take effect. 993 * Args: 994 * client - The client from cras_client_create. 995 * node_id - ID of a hotword input node (CRAS_NODE_TYPE_HOTWORD). 996 * model_name - Name of the model to use, e.g. "en_us". 997 * Returns: 998 * 0 on success. 999 * -EINVAL if client or node_id is invalid. 1000 * -ENOENT if the specified model is not found. 1001 */ 1002 int cras_client_set_hotword_model(struct cras_client *client, 1003 cras_node_id_t node_id, 1004 const char *model_name); 1005 1006 /* Set the context pointer for system state change callbacks. 1007 * Args: 1008 * client - The client from cras_client_create. 1009 * context - The context pointer passed to all callbacks. 1010 */ 1011 void cras_client_set_state_change_callback_context( 1012 struct cras_client *client, void *context); 1013 1014 /* Output volume change callback. 1015 * 1016 * Args: 1017 * context - Context pointer set with 1018 * cras_client_set_state_change_callback_context(). 1019 * volume - The system output volume, ranging from 0 to 100. 1020 */ 1021 typedef void (*cras_client_output_volume_changed_callback)( 1022 void* context, int32_t volume); 1023 1024 /* Output mute change callback. 1025 * 1026 * Args: 1027 * context - Context pointer set with 1028 * cras_client_set_state_change_callback_context(). 1029 * muted - Non-zero when the audio is muted, zero otherwise. 1030 * user_muted - Non-zero when the audio has been muted by the 1031 * user, zero otherwise. 1032 * mute_locked - Non-zero when the mute funcion is locked, 1033 * zero otherwise. 1034 */ 1035 typedef void (*cras_client_output_mute_changed_callback)( 1036 void* context, int muted, int user_muted, int mute_locked); 1037 1038 /* Capture gain change callback. 1039 * 1040 * Args: 1041 * context - Context pointer set with 1042 * cras_client_set_state_change_callback_context(). 1043 * gain - The system capture gain, in centi-decibels. 1044 */ 1045 typedef void (*cras_client_capture_gain_changed_callback)( 1046 void* context, int32_t gain); 1047 1048 /* Capture mute change callback. 1049 * 1050 * Args: 1051 * context - Context pointer set with 1052 * cras_client_set_state_change_callback_context(). 1053 * muted - Non-zero when the audio is muted, zero otherwise. 1054 * mute_locked - Non-zero when the mute funcion is locked, 1055 * zero otherwise. 1056 */ 1057 typedef void (*cras_client_capture_mute_changed_callback)( 1058 void* context, int muted, int mute_locked); 1059 1060 /* Nodes change callback. 1061 * 1062 * Args: 1063 * context - Context pointer set with 1064 * cras_client_set_state_change_callback_context(). 1065 */ 1066 typedef void (*cras_client_nodes_changed_callback)(void* context); 1067 1068 /* Active node change callback. 1069 * 1070 * Args: 1071 * context - Context pointer set with 1072 * cras_client_set_state_change_callback_context(). 1073 * direction - Indicates the direction of the selected node. 1074 * node_id - The ID of the selected node. Special device ID values 1075 * defined by CRAS_SPECIAL_DEVICE will be used when no other 1076 * device or node is selected or between selections. 1077 */ 1078 typedef void (*cras_client_active_node_changed_callback)( 1079 void* context, enum CRAS_STREAM_DIRECTION direction, 1080 cras_node_id_t node_id); 1081 1082 /* Output node volume change callback. 1083 * 1084 * Args: 1085 * context - Context pointer set with 1086 * cras_client_set_state_change_callback_context(). 1087 * node_id - The ID of the output node. 1088 * volume - The volume for this node with range 0 to 100. 1089 */ 1090 typedef void (*cras_client_output_node_volume_changed_callback)( 1091 void* context, cras_node_id_t node_id, int32_t volume); 1092 1093 /* Node left right swapped change callback. 1094 * 1095 * Args: 1096 * context - Context pointer set with 1097 * cras_client_set_state_change_callback_context(). 1098 * node_id - The ID of the node. 1099 * swapped - Non-zero if the node is left-right swapped, zero otherwise. 1100 */ 1101 typedef void (*cras_client_node_left_right_swapped_changed_callback)( 1102 void* context, cras_node_id_t node_id, int swapped); 1103 1104 /* Input node gain change callback. 1105 * Args: 1106 * context - Context pointer set with 1107 * cras_client_set_state_change_callback_context(). 1108 * node_id - The ID of the input node. 1109 * gain - The gain for this node in centi-decibels. 1110 */ 1111 typedef void (*cras_client_input_node_gain_changed_callback)( 1112 void* context, cras_node_id_t node_id, int32_t gain); 1113 1114 /* Number of active streams change callback. 1115 * 1116 * Args: 1117 * context - Context pointer set with 1118 * cras_client_set_state_change_callback_context(). 1119 * direction - Indicates the direction of the stream's node. 1120 * num_active_streams - The number of active streams. 1121 */ 1122 typedef void (*cras_client_num_active_streams_changed_callback)( 1123 void* context, enum CRAS_STREAM_DIRECTION direction, 1124 uint32_t num_active_streams); 1125 1126 /* Set system state information callbacks. 1127 * NOTE: These callbacks are executed from the client control thread. 1128 * Each state change callback is given the context pointer set with 1129 * cras_client_set_state_change_callback_context(). The context pointer is 1130 * NULL by default. 1131 * Args: 1132 * client - The client from cras_client_create. 1133 * cb - The callback, or NULL to disable the call-back. 1134 * Returns: 1135 * 0 for success or negative errno error code on error. 1136 */ 1137 int cras_client_set_output_volume_changed_callback( 1138 struct cras_client *client, 1139 cras_client_output_volume_changed_callback cb); 1140 int cras_client_set_output_mute_changed_callback( 1141 struct cras_client *client, 1142 cras_client_output_mute_changed_callback cb); 1143 int cras_client_set_capture_gain_changed_callback( 1144 struct cras_client *client, 1145 cras_client_capture_gain_changed_callback cb); 1146 int cras_client_set_capture_mute_changed_callback( 1147 struct cras_client *client, 1148 cras_client_capture_mute_changed_callback cb); 1149 int cras_client_set_nodes_changed_callback( 1150 struct cras_client *client, 1151 cras_client_nodes_changed_callback cb); 1152 int cras_client_set_active_node_changed_callback( 1153 struct cras_client *client, 1154 cras_client_active_node_changed_callback cb); 1155 int cras_client_set_output_node_volume_changed_callback( 1156 struct cras_client *client, 1157 cras_client_output_node_volume_changed_callback cb); 1158 int cras_client_set_node_left_right_swapped_changed_callback( 1159 struct cras_client *client, 1160 cras_client_node_left_right_swapped_changed_callback cb); 1161 int cras_client_set_input_node_gain_changed_callback( 1162 struct cras_client *client, 1163 cras_client_input_node_gain_changed_callback cb); 1164 int cras_client_set_num_active_streams_changed_callback( 1165 struct cras_client *client, 1166 cras_client_num_active_streams_changed_callback cb); 1167 1168 #ifdef __cplusplus 1169 } 1170 #endif 1171 1172 #endif /* CRAS_CLIENT_H_ */ 1173