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 #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 #define BT_MCS_PLAYBACK_SPEED_MIN -128 51 /** Quarter playback speed, resulting in 25 % speed */ 52 #define BT_MCS_PLAYBACK_SPEED_QUARTER -128 53 /** Half playback speed, resulting in 50 % speed */ 54 #define BT_MCS_PLAYBACK_SPEED_HALF -64 55 /** Unity playback speed, resulting in 100 % speed */ 56 #define BT_MCS_PLAYBACK_SPEED_UNITY 0 57 /** Double playback speed, resulting in 200 % speed */ 58 #define BT_MCS_PLAYBACK_SPEED_DOUBLE 64 59 /** Max playback speed, resulting in 395.7 % speed (nearly 400 %) */ 60 #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 #define BT_MCS_SEEKING_SPEED_FACTOR_MAX 64 73 /** Minimum seeking speed - Can be negated */ 74 #define BT_MCS_SEEKING_SPEED_FACTOR_MIN 4 75 /** No seeking */ 76 #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 #define BT_MCS_PLAYING_ORDER_SINGLE_ONCE 0X01 85 /** A single track is played repeatedly; the next track is the current track. */ 86 #define BT_MCS_PLAYING_ORDER_SINGLE_REPEAT 0x02 87 /** The tracks within a group are played once in track order. */ 88 #define BT_MCS_PLAYING_ORDER_INORDER_ONCE 0x03 89 /** The tracks within a group are played in track order repeatedly. */ 90 #define BT_MCS_PLAYING_ORDER_INORDER_REPEAT 0x04 91 /** The tracks within a group are played once only from the oldest first. */ 92 #define BT_MCS_PLAYING_ORDER_OLDEST_ONCE 0x05 93 /** The tracks within a group are played from the oldest first repeatedly. */ 94 #define BT_MCS_PLAYING_ORDER_OLDEST_REPEAT 0x06 95 /** The tracks within a group are played once only from the newest first. */ 96 #define BT_MCS_PLAYING_ORDER_NEWEST_ONCE 0x07 97 /** The tracks within a group are played from the newest first repeatedly. */ 98 #define BT_MCS_PLAYING_ORDER_NEWEST_REPEAT 0x08 99 /** The tracks within a group are played in random order once. */ 100 #define BT_MCS_PLAYING_ORDER_SHUFFLE_ONCE 0x09 101 /** The tracks within a group are played in random order repeatedly. */ 102 #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 #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 #define BT_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT BIT(1) 115 /** The tracks within a group are played once in track order. */ 116 #define BT_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE BIT(2) 117 /** The tracks within a group are played in track order repeatedly. */ 118 #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 #define BT_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE BIT(4) 121 /** The tracks within a group are played from the oldest first repeatedly. */ 122 #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 #define BT_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE BIT(6) 125 /** The tracks within a group are played from the newest first repeatedly. */ 126 #define BT_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT BIT(7) 127 /** The tracks within a group are played in random order once. */ 128 #define BT_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE BIT(8) 129 /** The tracks within a group are played in random order repeatedly. */ 130 #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 #define BT_MCS_MEDIA_STATE_INACTIVE 0x00 139 /** The media player is playing the current track. */ 140 #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 #define BT_MCS_MEDIA_STATE_PAUSED 0x02 143 /** The current track is fast forwarding or fast rewinding. */ 144 #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 #define BT_MCS_OPC_PLAY 0x01 153 /** Pause playing the current track. */ 154 #define BT_MCS_OPC_PAUSE 0x02 155 /** Fast rewind the current track. */ 156 #define BT_MCS_OPC_FAST_REWIND 0x03 157 /** Fast forward the current track. */ 158 #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 #define BT_MCS_OPC_STOP 0x05 164 165 /** Set a new current track position relative to the current track position. */ 166 #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 #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 #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 #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 #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 #define BT_MCS_OPC_GOTO_SEGMENT 0x24 193 194 /** Set the current track to the previous track based on the playing order. */ 195 #define BT_MCS_OPC_PREV_TRACK 0x30 196 /** Set the current track to the next track based on the playing order. */ 197 #define BT_MCS_OPC_NEXT_TRACK 0x31 198 /** Set the current track to the first track based on the playing order. */ 199 #define BT_MCS_OPC_FIRST_TRACK 0x32 200 /** Set the current track to the last track based on the playing order. */ 201 #define BT_MCS_OPC_LAST_TRACK 0x33 202 /** Set the current track to the nth track based on the playing order. */ 203 #define BT_MCS_OPC_GOTO_TRACK 0x34 204 205 /** Set the current group to the previous group in the sequence of groups. */ 206 #define BT_MCS_OPC_PREV_GROUP 0x40 207 /** Set the current group to the next group in the sequence of groups. */ 208 #define BT_MCS_OPC_NEXT_GROUP 0x41 209 /** Set the current group to the first group in the sequence of groups. */ 210 #define BT_MCS_OPC_FIRST_GROUP 0x42 211 /** Set the current group to the last group in the sequence of groups. */ 212 #define BT_MCS_OPC_LAST_GROUP 0x43 213 /** Set the current group to the nth group in the sequence of groups. */ 214 #define BT_MCS_OPC_GOTO_GROUP 0x44 215 /** @} */ 216 217 /** Media control point supported opcodes length */ 218 #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 #define BT_MCS_OPC_SUP_PLAY BIT(0) 226 /** Support the Pause opcode */ 227 #define BT_MCS_OPC_SUP_PAUSE BIT(1) 228 /** Support the Fast Rewind opcode */ 229 #define BT_MCS_OPC_SUP_FAST_REWIND BIT(2) 230 /** Support the Fast Forward opcode */ 231 #define BT_MCS_OPC_SUP_FAST_FORWARD BIT(3) 232 /** Support the Stop opcode */ 233 #define BT_MCS_OPC_SUP_STOP BIT(4) 234 235 /** Support the Move Relative opcode */ 236 #define BT_MCS_OPC_SUP_MOVE_RELATIVE BIT(5) 237 238 /** Support the Previous Segment opcode */ 239 #define BT_MCS_OPC_SUP_PREV_SEGMENT BIT(6) 240 /** Support the Next Segment opcode */ 241 #define BT_MCS_OPC_SUP_NEXT_SEGMENT BIT(7) 242 /** Support the First Segment opcode */ 243 #define BT_MCS_OPC_SUP_FIRST_SEGMENT BIT(8) 244 /** Support the Last Segment opcode */ 245 #define BT_MCS_OPC_SUP_LAST_SEGMENT BIT(9) 246 /** Support the Goto Segment opcode */ 247 #define BT_MCS_OPC_SUP_GOTO_SEGMENT BIT(10) 248 249 /** Support the Previous Track opcode */ 250 #define BT_MCS_OPC_SUP_PREV_TRACK BIT(11) 251 /** Support the Next Track opcode */ 252 #define BT_MCS_OPC_SUP_NEXT_TRACK BIT(12) 253 /** Support the First Track opcode */ 254 #define BT_MCS_OPC_SUP_FIRST_TRACK BIT(13) 255 /** Support the Last Track opcode */ 256 #define BT_MCS_OPC_SUP_LAST_TRACK BIT(14) 257 /** Support the Goto Track opcode */ 258 #define BT_MCS_OPC_SUP_GOTO_TRACK BIT(15) 259 260 /** Support the Previous Group opcode */ 261 #define BT_MCS_OPC_SUP_PREV_GROUP BIT(16) 262 /** Support the Next Group opcode */ 263 #define BT_MCS_OPC_SUP_NEXT_GROUP BIT(17) 264 /** Support the First Group opcode */ 265 #define BT_MCS_OPC_SUP_FIRST_GROUP BIT(18) 266 /** Support the Last Group opcode */ 267 #define BT_MCS_OPC_SUP_LAST_GROUP BIT(19) 268 /** Support the Goto Group opcode */ 269 #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 #define BT_MCS_OPC_NTF_SUCCESS 0x01 278 /** An invalid or unsupported opcode was used for the Media Control Point write. */ 279 #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 #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 #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 #define BT_MCS_SEARCH_TYPE_TRACK_NAME 0x01 301 /** Search for Artist Name */ 302 #define BT_MCS_SEARCH_TYPE_ARTIST_NAME 0x02 303 /** Search for Album Name */ 304 #define BT_MCS_SEARCH_TYPE_ALBUM_NAME 0x03 305 /** Search for Group Name */ 306 #define BT_MCS_SEARCH_TYPE_GROUP_NAME 0x04 307 /** Search for Earliest Year */ 308 #define BT_MCS_SEARCH_TYPE_EARLIEST_YEAR 0x05 309 /** Search for Latest Year */ 310 #define BT_MCS_SEARCH_TYPE_LATEST_YEAR 0x06 311 /** Search for Genre */ 312 #define BT_MCS_SEARCH_TYPE_GENRE 0x07 313 /** Search for Tracks only */ 314 #define BT_MCS_SEARCH_TYPE_ONLY_TRACKS 0x08 315 /** Search for Groups only */ 316 #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 #define SEARCH_LEN_MIN 2 326 327 /** Search control point maximum length */ 328 #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 */ 340 341 /** Search parameters maximum length */ 342 #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 #define BT_MCS_SCP_NTF_SUCCESS 0x01 352 /** Search request was invalid; no search started. */ 353 #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 #define BT_MCS_GROUP_OBJECT_TRACK_TYPE 0x00 364 /** Group object type is group */ 365 #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_ */ 377
