Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Bluetooth Media Control Service (MCS) APIs.
4 : */
5 : /*
6 : * Copyright (c) 2019 - 2024 Nordic Semiconductor ASA
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 :
11 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_MCS_H_
12 : #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_MCS_H_
13 :
14 : /**
15 : * @brief Media Control Service (MCS)
16 : *
17 : * @defgroup bt_mcs Media Control Service (MCS)
18 : *
19 : * @since 3.0
20 : * @version 0.8.0
21 : *
22 : * @ingroup bluetooth
23 : * @{
24 : *
25 : * Definitions and types related to the Media Control Service and Media Control
26 : * Profile specifications.
27 : */
28 :
29 : #include <zephyr/sys/util.h>
30 : #include <zephyr/sys/util_macro.h>
31 :
32 : #ifdef __cplusplus
33 : extern "C" {
34 : #endif
35 :
36 : /**
37 : * A characteristic value has changed while a Read Long Value Characteristic sub-procedure is in
38 : * progress.
39 : */
40 1 : #define BT_MCS_ERR_LONG_VAL_CHANGED 0x80
41 :
42 : /**
43 : * @name Playback speeds
44 : *
45 : * The playback speed (s) is calculated by the value of 2 to the power of p divided by 64.
46 : * All values from -128 to 127 allowed, only some examples defined.
47 : * @{
48 : */
49 : /** Minimum playback speed, resulting in 25 % speed */
50 1 : #define BT_MCS_PLAYBACK_SPEED_MIN -128
51 : /** Quarter playback speed, resulting in 25 % speed */
52 1 : #define BT_MCS_PLAYBACK_SPEED_QUARTER -128
53 : /** Half playback speed, resulting in 50 % speed */
54 1 : #define BT_MCS_PLAYBACK_SPEED_HALF -64
55 : /** Unity playback speed, resulting in 100 % speed */
56 1 : #define BT_MCS_PLAYBACK_SPEED_UNITY 0
57 : /** Double playback speed, resulting in 200 % speed */
58 1 : #define BT_MCS_PLAYBACK_SPEED_DOUBLE 64
59 : /** Max playback speed, resulting in 395.7 % speed (nearly 400 %) */
60 1 : #define BT_MCS_PLAYBACK_SPEED_MAX 127
61 : /** @} */
62 :
63 : /**
64 : * @name Seeking speed
65 : *
66 : * The allowed values for seeking speed are the range -64 to -4
67 : * (endpoints included), the value 0, and the range 4 to 64
68 : * (endpoints included).
69 : * @{
70 : */
71 : /** Maximum seeking speed - Can be negated */
72 1 : #define BT_MCS_SEEKING_SPEED_FACTOR_MAX 64
73 : /** Minimum seeking speed - Can be negated */
74 1 : #define BT_MCS_SEEKING_SPEED_FACTOR_MIN 4
75 : /** No seeking */
76 1 : #define BT_MCS_SEEKING_SPEED_FACTOR_ZERO 0
77 : /** @} */
78 :
79 : /**
80 : * @name Playing orders
81 : * @{
82 : */
83 : /** A single track is played once; there is no next track. */
84 1 : #define BT_MCS_PLAYING_ORDER_SINGLE_ONCE 0X01
85 : /** A single track is played repeatedly; the next track is the current track. */
86 1 : #define BT_MCS_PLAYING_ORDER_SINGLE_REPEAT 0x02
87 : /** The tracks within a group are played once in track order. */
88 1 : #define BT_MCS_PLAYING_ORDER_INORDER_ONCE 0x03
89 : /** The tracks within a group are played in track order repeatedly. */
90 1 : #define BT_MCS_PLAYING_ORDER_INORDER_REPEAT 0x04
91 : /** The tracks within a group are played once only from the oldest first. */
92 1 : #define BT_MCS_PLAYING_ORDER_OLDEST_ONCE 0x05
93 : /** The tracks within a group are played from the oldest first repeatedly. */
94 1 : #define BT_MCS_PLAYING_ORDER_OLDEST_REPEAT 0x06
95 : /** The tracks within a group are played once only from the newest first. */
96 1 : #define BT_MCS_PLAYING_ORDER_NEWEST_ONCE 0x07
97 : /** The tracks within a group are played from the newest first repeatedly. */
98 1 : #define BT_MCS_PLAYING_ORDER_NEWEST_REPEAT 0x08
99 : /** The tracks within a group are played in random order once. */
100 1 : #define BT_MCS_PLAYING_ORDER_SHUFFLE_ONCE 0x09
101 : /** The tracks within a group are played in random order repeatedly. */
102 1 : #define BT_MCS_PLAYING_ORDER_SHUFFLE_REPEAT 0x0a
103 : /** @} */
104 :
105 : /** @name Playing orders supported
106 : *
107 : * A bitmap, in the same order as the playing orders above.
108 : * Note that playing order 1 corresponds to bit 0, and so on.
109 : * @{
110 : */
111 : /** A single track is played once; there is no next track. */
112 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_ONCE BIT(0)
113 : /** A single track is played repeatedly; the next track is the current track. */
114 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT BIT(1)
115 : /** The tracks within a group are played once in track order. */
116 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE BIT(2)
117 : /** The tracks within a group are played in track order repeatedly. */
118 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_REPEAT BIT(3)
119 : /** The tracks within a group are played once only from the oldest first. */
120 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE BIT(4)
121 : /** The tracks within a group are played from the oldest first repeatedly. */
122 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_REPEAT BIT(5)
123 : /** The tracks within a group are played once only from the newest first. */
124 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE BIT(6)
125 : /** The tracks within a group are played from the newest first repeatedly. */
126 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT BIT(7)
127 : /** The tracks within a group are played in random order once. */
128 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE BIT(8)
129 : /** The tracks within a group are played in random order repeatedly. */
130 1 : #define BT_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_REPEAT BIT(9)
131 : /** @} */
132 :
133 : /**
134 : * @name Media states
135 : * @{
136 : */
137 : /** The current track is invalid, and no track has been selected. */
138 1 : #define BT_MCS_MEDIA_STATE_INACTIVE 0x00
139 : /** The media player is playing the current track. */
140 1 : #define BT_MCS_MEDIA_STATE_PLAYING 0x01
141 : /** The current track is paused. The media player has a current track, but it is not being played */
142 1 : #define BT_MCS_MEDIA_STATE_PAUSED 0x02
143 : /** The current track is fast forwarding or fast rewinding. */
144 1 : #define BT_MCS_MEDIA_STATE_SEEKING 0x03
145 : /** @} */
146 :
147 : /**
148 : * @name Media control point opcodes
149 : * @{
150 : */
151 : /** Start playing the current track. */
152 1 : #define BT_MCS_OPC_PLAY 0x01
153 : /** Pause playing the current track. */
154 1 : #define BT_MCS_OPC_PAUSE 0x02
155 : /** Fast rewind the current track. */
156 1 : #define BT_MCS_OPC_FAST_REWIND 0x03
157 : /** Fast forward the current track. */
158 1 : #define BT_MCS_OPC_FAST_FORWARD 0x04
159 : /**
160 : * Stop current activity and return to the paused state and set the current track position to the
161 : * start of the current track.
162 : */
163 1 : #define BT_MCS_OPC_STOP 0x05
164 :
165 : /** Set a new current track position relative to the current track position. */
166 1 : #define BT_MCS_OPC_MOVE_RELATIVE 0x10
167 :
168 : /**
169 : * Set the current track position to the starting position of the previous segment of the current
170 : * track.
171 : */
172 1 : #define BT_MCS_OPC_PREV_SEGMENT 0x20
173 : /**
174 : * Set the current track position to the starting position of
175 : * the next segment of the current track.
176 : */
177 1 : #define BT_MCS_OPC_NEXT_SEGMENT 0x21
178 : /**
179 : * Set the current track position to the starting position of
180 : * the first segment of the current track.
181 : */
182 1 : #define BT_MCS_OPC_FIRST_SEGMENT 0x22
183 : /**
184 : * Set the current track position to the starting position of
185 : * the last segment of the current track.
186 : */
187 1 : #define BT_MCS_OPC_LAST_SEGMENT 0x23
188 : /**
189 : * Set the current track position to the starting position of
190 : * the nth segment of the current track.
191 : */
192 1 : #define BT_MCS_OPC_GOTO_SEGMENT 0x24
193 :
194 : /** Set the current track to the previous track based on the playing order. */
195 1 : #define BT_MCS_OPC_PREV_TRACK 0x30
196 : /** Set the current track to the next track based on the playing order. */
197 1 : #define BT_MCS_OPC_NEXT_TRACK 0x31
198 : /** Set the current track to the first track based on the playing order. */
199 1 : #define BT_MCS_OPC_FIRST_TRACK 0x32
200 : /** Set the current track to the last track based on the playing order. */
201 1 : #define BT_MCS_OPC_LAST_TRACK 0x33
202 : /** Set the current track to the nth track based on the playing order. */
203 1 : #define BT_MCS_OPC_GOTO_TRACK 0x34
204 :
205 : /** Set the current group to the previous group in the sequence of groups. */
206 1 : #define BT_MCS_OPC_PREV_GROUP 0x40
207 : /** Set the current group to the next group in the sequence of groups. */
208 1 : #define BT_MCS_OPC_NEXT_GROUP 0x41
209 : /** Set the current group to the first group in the sequence of groups. */
210 1 : #define BT_MCS_OPC_FIRST_GROUP 0x42
211 : /** Set the current group to the last group in the sequence of groups. */
212 1 : #define BT_MCS_OPC_LAST_GROUP 0x43
213 : /** Set the current group to the nth group in the sequence of groups. */
214 1 : #define BT_MCS_OPC_GOTO_GROUP 0x44
215 : /** @} */
216 :
217 : /** Media control point supported opcodes length */
218 1 : #define BT_MCS_OPCODES_SUPPORTED_LEN 4
219 :
220 : /**
221 : * @name Media control point supported opcodes values
222 : * @{
223 : */
224 : /** Support the Play opcode */
225 1 : #define BT_MCS_OPC_SUP_PLAY BIT(0)
226 : /** Support the Pause opcode */
227 1 : #define BT_MCS_OPC_SUP_PAUSE BIT(1)
228 : /** Support the Fast Rewind opcode */
229 1 : #define BT_MCS_OPC_SUP_FAST_REWIND BIT(2)
230 : /** Support the Fast Forward opcode */
231 1 : #define BT_MCS_OPC_SUP_FAST_FORWARD BIT(3)
232 : /** Support the Stop opcode */
233 1 : #define BT_MCS_OPC_SUP_STOP BIT(4)
234 :
235 : /** Support the Move Relative opcode */
236 1 : #define BT_MCS_OPC_SUP_MOVE_RELATIVE BIT(5)
237 :
238 : /** Support the Previous Segment opcode */
239 1 : #define BT_MCS_OPC_SUP_PREV_SEGMENT BIT(6)
240 : /** Support the Next Segment opcode */
241 1 : #define BT_MCS_OPC_SUP_NEXT_SEGMENT BIT(7)
242 : /** Support the First Segment opcode */
243 1 : #define BT_MCS_OPC_SUP_FIRST_SEGMENT BIT(8)
244 : /** Support the Last Segment opcode */
245 1 : #define BT_MCS_OPC_SUP_LAST_SEGMENT BIT(9)
246 : /** Support the Goto Segment opcode */
247 1 : #define BT_MCS_OPC_SUP_GOTO_SEGMENT BIT(10)
248 :
249 : /** Support the Previous Track opcode */
250 1 : #define BT_MCS_OPC_SUP_PREV_TRACK BIT(11)
251 : /** Support the Next Track opcode */
252 1 : #define BT_MCS_OPC_SUP_NEXT_TRACK BIT(12)
253 : /** Support the First Track opcode */
254 1 : #define BT_MCS_OPC_SUP_FIRST_TRACK BIT(13)
255 : /** Support the Last Track opcode */
256 1 : #define BT_MCS_OPC_SUP_LAST_TRACK BIT(14)
257 : /** Support the Goto Track opcode */
258 1 : #define BT_MCS_OPC_SUP_GOTO_TRACK BIT(15)
259 :
260 : /** Support the Previous Group opcode */
261 1 : #define BT_MCS_OPC_SUP_PREV_GROUP BIT(16)
262 : /** Support the Next Group opcode */
263 1 : #define BT_MCS_OPC_SUP_NEXT_GROUP BIT(17)
264 : /** Support the First Group opcode */
265 1 : #define BT_MCS_OPC_SUP_FIRST_GROUP BIT(18)
266 : /** Support the Last Group opcode */
267 1 : #define BT_MCS_OPC_SUP_LAST_GROUP BIT(19)
268 : /** Support the Goto Group opcode */
269 1 : #define BT_MCS_OPC_SUP_GOTO_GROUP BIT(20)
270 : /** @} */
271 :
272 : /**
273 : * @name Media control point notification result codes
274 : * @{
275 : */
276 : /** Action requested by the opcode write was completed successfully. */
277 1 : #define BT_MCS_OPC_NTF_SUCCESS 0x01
278 : /** An invalid or unsupported opcode was used for the Media Control Point write. */
279 1 : #define BT_MCS_OPC_NTF_NOT_SUPPORTED 0x02
280 : /**
281 : * The Media Player State characteristic value is Inactive when the opcode is received or the
282 : * result of the requested action of the opcode results in the Media Player State characteristic
283 : * being set to Inactive.
284 : */
285 1 : #define BT_MCS_OPC_NTF_PLAYER_INACTIVE 0x03
286 : /**
287 : * The requested action of any Media Control Point write cannot be completed successfully because of
288 : * a condition within the player.
289 : */
290 1 : #define BT_MCS_OPC_NTF_CANNOT_BE_COMPLETED 0x04
291 : /** @} */
292 :
293 : /**
294 : * @name Search control point type values
295 : *
296 : * Reference: Media Control Service spec v1.0 section 3.20.2
297 : * @{
298 : */
299 : /** Search for Track Name */
300 1 : #define BT_MCS_SEARCH_TYPE_TRACK_NAME 0x01
301 : /** Search for Artist Name */
302 1 : #define BT_MCS_SEARCH_TYPE_ARTIST_NAME 0x02
303 : /** Search for Album Name */
304 1 : #define BT_MCS_SEARCH_TYPE_ALBUM_NAME 0x03
305 : /** Search for Group Name */
306 1 : #define BT_MCS_SEARCH_TYPE_GROUP_NAME 0x04
307 : /** Search for Earliest Year */
308 1 : #define BT_MCS_SEARCH_TYPE_EARLIEST_YEAR 0x05
309 : /** Search for Latest Year */
310 1 : #define BT_MCS_SEARCH_TYPE_LATEST_YEAR 0x06
311 : /** Search for Genre */
312 1 : #define BT_MCS_SEARCH_TYPE_GENRE 0x07
313 : /** Search for Tracks only */
314 1 : #define BT_MCS_SEARCH_TYPE_ONLY_TRACKS 0x08
315 : /** Search for Groups only */
316 1 : #define BT_MCS_SEARCH_TYPE_ONLY_GROUPS 0x09
317 : /** @} */
318 :
319 : /**
320 : * @brief Search control point minimum length
321 : *
322 : * At least one search control item (SCI), consisting of the length octet and the type octet.
323 : * (The * parameter field may be empty.)
324 : */
325 1 : #define SEARCH_LEN_MIN 2
326 :
327 : /** Search control point maximum length */
328 1 : #define SEARCH_LEN_MAX 64
329 :
330 : /**
331 : * @brief Search control point item (SCI) minimum length
332 : *
333 : * An SCI length can be as little as one byte, for an SCI that has only the type field.
334 : * (The SCI len is the length of type + param.)
335 : */
336 : #define SEARCH_SCI_LEN_MIN 1 /* An SCI length can be as little as one byte,
337 : * for an SCI that has only the type field.
338 : * (The SCI len is the length of type + param.)
339 1 : */
340 :
341 : /** Search parameters maximum length */
342 1 : #define SEARCH_PARAM_MAX 62
343 :
344 : /**
345 : * @name Search notification result codes
346 : *
347 : * Reference: Media Control Service spec v1.0 section 3.20.2
348 : * @{
349 : */
350 : /** Search request was accepted; search has started. */
351 1 : #define BT_MCS_SCP_NTF_SUCCESS 0x01
352 : /** Search request was invalid; no search started. */
353 1 : #define BT_MCS_SCP_NTF_FAILURE 0x02
354 : /** @} */
355 :
356 : /**
357 : * @name Group object object types
358 : *
359 : * Reference: Media Control Service spec v1.0 section 4.4.1
360 : * @{
361 : */
362 : /** Group object type is track */
363 1 : #define BT_MCS_GROUP_OBJECT_TRACK_TYPE 0x00
364 : /** Group object type is group */
365 1 : #define BT_MCS_GROUP_OBJECT_GROUP_TYPE 0x01
366 : /** @} */
367 :
368 : #ifdef __cplusplus
369 : }
370 : #endif
371 :
372 : /**
373 : * @}
374 : */
375 :
376 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_MCS_H_ */
|
