doc/media-api.txt

   1 BlueZ D-Bus Media API description
   2 *********************************
   3
   4
   5 Media hierarchy
   6 ===============
   7
   8 Service         org.bluez
   9 Interface       org.bluez.Media1
  10 Object path     [variable prefix]/{hci0,hci1,...}
  11
  12 Methods         void RegisterEndpoint(object endpoint, dict properties)
  13
  14                         Register a local end point to sender, the sender can
  15                         register as many end points as it likes.
  16
  17                         Note: If the sender disconnects the end points are
  18                         automatically unregistered.
  19
  20                         possible properties:
  21
  22                                 string UUID:
  23
  24                                         UUID of the profile which the endpoint
  25                                         is for.
  26
  27                                 byte Codec:
  28
  29                                         Assigned number of codec that the
  30                                         endpoint implements. The values should
  31                                         match the profile specification which
  32                                         is indicated by the UUID.
  33
  34                                 array{byte} Capabilities:
  35
  36                                         Capabilities blob, it is used as it is
  37                                         so the size and byte order must match.
  38
  39                         Possible Errors: org.bluez.Error.InvalidArguments
  40                                          org.bluez.Error.NotSupported - emitted
  41                                          when interface for the end-point is
  42                                          disabled.
  43
  44                 void UnregisterEndpoint(object endpoint)
  45
  46                         Unregister sender end point.
  47
  48                 void RegisterPlayer(object player, dict properties)
  49
  50                         Register a media player object to sender, the sender
  51                         can register as many objects as it likes.
  52
  53                         Object must implement at least
  54                         org.mpris.MediaPlayer2.Player as defined in MPRIS 2.2
  55                         spec:
  56
  57                         http://specifications.freedesktop.org/mpris-spec/latest/
  58
  59                         Note: If the sender disconnects its objects are
  60                         automatically unregistered.
  61
  62                         Possible Errors: org.bluez.Error.InvalidArguments
  63                                          org.bluez.Error.NotSupported
  64
  65                 void UnregisterPlayer(object player)
  66
  67                         Unregister sender media player.
  68
  69
  70 Media Control hierarchy
  71 =======================
  72
  73 Service         org.bluez
  74 Interface       org.bluez.MediaControl1 [Deprecated]
  75 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
  76
  77 Methods         void Play()
  78
  79                         Resume playback.
  80
  81                 void Pause()
  82
  83                         Pause playback.
  84
  85                 void Stop()
  86
  87                         Stop playback.
  88
  89                 void Next()
  90
  91                         Next item.
  92
  93                 void Previous()
  94
  95                         Previous item.
  96
  97                 void VolumeUp()
  98
  99                         Adjust remote volume one step up
 100
 101                 void VolumeDown()
 102
 103                         Adjust remote volume one step down
 104
 105                 void FastForward()
 106
 107                         Fast forward playback, this action is only stopped
 108                         when another method in this interface is called.
 109
 110                 void Rewind()
 111
 112                         Rewind playback, this action is only stopped
 113                         when another method in this interface is called.
 114
 115 Properties
 116
 117                 boolean Connected [readonly]
 118
 119
 120 MediaPlayer1 hierarchy
 121 ======================
 122
 123 Service         org.bluez (Controller role)
 124 Interface       org.bluez.MediaPlayer1 [Experimental]
 125 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX
 126
 127 Methods         void Play()
 128
 129                         Resume playback.
 130
 131                 void Pause()
 132
 133                         Pause playback.
 134
 135                 void Stop()
 136
 137                         Stop playback.
 138
 139                 void Next()
 140
 141                         Next item.
 142
 143                 void Previous()
 144
 145                         Previous item.
 146
 147                 void FastForward()
 148
 149                         Fast forward playback, this action is only stopped
 150                         when another method in this interface is called.
 151
 152                 void Rewind()
 153
 154                         Rewind playback, this action is only stopped
 155                         when another method in this interface is called.
 156
 157 Properties      string Equalizer [readwrite]
 158
 159                         Possible values: "off" or "on"
 160
 161                 string Repeat [readwrite]
 162
 163                         Possible values: "off", "singletrack", "alltracks" or
 164                                         "group"
 165
 166                 string Shuffle [readwrite]
 167
 168                         Possible values: "off", "alltracks" or "group"
 169
 170                 string Scan [readwrite]
 171
 172                         Possible values: "off", "alltracks" or "group"
 173
 174                 string Status [readonly]
 175
 176                         Possible status: "playing", "stopped", "paused",
 177                                         "forward-seek", "reverse-seek"
 178                                         or "error"
 179
 180                 uint32 Position [readonly]
 181
 182                         Playback position in milliseconds. Changing the
 183                         position may generate additional events that will be
 184                         sent to the remote device. When position is 0 it means
 185                         the track is starting and when it's greater than or
 186                         equal to track's duration the track has ended. Note
 187                         that even if duration is not available in metadata it's
 188                         possible to signal its end by setting position to the
 189                         maximum uint32 value.
 190
 191                 dict Track [readonly]
 192
 193                         Track metadata.
 194
 195                         Possible values:
 196
 197                                 string Title:
 198
 199                                         Track title name
 200
 201                                 string Artist:
 202
 203                                         Track artist name
 204
 205                                 string Album:
 206
 207                                         Track album name
 208
 209                                 string Genre:
 210
 211                                         Track genre name
 212
 213                                 uint32 NumberOfTracks:
 214
 215                                         Number of tracks in total
 216
 217                                 uint32 TrackNumber:
 218
 219                                         Track number
 220
 221                                 uint32 Duration:
 222
 223                                         Track duration in milliseconds
 224
 225                 object Device [readonly]
 226
 227                         Device object path.
 228
 229                 string Name [readonly]
 230
 231                         Player name
 232
 233                 string Type [readonly]
 234
 235                         Player type
 236
 237                         Possible values:
 238
 239                                 "Audio"
 240                                 "Video"
 241                                 "Audio Broadcasting"
 242                                 "Video Broadcasting"
 243
 244                 string Subtype [readonly]
 245
 246                         Player subtype
 247
 248                         Possible values:
 249
 250                                 "Audio Book"
 251                                 "Podcast"
 252
 253                 boolean Browsable [readonly]
 254
 255                         If present indicates the player can be browsed using
 256                         MediaFolder interface.
 257
 258                         Possible values:
 259
 260                                 True: Supported and active
 261                                 False: Supported but inactive
 262
 263                         Note: If supported but inactive clients can enable it
 264                         by using MediaFolder interface but it might interfere
 265                         in the playback of other players.
 266
 267
 268                 boolean Searchable [readonly]
 269
 270                         If present indicates the player can be searched using
 271                         MediaFolder interface.
 272
 273                         Possible values:
 274
 275                                 True: Supported and active
 276                                 False: Supported but inactive
 277
 278                         Note: If supported but inactive clients can enable it
 279                         by using MediaFolder interface but it might interfere
 280                         in the playback of other players.
 281
 282                 object Playlist
 283
 284                         Playlist object path.
 285
 286 MediaFolder1 hierarchy
 287 ======================
 288
 289 Service         unique name (Target role)
 290                 org.bluez (Controller role)
 291 Interface       org.bluez.MediaFolder1 [Experimental]
 292 Object path     freely definable (Target role)
 293                 [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX
 294                 (Controller role)
 295
 296 Methods         object Search(string value, dict filter)
 297
 298                         Return a folder object containing the search result.
 299
 300                         To list the items found use the folder object returned
 301                         and pass to ChangeFolder.
 302
 303                 array{objects, properties} ListItems(dict filter)
 304
 305                         Return a list of items found
 306
 307                 void ChangeFolder(object folder)
 308
 309                         Change current folder.
 310
 311                         Note: By changing folder the items of previous folder
 312                         might be destroyed and have to be listed again, the
 313                         exception is NowPlaying folder which should be always
 314                         present while the player is active.
 315
 316 Properties      uint32 NumberOfItems [readonly]
 317
 318                         Number of items in the folder
 319
 320                 string Name [readonly]
 321
 322                         Folder name:
 323
 324                         Possible values:
 325                                 "/Filesystem/...": Filesystem scope
 326                                 "/NowPlaying/...": NowPlaying scope
 327
 328                         Note: /NowPlaying folder might not be listed if player
 329                         is stopped, folders created by Search are virtual so
 330                         once another Search is perform or the folder is
 331                         changed using ChangeFolder it will no longer be listed.
 332
 333 Filters         uint32 Start:
 334
 335                         Offset of the first item.
 336
 337                         Default value: 0
 338
 339                 uint32 End:
 340
 341                         Offset of the last item.
 342
 343                         Default value: NumbeOfItems
 344
 345                 array{string} Attributes
 346
 347                         Item properties that should be included in the list.
 348
 349                         Possible Values:
 350
 351                                 "title", "artist", "album", "genre",
 352                                 "number-of-tracks", "number", "duration"
 353
 354                         Default Value: All
 355
 356 MediaItem1 hierarchy
 357 ====================
 358
 359 Service         unique name (Target role)
 360                 org.bluez (Controller role)
 361 Interface       org.bluez.MediaItem1 [Experimental]
 362 Object path     freely definable (Target role)
 363                 [variable
 364                 prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX/itemX
 365                 (Controller role)
 366
 367 Methods         void Play()
 368
 369                         Play item
 370
 371                 void AddtoNowPlaying()
 372
 373                         Add item to now playing list
 374
 375 Properties      object Player [readonly]
 376
 377                         Player object path the item belongs to
 378
 379                 string Name [readonly]
 380
 381                         Item displayable name
 382
 383                 string Type [readonly]
 384
 385                         Item type
 386
 387                         Possible values: "video", "audio", "folder"
 388
 389                 string FolderType [readonly, optional]
 390
 391                         Folder type.
 392
 393                         Possible values: "mixed", "titles", "albums", "artists"
 394
 395                         Available if property Type is "Folder"
 396
 397                 boolean Playable [readonly, optional]
 398
 399                         Indicates if the item can be played
 400
 401                         Available if property Type is "folder"
 402
 403                 dict Metadata [readonly]
 404
 405                         Item metadata.
 406
 407                         Possible values:
 408
 409                                 string Title
 410
 411                                         Item title name
 412
 413                                         Available if property Type is "audio"
 414                                         or "video"
 415
 416                                 string Artist
 417
 418                                         Item artist name
 419
 420                                         Available if property Type is "audio"
 421                                         or "video"
 422
 423                                 string Album
 424
 425                                         Item album name
 426
 427                                         Available if property Type is "audio"
 428                                         or "video"
 429
 430                                 string Genre
 431
 432                                         Item genre name
 433
 434                                         Available if property Type is "audio"
 435                                         or "video"
 436
 437                                 uint32 NumberOfTracks
 438
 439                                         Item album number of tracks in total
 440
 441                                         Available if property Type is "audio"
 442                                         or "video"
 443
 444                                 uint32 Number
 445
 446                                         Item album number
 447
 448                                         Available if property Type is "audio"
 449                                         or "video"
 450
 451                                 uint32 Duration
 452
 453                                         Item duration in milliseconds
 454
 455                                         Available if property Type is "audio"
 456                                         or "video"
 457
 458 MediaEndpoint1 hierarchy
 459 ========================
 460
 461 Service         unique name
 462 Interface       org.bluez.MediaEndpoint1
 463 Object path     freely definable
 464
 465 Methods         void SetConfiguration(object transport, dict properties)
 466
 467                         Set configuration for the transport.
 468
 469                 array{byte} SelectConfiguration(array{byte} capabilities)
 470
 471                         Select preferable configuration from the supported
 472                         capabilities.
 473
 474                         Returns a configuration which can be used to setup
 475                         a transport.
 476
 477                         Note: There is no need to cache the selected
 478                         configuration since on success the configuration is
 479                         send back as parameter of SetConfiguration.
 480
 481                 void ClearConfiguration(object transport)
 482
 483                         Clear transport configuration.
 484
 485                 void Release()
 486
 487                         This method gets called when the service daemon
 488                         unregisters the endpoint. An endpoint can use it to do
 489                         cleanup tasks. There is no need to unregister the
 490                         endpoint, because when this method gets called it has
 491                         already been unregistered.
 492
 493
 494 MediaTransport1 hierarchy
 495 =========================
 496
 497 Service         org.bluez
 498 Interface       org.bluez.MediaTransport1
 499 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/fdX
 500
 501 Methods         fd, uint16, uint16 Acquire()
 502
 503                         Acquire transport file descriptor and the MTU for read
 504                         and write respectively.
 505
 506                         Possible Errors: org.bluez.Error.NotAuthorized
 507                                          org.bluez.Error.Failed
 508
 509                 fd, uint16, uint16 TryAcquire()
 510
 511                         Acquire transport file descriptor only if the transport
 512                         is in "pending" state at the time the message is
 513                         received by BlueZ. Otherwise no request will be sent
 514                         to the remote device and the function will just fail
 515                         with org.bluez.Error.NotAvailable.
 516
 517                         Possible Errors: org.bluez.Error.NotAuthorized
 518                                          org.bluez.Error.Failed
 519                                          org.bluez.Error.NotAvailable
 520
 521                 void Release()
 522
 523                         Releases file descriptor.
 524
 525 Properties      object Device [readonly]
 526
 527                         Device object which the transport is connected to.
 528
 529                 string UUID [readonly]
 530
 531                         UUID of the profile which the transport is for.
 532
 533                 byte Codec [readonly]
 534
 535                         Assigned number of codec that the transport support.
 536                         The values should match the profile specification which
 537                         is indicated by the UUID.
 538
 539                 array{byte} Configuration [readonly]
 540
 541                         Configuration blob, it is used as it is so the size and
 542                         byte order must match.
 543
 544                 string State [readonly]
 545
 546                         Indicates the state of the transport. Possible
 547                         values are:
 548                                 "idle": not streaming
 549                                 "pending": streaming but not acquired
 550                                 "active": streaming and acquired
 551
 552                 uint16 Delay [readwrite]
 553
 554                         Optional. Transport delay in 1/10 of millisecond, this
 555                         property is only writeable when the transport was
 556                         acquired by the sender.
 557
 558                 boolean NREC [readwrite]
 559
 560                         Optional and HFP specific (external to BlueZ).
 561                         Indicates if echo cancelling and noise reduction
 562                         functions are active in the transport, this
 563                         property is only writeable when the transport
 564                         was acquired by the sender.
 565
 566                 boolean InbandRingtone [readwrite]
 567
 568                         Optional and HFP specific (external to BlueZ).
 569                         Indicates if the transport support sending
 570                         ringtones, this property is only writeable when
 571                         the transport was acquired by the sender.
 572
 573                 string Routing [readonly]
 574
 575                         Optional and HFP specific (external to BlueZ).
 576                         Indicates where is the transport being routed.
 577
 578                         Possible Values: "HCI" or "PCM"
 579
 580                 uint16 Volume [readwrite]
 581
 582                         Optional. Indicates volume level of the transport,
 583                         this property is only writeable when the transport was
 584                         acquired by the sender.
 585
 586                         Note: the property will not be present for HSP/HFP
 587                         transports and MicrophoneGain/SpeakerGain should be
 588                         used instead.
 589
 590                         Possible Values: 0-127
 591
 592                 byte MicrophoneGain [readwrite]
 593
 594                         Optional. Indicates volume level of the transport's
 595                         incoming audio stream for HSP/HFP transports. This
 596                         property is only writeable when the transport was
 597                         acquired by the sender.
 598
 599                         Possible Values: 0-15
 600
 601                 byte SpeakerGain [readwrite]
 602
 603                         Optional. Indicates volume level of the transport's
 604                         outgoing audio stream for HSP/HFP transports. This
 605                         property is only writeable when the transport was
 606                         acquired by the sender.
 607
 608                         Possible Values: 0-15