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_ */
