README.dbus-api
1CRAS dbus methods and signals.
2==============================
3
4Service org.chromium.cras
5Interface org.chromium.cras.Control
6Object Path /org/chromium/cras
7
8Methods void SetOutputVolume(int32 volume)
9
10 Sets the volume of the system. Volume ranges from
11 0 to 100, and will be translated to dB based on the
12 output-specific volume curve.
13
14 void SetOutputNodeVolume(uint64 node_id, int32 volume)
15
16 Sets the volume of the given node. Volume ranges from
17 0 to 100, and will be translated to dB based on the
18 output-specific volume curve.
19
20 void SwapLeftRight(uint64 node_id, boolean swap)
21
22 Swap the left and right channel of the given node.
23 Message will be dropped if this feature is not supported.
24
25 void SetOutputMute(boolean mute_on)
26
27 Sets the system output mute.
28
29 void SetOutputUserMute(boolean mute_on)
30
31 Sets the system output mute from user action.
32
33 void SetInputNodeGain(uint64 node_id, int32 gain)
34
35 Sets the capture gain of the node. gain is a 0-100
36 integer which linearly maps [0, 50] to range [-40dB, 0dB]
37 and [50, 100] to [0dB, 20dB],
38 Default gain value is 50, which is 0dB.
39
40 void SetInputMute(boolean mute_on)
41
42 Sets the capture mute state of the system. Recordings
43 will be muted when this is set.
44
45 void GetVolumeState()
46
47 Returns the volume and capture gain as follows:
48 int32 output_volume (0-100)
49 boolean output_mute
50 int32 input_gain (in dBFS * 100)
51 boolean input_mute
52 boolean output_user_mute
53
54 void GetDefaultOutputBufferSize()
55
56 Returns the default output buffer size in frames.
57
58 {dict},{dict},... GetNodes()
59
60 Returns information about nodes. A node can be either
61 output or input but not both. An output node is
62 something like a speaker or a headphone, and an input
63 node is like a microphone. The return value is a
64 sequence of dicts mapping from strings to variants
65 (e.g. signature "a{sv}a{sv}" for two nodes). Each dict
66 contains information about a node.
67
68 Each dict contains the following properties:
69 boolean IsInput
70 false for output nodes, true for input
71 nodes.
72 uint64 Id
73 The id of this node. It is unique among
74 all nodes including both output and
75 input nodes.
76 string Type
77 The type of this node. It can be one of
78 following values:
79 /* for output nodes. */
80 "INTERNAL_SPEAKER","HEADPHONE", "HDMI",
81 /* for input nodes. */
82 "INTERNAL_MIC", "MIC",
83 /* for both output and input nodes. */
84 "USB", "BLUETOOTH", "UNKNOWN",
85 string Name
86 The name of this node. For example,
87 "Speaker" or "Internal Mic".
88 string DeviceName
89 The name of the device that this node
90 belongs to. For example,
91 "HDA Intel PCH: CA0132 Analog:0,0" or
92 "Creative SB Arena Headset".
93 uint64 StableDeviceId
94 The stable ID does not change due to
95 device plug/unplug or reboot.
96 uint64 StableDeviceIdNew
97 The new stable ID. Keeping both stable
98 ID and stable ID new is for backward
99 compatibility.
100 boolean Active
101 Whether this node is currently used
102 for output/input. There is one active
103 node for output and one active node for
104 input.
105 uint64 PluggedTime
106 The time that this device was plugged
107 in. This value is in microseconds.
108 unit64 NodeVolume
109 The node volume indexed from 0 to 100.
110 unit64 NodeCaptureGain
111 The capture gain of node in dBFS * 100.
112 string HotwordModels
113 A string of comma-separated hotword
114 language model locales supported by this
115 node. e.g. "en_au,en_gb,en_us"
116 The string is empty if the node type is
117 not HOTWORD.
118
119 void GetSystemAecSupported();
120
121 Returns 1 if system echo cancellation is supported,
122 otherwise return 0.
123
124 void SetActiveOutputNode(uint64 node_id);
125
126 Requests the specified node to be used for
127 output. If node_id is 0 (which is not a valid
128 node id), cras will choose the active node
129 automatically.
130
131 void SetActiveInputNode(uint64 node_id);
132
133 Requests the specified node to be used for
134 input. If node_id is 0 (which is not a valid
135 node id), cras will choose the active node
136 automatically.
137
138 int32 GetNumberOfActiveStreams()
139
140 Returns the number of streams currently being
141 played or recorded.
142
143 int32 GetNumberOfActiveInputStreams()
144
145 Returns the number of streams currently using input hardware.
146
147 int32 GetNumberOfActiveOutputStreams()
148
149 Returns the number of streams currently using output hardware.
150
151 int32 IsAudioOutputActive()
152
153 Returns 1 if there are currently any active output streams,
154 excluding 'fake' streams that are not actually outputting any
155 audio. Returns 0 if there are no active streams, or all active
156 streams are 'fake' streams.
157
158 void SetGlobalOutputChannelRemix(int32 num_channels,
159 array:double coefficient)
160
161 Sets the conversion matrix for global output channel
162 remixing. The coefficient array represents an N * N
163 conversion matrix M, where N is num_channels, with
164 M[i][j] = coefficient[i * N + j].
165 The remix is done by multiplying the conversion matrix
166 to each N-channel PCM data, i.e M * [L, R] = [L', R']
167 For example, coefficient [0.1, 0.9, 0.4, 0.6] will
168 result in:
169 L' = 0.1 * L + 0.9 * R
170 R' = 0.4 * L + 0.6 * R
171
172 int32 SetHotwordModel(uint64_t node_id, string model_name)
173
174 Set the hotword language model on the specified node.
175 The node must have type HOTWORD and the model_name must
176 be one of the supported locales returned by
177 GetNodes() HotwordModels string.
178 Returns 0 on success, or a negative errno on failure.
179
180Signals OutputVolumeChanged(int32 volume)
181
182 Indicates that the output volume level has changed.
183
184 OutputMuteChanged(boolean muted, boolean user_muted)
185
186 Indicates that the output mute state has changed. muted
187 is true if the system is muted by a system process, such
188 as suspend or device switch. user_muted is set if the
189 system has been muted by user action such as the mute
190 key.
191
192 InputGainChanged(int32 gain)
193
194 Indicates what the system capture gain is now. gain
195 expressed in dBFS*100.
196
197 InputMuteChanged(boolean muted)
198
199 Indicates that the input mute state has changed.
200
201 NodesChanged()
202
203 Indicates that nodes are added/removed.
204
205 ActiveOutputNodeChanged(uint64 node_id)
206
207 Indicates that the active output node has changed.
208
209 ActiveInputNodeChanged(uint64 node_id)
210
211 Indicates that the active input node has changed.
212
213 OutputNodeVolumeChanged(uint64 node_id, int32 volume)
214
215 Indicates the volume of the given node.
216
217 NodeLeftRightSwappedChanged(uint64 node_id, boolean swapped)
218
219 Indicates the left and right channel swapping state of the
220 given node.
221
222 InputNodeGainChanged(uint64 node_id, int32 gain)
223
224 Indicates that the capture gain for the node is now gain
225 expressed in dBFS*100.
226
227 NumberOfActiveStreamsChanged(int32 num_active_streams)
228
229 Indicates the number of active streams has changed.
230
231 AudioOutputActiveStateChanged(boolean active)
232
233 Indicates active output state has changed.
234 See IsAudioOutputActive for details.
235
236 HotwordTriggered(int64 tv_sec, int64 tv_nsec)
237
238 Indicates that hotword was triggered at the given timestamp.
239
README.md
1CRAS = ChromeOS Audio Server
2===
3
4# Directories
5- [src/server](src/server) - the source for the sound server
6- [src/libcras](src/libcras) - client library for interacting with cras
7- [src/common](src/common) - files common to both the server and library
8- [src/tests](src/tests) - tests for cras and libcras
9- [src/fuzz](src/fuzz) - source code and build scripts for coverage-guided
10 fuzzers for CRAS
11
12# Building from source:
13```
14# Generate install-sh
15./git_prepare.sh
16
17# Configure
18CC=clang \
19CXX=clang++ \
20CXXFLAGS="-g -O2 -std=gnu++11 -Wall" \
21CFLAGS="-g -O2 -Wall" \
22./configure --disable-alsa-plugin
23
24# Compile
25make -j$(nproc)
26
27# Compile with unit tests
28make -j$(nproc) check
29
30# Install binaries to /usr/bin
31sudo make install
32```
33
34## Code complete for for editors
35You need to install [bear] first and generate [compile commands] for
36[language server plugins in editors] by
37```
38make clean && make compile_commands.json
39```
40Then you'll get `compile_commands.json` for editor.
41Import the JSON file to your editor and you'll get useful code complete
42features for CRAS and its unit tests.
43
44# Configuration:
45
46## Device Blocklisting:
47
48Blocklist of certain USB output device(s) is possible by modifying the config
49file `/etc/cras/device_blocklist`.
50
51The format of this file is as follows:
52```
53[USB_Outputs]
54 <vendor_id>_<product_id>_<checksum>_<device_index> = 1
55```
56Where vendor_id and product id are the USB identifiers for the card to
57blocklist. The checksum is the output of "cksum" command applied to the
58sysfs "descriptors" file of the device. The device index specifies the
59index of the output device in the card to blocklist. This is a bool
60parameter, so '= 1' enables the option.
61
62Example, blocklisting the non-functional output device reported by the C-Media
63based CAD-u1 mic:
64```
65[USB_Outputs]
66 0d8c_0008_00000000_0 = 1
67```
68
69## Card Configuration:
70
71There can be a config file for each sound alsa card on the system. This file
72lives in `/etc/cras/`. The file should be named with the card name returned by
73ALSA, the string in the second set of '[]' in the aplay -l output. The ini file
74has the following format.
75
76```
77[<output-node-name>] ; Name of the mixer control for this output.
78 <config-option> = <config-value>
79```
80output-node-name can be speficied in a few ways to link with the real node:
81- UCM device name - The name string following the SectionDevice label in UCM
82 config, i.e. HiFi.conf
83- Jack name - Name of the mixer control for mixer jack, or the gpio jack name
84 listed by 'evtest' command.
85- Mixer control name - e.g. "Headphone" or "Speaker", listed by
86 'amixer scontrols' command.
87
88Note that an output node matches to the output-node-name label in card config by
89priorty ordered above. For example if a node has UCM device, it will first
90search the config file for the UCM device name. When not found, jack name will
91be used for searching, and lastly the mixer output control name.
92
93config-option can be the following:
94- volume_curve - The type of volume curve, "simple_step" or "explicit".
95- Options valid and mandatory when volume_curve = simple_step:
96 - max_volume - The maximum volume for this output specified in dBFS * 100.
97 - volume_step - Number of dB per volume 'tick' specified in dBFS * 100.
98- Options valid and mandatory when volume_curve = explicit:
99 - dB_at_N - The value in dB*100 that should be used for the volume at step
100 "N". There must be one of these for each setting from N=0 to 100
101 inclusive.
102
103
104Example:
105This example configures the Headphones to have a max volume of -3dBFS with a
106step size of 0.75dBFS and the Speaker to have the curve specified by the steps
107given, which is a 1dBFS per step curve from max = +0.5dBFS to min = -99.5dBFS
108(volume step 10 is -89.5dBFS).
109
110```
111[Headphone]
112 volume_curve = simple_step
113 volume_step = 75
114 max_volume = -300
115[Speaker]
116 volume_curve = explicit
117 dB_at_0 = -9950
118 dB_at_1 = -9850
119 dB_at_2 = -9750
120 dB_at_3 = -9650
121 dB_at_4 = -9550
122 dB_at_5 = -9450
123 dB_at_6 = -9350
124 dB_at_7 = -9250
125 dB_at_8 = -9150
126 dB_at_9 = -9050
127 dB_at_10 = -8950
128 dB_at_11 = -8850
129 dB_at_12 = -8750
130 dB_at_13 = -8650
131 dB_at_14 = -8550
132 dB_at_15 = -8450
133 dB_at_16 = -8350
134 dB_at_17 = -8250
135 dB_at_18 = -8150
136 dB_at_19 = -8050
137 dB_at_20 = -7950
138 dB_at_21 = -7850
139 dB_at_22 = -7750
140 dB_at_23 = -7650
141 dB_at_24 = -7550
142 dB_at_25 = -7450
143 dB_at_26 = -7350
144 dB_at_27 = -7250
145 dB_at_28 = -7150
146 dB_at_29 = -7050
147 dB_at_30 = -6950
148 dB_at_31 = -6850
149 dB_at_32 = -6750
150 dB_at_33 = -6650
151 dB_at_34 = -6550
152 dB_at_35 = -6450
153 dB_at_36 = -6350
154 dB_at_37 = -6250
155 dB_at_38 = -6150
156 dB_at_39 = -6050
157 dB_at_40 = -5950
158 dB_at_41 = -5850
159 dB_at_42 = -5750
160 dB_at_43 = -5650
161 dB_at_44 = -5550
162 dB_at_45 = -5450
163 dB_at_46 = -5350
164 dB_at_47 = -5250
165 dB_at_48 = -5150
166 dB_at_49 = -5050
167 dB_at_50 = -4950
168 dB_at_51 = -4850
169 dB_at_52 = -4750
170 dB_at_53 = -4650
171 dB_at_54 = -4550
172 dB_at_55 = -4450
173 dB_at_56 = -4350
174 dB_at_57 = -4250
175 dB_at_58 = -4150
176 dB_at_59 = -4050
177 dB_at_60 = -3950
178 dB_at_61 = -3850
179 dB_at_62 = -3750
180 dB_at_63 = -3650
181 dB_at_64 = -3550
182 dB_at_65 = -3450
183 dB_at_66 = -3350
184 dB_at_67 = -3250
185 dB_at_68 = -3150
186 dB_at_69 = -3050
187 dB_at_70 = -2950
188 dB_at_71 = -2850
189 dB_at_72 = -2750
190 dB_at_73 = -2650
191 dB_at_74 = -2550
192 dB_at_75 = -2450
193 dB_at_76 = -2350
194 dB_at_77 = -2250
195 dB_at_78 = -2150
196 dB_at_79 = -2050
197 dB_at_80 = -1950
198 dB_at_81 = -1850
199 dB_at_82 = -1750
200 dB_at_83 = -1650
201 dB_at_84 = -1550
202 dB_at_85 = -1450
203 dB_at_86 = -1350
204 dB_at_87 = -1250
205 dB_at_88 = -1150
206 dB_at_89 = -1050
207 dB_at_90 = -950
208 dB_at_91 = -850
209 dB_at_92 = -750
210 dB_at_93 = -650
211 dB_at_94 = -550
212 dB_at_95 = -450
213 dB_at_96 = -350
214 dB_at_97 = -250
215 dB_at_98 = -150
216 dB_at_99 = -50
217 dB_at_100 = 50
218```
219
220[bear]: https://github.com/rizsotto/Bear
221[compile commands]: https://clang.llvm.org/extra/clangd/Installation.html#compile-commands-json
222[language server plugins in editors]: https://clang.llvm.org/extra/clangd/Installation.html#editor-plugins
223