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