diff options
Diffstat (limited to 'doc/media-api.txt')
| -rw-r--r-- | doc/media-api.txt | 511 |
1 files changed, 384 insertions, 127 deletions
diff --git a/doc/media-api.txt b/doc/media-api.txt index 44464390..05f90e38 100644 --- a/doc/media-api.txt +++ b/doc/media-api.txt @@ -1,11 +1,12 @@ BlueZ D-Bus Media API description ********************************* + Media hierarchy =============== Service org.bluez -Interface org.bluez.Media +Interface org.bluez.Media1 Object path [variable prefix]/{hci0,hci1,...} Methods void RegisterEndpoint(object endpoint, dict properties) @@ -44,119 +45,152 @@ Methods void RegisterEndpoint(object endpoint, dict properties) Unregister sender end point. - void RegisterPlayer(object player, dict properties, - dict metadata) + void RegisterPlayer(object player, dict properties) Register a media player object to sender, the sender - can register as many objets as it likes. + can register as many objects as it likes. + + Object must implement at least + org.mpris.MediaPlayer2.Player as defined in MPRIS 2.2 + spec: + + http://specifications.freedesktop.org/mpris-spec/latest/ Note: If the sender disconnects its objects are automatically unregistered. - Properties: + Possible Errors: org.bluez.Error.InvalidArguments + org.bluez.Error.NotSupported - string Equalizer: + void UnregisterPlayer(object player) - Possible values: "off" or "on" + Unregister sender media player. - string Repeat: - Possible values: "off", "singletrack", - "alltracks" or "group" +Media Control hierarchy +======================= - string Shuffle: +Service org.bluez +Interface org.bluez.MediaControl1 [Deprecated] +Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - Possible values: "off", "alltracks" or - "group" +Methods void Play() - string Scan: + Resume playback. - Possible values: "off", "alltracks" or - "group" + void Pause() - string Status: + Pause playback. - Possible values: "playing", "stopped", - "paused", - "forward-seek", - "reverse-seek" or - "error" + void Stop() - uint32 Position + Stop playback. - Playback position in milliseconds + void Next() - Metadata: + Next item. - string Title: + void Previous() - Track title name + Previous item. - string Artist: + void VolumeUp() - Track artist name + Adjust remote volume one step up - string Album: + void VolumeDown() - Track album name + Adjust remote volume one step down - string Genre: + void FastForward() - Track genre name + Fast forward playback, this action is only stopped + when another method in this interface is called. - uint32 NumberOfTracks: + void Rewind() - Number of tracks in total + Rewind playback, this action is only stopped + when another method in this interface is called. - uint32 Number: +Properties - Track number + boolean Connected [readonly] - uint32 Duration: - Track duration in milliseconds +MediaPlayer1 hierarchy +====================== - Possible Errors: org.bluez.Error.InvalidArguments - org.bluez.Error.NotSupported +Service org.bluez (Controller role) +Interface org.bluez.MediaPlayer1 [Experimental] +Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX - void UnregisterPlayer(object player) +Methods void Play() - Unregister sender media player. + Resume playback. -MediaPlayer hierarchy -===================== + void Pause() -Service unique name -Interface org.bluez.MediaPlayer -Object path freely definable + Pause playback. -Methods void SetProperty(string property, variant value) + void Stop() - Changes the value of the specified property. Only - properties that are listed as read-write can be changed. + Stop playback. - On success this will emit a PropertyChanged signal. + void Next() - void Release() + Next item. - This method gets called when the service daemon - unregisters the player which can then perform - cleanup tasks. There is no need to unregister the - player, because when this method gets called it has - already been unregistered. + void Previous() + + Previous item. + + void FastForward() + + Fast forward playback, this action is only stopped + when another method in this interface is called. + + void Rewind() + + Rewind playback, this action is only stopped + when another method in this interface is called. + +Properties string Equalizer [readwrite] + + Possible values: "off" or "on" + + string Repeat [readwrite] + + Possible values: "off", "singletrack", "alltracks" or + "group" + + string Shuffle [readwrite] + + Possible values: "off", "alltracks" or "group" + + string Scan [readwrite] + + Possible values: "off", "alltracks" or "group" -Signals PropertyChanged(string setting, variant value) + string Status [readonly] - This signal indicates a changed value of the given - property. + Possible status: "playing", "stopped", "paused", + "forward-seek", "reverse-seek" + or "error" + + uint32 Position [readonly] + + Playback position in milliseconds. Changing the + position may generate additional events that will be + sent to the remote device. When position is 0 it means + the track is starting and when it's greater than or + equal to track's duration the track has ended. Note + that even if duration is not available in metadata it's + possible to signal its end by setting position to the + maximum uint32 value. - TrackChanged(dict metadata) + dict Track [readonly] - This signal indicates that current track has changed. - All available metadata for the new track shall be set - at once in the metadata argument. Metadata cannot be - updated in parts, otherwise it will be interpreted as - multiple track changes. + Track metadata. Possible values: @@ -180,7 +214,7 @@ Signals PropertyChanged(string setting, variant value) Number of tracks in total - uint32 Number: + uint32 TrackNumber: Track number @@ -188,45 +222,244 @@ Signals PropertyChanged(string setting, variant value) Track duration in milliseconds -Properties string Equalizer [readwrite] + object Device [readonly] - Possible values: "off" or "on" + Device object path. - string Repeat [readwrite] + string Name [readonly] - Possible values: "off", "singletrack", "alltracks" or - "group" + Player name - string Shuffle [readwrite] + string Type [readonly] - Possible values: "off", "alltracks" or "group" + Player type - string Scan [readwrite] + Possible values: - Possible values: "off", "alltracks" or "group" + "Audio" + "Video" + "Audio Broadcasting" + "Video Broadcasting" - string Status [readonly] + string Subtype [readonly] - Possible status: "playing", "stopped", "paused", - "forward-seek", "reverse-seek" or - "error" + Player subtype - uint32 Position [readonly] + Possible values: - Playback position in milliseconds. Changing the - position may generate additional events that will be - sent to the remote device. When position is 0 it means - the track is starting and when it's greater than or - equal to track's duration the track has ended. Note - that even if duration is not available in metadata it's - possible to signal its end by setting position to the - maximum uint32 value. + "Audio Book" + "Podcast" -MediaEndpoint hierarchy -======================= + boolean Browsable [readonly] + + If present indicates the player can be browsed using + MediaFolder interface. + + Possible values: + + True: Supported and active + False: Supported but inactive + + Note: If supported but inactive clients can enable it + by using MediaFolder interface but it might interfere + in the playback of other players. + + + boolean Searchable [readonly] + + If present indicates the player can be searched using + MediaFolder interface. + + Possible values: + + True: Supported and active + False: Supported but inactive + + Note: If supported but inactive clients can enable it + by using MediaFolder interface but it might interfere + in the playback of other players. + + object Playlist + + Playlist object path. + +MediaFolder1 hierarchy +====================== + +Service unique name (Target role) + org.bluez (Controller role) +Interface org.bluez.MediaFolder1 [Experimental] +Object path freely definable (Target role) + [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX + (Controller role) + +Methods object Search(string value, dict filter) + + Return a folder object containing the search result. + + To list the items found use the folder object returned + and pass to ChangeFolder. + + array{objects, properties} ListItems(dict filter) + + Return a list of items found + + void ChangeFolder(object folder) + + Change current folder. + + Note: By changing folder the items of previous folder + might be destroyed and have to be listed again, the + exception is NowPlaying folder which should be always + present while the player is active. + +Properties uint32 NumberOfItems [readonly] + + Number of items in the folder + + string Name [readonly] + + Folder name: + + Possible values: + "/Filesystem/...": Filesystem scope + "/NowPlaying/...": NowPlaying scope + + Note: /NowPlaying folder might not be listed if player + is stopped, folders created by Search are virtual so + once another Search is perform or the folder is + changed using ChangeFolder it will no longer be listed. + +Filters uint32 Start: + + Offset of the first item. + + Default value: 0 + + uint32 End: + + Offset of the last item. + + Default value: NumbeOfItems + + array{string} Attributes + + Item properties that should be included in the list. + + Possible Values: + + "title", "artist", "album", "genre", + "number-of-tracks", "number", "duration" + + Default Value: All + +MediaItem1 hierarchy +==================== + +Service unique name (Target role) + org.bluez (Controller role) +Interface org.bluez.MediaItem1 [Experimental] +Object path freely definable (Target role) + [variable + prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX/itemX + (Controller role) + +Methods void Play() + + Play item + + void AddtoNowPlaying() + + Add item to now playing list + +Properties object Player [readonly] + + Player object path the item belongs to + + string Name [readonly] + + Item displayable name + + string Type [readonly] + + Item type + + Possible values: "video", "audio", "folder" + + string FolderType [readonly, optional] + + Folder type. + + Possible values: "mixed", "titles", "albums", "artists" + + Available if property Type is "Folder" + + boolean Playable [readonly, optional] + + Indicates if the item can be played + + Available if property Type is "folder" + + dict Metadata [readonly] + + Item metadata. + + Possible values: + + string Title + + Item title name + + Available if property Type is "audio" + or "video" + + string Artist + + Item artist name + + Available if property Type is "audio" + or "video" + + string Album + + Item album name + + Available if property Type is "audio" + or "video" + + string Genre + + Item genre name + + Available if property Type is "audio" + or "video" + + uint32 NumberOfTracks + + Item album number of tracks in total + + Available if property Type is "audio" + or "video" + + uint32 Number + + Item album number + + Available if property Type is "audio" + or "video" + + uint32 Duration + + Item duration in milliseconds + + Available if property Type is "audio" + or "video" + +MediaEndpoint1 hierarchy +======================== Service unique name -Interface org.bluez.MediaEndpoint +Interface org.bluez.MediaEndpoint1 Object path freely definable Methods void SetConfiguration(object transport, dict properties) @@ -257,47 +490,38 @@ Methods void SetConfiguration(object transport, dict properties) endpoint, because when this method gets called it has already been unregistered. -MediaTransport hierarchy -======================== + +MediaTransport1 hierarchy +========================= Service org.bluez -Interface org.bluez.MediaTransport +Interface org.bluez.MediaTransport1 Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/fdX -Methods dict GetProperties() - - Returns all properties for the interface. See the - properties section for available properties. - - fd, uint16, uint16 Acquire(string accesstype) +Methods fd, uint16, uint16 Acquire() Acquire transport file descriptor and the MTU for read and write respectively. - possible accesstype: + Possible Errors: org.bluez.Error.NotAuthorized + org.bluez.Error.Failed - "r" : Read only access + fd, uint16, uint16 TryAcquire() - "w" : Write only access + Acquire transport file descriptor only if the transport + is in "pending" state at the time the message is + received by BlueZ. Otherwise no request will be sent + to the remote device and the function will just fail + with org.bluez.Error.NotAvailable. - "rw": Read and write access + Possible Errors: org.bluez.Error.NotAuthorized + org.bluez.Error.Failed + org.bluez.Error.NotAvailable - void Release(string accesstype) + void Release() Releases file descriptor. - void SetProperty(string name, variant value) - - Changes the value of the specified property. Only - properties that are listed a read-write can be changed. - - On success this will emit a PropertyChanged signal. - -Signals void PropertyChanged(string name, variant value) - - This signal indicates a changed value of the given - property. - Properties object Device [readonly] Device object which the transport is connected to. @@ -317,6 +541,14 @@ Properties object Device [readonly] Configuration blob, it is used as it is so the size and byte order must match. + string State [readonly] + + Indicates the state of the transport. Possible + values are: + "idle": not streaming + "pending": streaming but not acquired + "active": streaming and acquired + uint16 Delay [readwrite] Optional. Transport delay in 1/10 of millisecond, this @@ -325,20 +557,23 @@ Properties object Device [readonly] boolean NREC [readwrite] - Optional. Indicates if echo cancelling and noise - reduction functions are active in the transport, this - property is only writeable when the transport was - acquired by the sender. + Optional and HFP specific (external to BlueZ). + Indicates if echo cancelling and noise reduction + functions are active in the transport, this + property is only writeable when the transport + was acquired by the sender. boolean InbandRingtone [readwrite] - Optional. Indicates if the transport support sending - ringtones, this property is only writeable when the - transport was acquired by the sender. + Optional and HFP specific (external to BlueZ). + Indicates if the transport support sending + ringtones, this property is only writeable when + the transport was acquired by the sender. string Routing [readonly] - Optional. Indicates where is the transport being routed + Optional and HFP specific (external to BlueZ). + Indicates where is the transport being routed. Possible Values: "HCI" or "PCM" @@ -348,4 +583,26 @@ Properties object Device [readonly] this property is only writeable when the transport was acquired by the sender. + Note: the property will not be present for HSP/HFP + transports and MicrophoneGain/SpeakerGain should be + used instead. + Possible Values: 0-127 + + byte MicrophoneGain [readwrite] + + Optional. Indicates volume level of the transport's + incoming audio stream for HSP/HFP transports. This + property is only writeable when the transport was + acquired by the sender. + + Possible Values: 0-15 + + byte SpeakerGain [readwrite] + + Optional. Indicates volume level of the transport's + outgoing audio stream for HSP/HFP transports. This + property is only writeable when the transport was + acquired by the sender. + + Possible Values: 0-15 |