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