From: Luiz Augusto von Dentz <luiz.von.dentz@xxxxxxxxx>
This converts media-api.txt to media-api.rst.
---
Makefile.am | 2 +-
doc/media-api.rst | 1047 +++++++++++++++++++++++++++++++++++++++++++
doc/media-api.txt | 889 ------------------------------------
test/example-player | 2 +-
test/simple-player | 2 +-
5 files changed, 1050 insertions(+), 892 deletions(-)
create mode 100644 doc/media-api.rst
delete mode 100644 doc/media-api.txt
diff --git a/Makefile.am b/Makefile.am
index c28c59a05492..30db74a0c441 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -397,7 +397,7 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
EXTRA_DIST += doc/mgmt-api.txt \
doc/adapter-api.txt doc/device-api.txt \
doc/agent-api.txt doc/profile-api.txt \
- doc/network-api.txt doc/media-api.txt \
+ doc/network-api.txt doc/media-api.rst \
doc/health-api.txt doc/sap-api.txt \
doc/input-api.txt
diff --git a/doc/media-api.rst b/doc/media-api.rst
new file mode 100644
index 000000000000..34bf44e8ffbb
--- /dev/null
+++ b/doc/media-api.rst
@@ -0,0 +1,1047 @@
+===================================
+BlueZ D-Bus Media API documentation
+===================================
+
+
+Media interface
+===============
+
+:Service: org.bluez
+:Interface: org.bluez.Media1
+:Object path: [variable prefix]/{hci0,hci1,...}
+
+Methods
+-------
+
+void RegisterEndpoint(object endpoint, dict properties)
+```````````````````````````````````````````````````````
+
+ Register a local end point to sender, the sender can register as many
+ end points as it likes.
+
+ Note: If the sender disconnects the end points are automatically
+ unregistered.
+
+ possible properties:
+
+ :string UUID:
+
+ UUID of the profile which the endpoint is for.
+
+ UUID must be in the list of SupportedUUIDS.
+
+ :byte Codec:
+
+ Assigned number of codec that the endpoint implements. The
+ values should match the profile specification which is
+ indicated by the UUID.
+
+ :uint32_t Vendor [Optional]:
+
+ Vendor-specific Company ID, Codec ID tuple that the endpoint
+ implements.
+
+ It shall be set to appropriate value when Vendor Specific Codec
+ (0xff) is used.
+
+ :array{byte} Capabilities:
+
+ Capabilities blob, it is used as it is so the size and byte
+ order must match.
+
+ :array{byte} Metadata [Optional]:
+
+ Metadata blob, it is used as it is so the size and byte order
+ must match.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+
+ emitted when interface for the end-point is disabled
+
+void UnregisterEndpoint(object endpoint)
+````````````````````````````````````````
+ Unregister sender end point.
+
+void RegisterPlayer(object player, dict properties)
+```````````````````````````````````````````````````
+
+ Register a media player object to sender, the sender 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.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+
+void UnregisterPlayer(object player)
+````````````````````````````````````
+
+ Unregister sender media player.
+
+void RegisterApplication(object root, dict options)
+```````````````````````````````````````````````````
+
+ Register endpoints an player objects within root object which must
+ implement ObjectManager.
+
+ The application object path together with the D-Bus system bus
+ connection ID define the identification of the application.
+
+ Possible errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.AlreadyExists:
+
+void UnregisterApplication(object application)
+``````````````````````````````````````````````
+
+ This unregisters the services that has been previously registered. The
+ object path parameter must match the same value that has been used on
+ registration.
+
+ Possible errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.DoesNotExist:
+
+Properties
+----------
+
+array{string} SupportedUUIDs [readonly]
+```````````````````````````````````````
+
+ List of 128-bit UUIDs that represents the supported Endpoint
+ registration.
+
+MediaControl interface
+======================
+
+:Service: org.bluez
+:Interface: org.bluez.MediaControl1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Methods
+-------
+
+void Play() [Deprecated]
+````````````````````````
+
+ Resume playback.
+
+void Pause() [Deprecated]
+`````````````````````````
+
+ Pause playback.
+
+void Stop() [Deprecated]
+````````````````````````
+
+ Stop playback.
+
+void Next() [Deprecated]
+````````````````````````
+
+ Next item.
+
+void Previous() [Deprecated]
+````````````````````````````
+
+ Previous item.
+
+void VolumeUp() [Deprecated]
+````````````````````````````
+
+ Adjust remote volume one step up
+
+void VolumeDown() [Deprecated]
+``````````````````````````````
+
+ Adjust remote volume one step down
+
+void FastForward() [Deprecated]
+```````````````````````````````
+
+ Fast forward playback, this action is only stopped when another method
+ in this interface is called.
+
+void Rewind() [Deprecated]
+``````````````````````````
+
+ Rewind playback, this action is only stopped when another method in
+ this interface is called.
+
+Properties
+----------
+
+boolean Connected [readonly]
+````````````````````````````
+
+object Player [readonly, optional]
+``````````````````````````````````
+
+ Addressed Player object path.
+
+MediaPlayer interface
+=====================
+
+:Service: org.bluez (Controller role)
+:Interface: org.bluez.MediaPlayer1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX
+
+Methods
+-------
+
+void Play()
+```````````
+
+ Resume playback.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Pause()
+````````````
+
+ Pause playback.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Stop()
+```````````
+
+ Stop playback.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Next()
+```````````
+
+ Next item.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Previous()
+```````````````
+
+ Previous item.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void FastForward()
+``````````````````
+
+ Fast forward playback, this action is only stopped when another method
+ in this interface is called.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Rewind()
+`````````````
+
+ Rewind playback, this action is only stopped when another method in
+ this interface is called.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Press(byte avc_key)
+````````````````````````
+
+ Press a specific key to send as passthrough command. The key will be
+ released automatically. Use Hold() instead if the intention is to hold
+ down the key.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Hold(byte avc_key)
+```````````````````````
+
+ Press and hold a specific key to send as passthrough command. It is
+ your responsibility to make sure that Release() is called after calling
+ this method. The held key will also be released when any other method
+ in this interface is called.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void Release()
+``````````````
+
+ Release the previously held key invoked using Hold().
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+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"
+
+string Status [readonly]
+````````````````````````
+
+ 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.
+
+dict Track [readonly]
+`````````````````````
+
+ Track metadata.
+
+ Possible values:
+
+ :string Title:
+
+ Track title name
+
+ :string Artist:
+
+ Track artist name
+
+ :string Album:
+
+ Track album name
+
+ :string Genre:
+
+ Track genre name
+
+ :uint32 NumberOfTracks:
+
+ Number of tracks in total
+
+ :uint32 TrackNumber:
+
+ Track number
+
+ :uint32 Duration:
+
+ Track duration in milliseconds
+
+object Device [readonly]
+````````````````````````
+
+ Device object path.
+
+string Name [readonly]
+``````````````````````
+
+ Player name
+
+string Type [readonly]
+``````````````````````
+
+ Player type
+
+ Possible values:
+
+ "Audio"
+ "Video"
+ "Audio Broadcasting"
+ "Video Broadcasting"
+
+string Subtype [readonly]
+`````````````````````````
+
+ Player subtype
+
+ Possible values:
+
+ "Audio Book"
+ "Podcast"
+
+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.
+
+MediaFolder interface
+=====================
+
+:Service: unique name (Target role)
+ org.bluez (Controller role)
+:Interface: org.bluez.MediaFolder1
+: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.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+array{objects, properties} ListItems(dict filter)
+`````````````````````````````````````````````````
+
+ Return a list of items found
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+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.
+
+ Possible Errors:
+
+ :org.bluez.Error.InvalidArguments:
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+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
+
+MediaItem interface
+===================
+
+:Service: unique name (Target role)
+ org.bluez (Controller role)
+:Interface: org.bluez.MediaItem1
+: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
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+void AddtoNowPlaying()
+``````````````````````
+
+ Add item to now playing list
+
+ Possible Errors:
+
+ :org.bluez.Error.NotSupported:
+ :org.bluez.Error.Failed:
+
+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"
+
+MediaEndpoint interface
+=======================
+
+:Service: unique name (Server role)
+ org.bluez (Client role)
+:Interface: org.bluez.MediaEndpoint1
+:Object path: freely definable (Server role)
+ [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/sepX
+ (Client role)
+
+Methods
+-------
+
+void SetConfiguration(object transport, dict properties)
+````````````````````````````````````````````````````````
+
+ Set configuration for the transport.
+
+ For client role transport must be set with a server endpoint oject which
+ will be configured and the properties must contain the following
+ properties:
+
+ :array{byte} Capabilities [Mandatory]:
+ :array{byte} Metadata [ISO only]:
+ :byte CIG [ISO only]:
+ :byte CIS [ISO only]:
+ :uint32 Interval [ISO only]:
+ :bool Framing [ISO only]:
+ :string PHY [ISO only]:
+ :uint16 SDU [ISO only]:
+ :byte Retransmissions [ISO only]:
+ :uint16 Latency [ISO only]:
+ :uint32 Delay [ISO only]:
+ :uint8 TargetLatency [ISO Latency]:
+ :byte BIG [ISO broadcast only]:
+ :byte BIS [ISO broadcast only]:
+ :byte SyncInterval [ISO broadcast only]:
+ :byte Encryption [ISO broadcast only]:
+ :byte Options [ISO broadcast only]:
+ :uint16 Skip [ISO broadcast only]:
+ :uint16 SyncTimeout [ISO broadcast only]:
+ :byte SyncCteType [ISO broadcast only]:
+ :byte MSE [ISO broadcast only]:
+ :uint16 Timeout [ISO broadcast only]:
+ :array{byte} BroadcastCode [ISO broadcast only]:
+
+array{byte} SelectConfiguration(array{byte} capabilities)
+`````````````````````````````````````````````````````````
+
+ Select preferable configuration from the supported capabilities.
+
+ Returns a configuration which can be used to setup a transport.
+
+ Note: There is no need to cache the selected configuration since on
+ success the configuration is send back as parameter of SetConfiguration.
+
+dict SelectProperties(dict properties)
+``````````````````````````````````````
+
+ Select preferable properties from the supported properties:
+
+ :object Endpoint [ISO only]:
+ :Refer to SetConfiguration for the list of other possible properties.:
+
+ Returns propeties which can be used to setup a transport.
+
+ Note: There is no need to cache the selected properties since on
+ success the configuration is send back as parameter of SetConfiguration.
+
+void ClearConfiguration(object transport)
+`````````````````````````````````````````
+
+ Clear transport configuration.
+
+void Release()
+``````````````
+
+ This method gets called when the service daemon unregisters the
+ endpoint. An endpoint can use it to do cleanup tasks. There is no need
+ to unregister the endpoint, because when this method gets called it has
+ already been unregistered.
+
+Properties
+----------
+
+string UUID [readonly, optional]
+````````````````````````````````
+
+ UUID of the profile which the endpoint is for.
+
+byte Codec [readonly, optional]
+```````````````````````````````
+
+ Assigned number of codec that the endpoint implements.
+ The values should match the profile specification which is indicated by
+ the UUID.
+
+uint32_t Vendor [readonly, Optional]
+````````````````````````````````````
+
+ Vendor-specific Company ID, Codec ID tuple that the endpoint implements.
+
+ It shall be set to appropriate value when Vendor Specific Codec (0xff)
+ is used.
+
+array{byte} Capabilities [readonly, optional]
+`````````````````````````````````````````````
+
+ Capabilities blob, it is used as it is so the size and byte order must
+ match.
+
+array{byte} Metadata [readonly, Optional]
+`````````````````````````````````````````
+
+ Metadata blob, it is used as it is so the size and byte order must
+ match.
+
+object Device [readonly, optional]
+``````````````````````````````````
+
+ Device object which the endpoint is belongs to.
+
+bool DelayReporting [readonly, optional]
+````````````````````````````````````````
+
+ Indicates if endpoint supports Delay Reporting.
+
+byte Framing [ISO only]
+```````````````````````
+
+ Indicates endpoint support framing.
+
+byte PHY [ISO only]
+```````````````````
+
+ Indicates endpoint supported PHY.
+
+uint16_t MaximumLatency [ISO only]
+``````````````````````````````````
+
+ Indicates endpoint maximum latency.
+
+uint32_t MinimumDelay [ISO only]
+````````````````````````````````
+
+ Indicates endpoint minimum presentation delay.
+
+uint32_t MaximumDelay [ISO only]
+````````````````````````````````
+
+ Indicates endpoint maximum presentation delay.
+
+uint32_t PreferredMinimumDelay [ISO only]
+`````````````````````````````````````````
+
+ Indicates endpoint preferred minimum presentation delay.
+
+uint32_t PreferredMinimumDelay [ISO only]
+`````````````````````````````````````````
+
+ Indicates endpoint preferred minimum presentation delay.
+
+uint32 Location [ISO only]
+``````````````````````````
+
+ Indicates endpoint supported locations.
+
+uint16 SupportedContext [ISO only]
+``````````````````````````````````
+
+ Indicates endpoint supported audio context.
+
+uint16 Context [ISO only]
+`````````````````````````
+
+ Indicates endpoint available audio context.
+
+MediaTransport interface
+========================
+
+:Service: org.bluez
+:Interface: org.bluez.MediaTransport1
+:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/fdX
+
+Methods
+-------
+
+fd, uint16, uint16 Acquire()
+````````````````````````````
+
+ Acquire transport file descriptor and the MTU for read and write
+ respectively.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotAuthorized:
+ :org.bluez.Error.Failed:
+
+fd, uint16, uint16 TryAcquire()
+```````````````````````````````
+
+ 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.
+
+ Possible Errors:
+
+ :org.bluez.Error.NotAuthorized:
+ :org.bluez.Error.Failed:
+ :org.bluez.Error.NotAvailable:
+
+void Release()
+``````````````
+
+ Releases file descriptor.
+
+Properties
+----------
+
+object Device [readonly]
+````````````````````````
+
+ Device object which the transport is connected to.
+
+string UUID [readonly]
+``````````````````````
+
+ UUID of the profile which the transport is for.
+
+byte Codec [readonly]
+`````````````````````
+
+ Assigned number of codec that the transport support.
+ The values should match the profile specification which is indicated by
+ the UUID.
+
+array{byte} Configuration [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 property is only writeable
+ when the transport was acquired by the sender.
+
+uint16 Volume [readwrite, optional]
+```````````````````````````````````
+
+ Indicates volume level of the transport, this property is only writeable
+ when the transport was acquired by the sender.
+
+ Possible Values: 0-127
+
+object Endpoint [readonly, optional, experimental]
+``````````````````````````````````````````````````
+
+ Endpoint object which the transport is associated with.
+
+uint32 Location [readonly, ISO only, experimental]
+``````````````````````````````````````````````````
+
+ Indicates transport Audio Location.
+
+array{byte} Metadata [readwrite, ISO Only, experimental]
+````````````````````````````````````````````````````````
+
+ Indicates transport Metadata.
+
+array{object} Links [readonly, optional, ISO only, experimental]
+````````````````````````````````````````````````````````````````
+
+ Linked transport objects which the transport is associated with.
+
+dict QoS [readonly, optional, ISO only, experimental]
+`````````````````````````````````````````````````````
+
+ Only present when QoS is configured.
+
+ Possible values for Unicast:
+
+ :byte CIG:
+
+ Indicates configured CIG.
+
+ :byte CIS:
+
+ Indicates configured CIS.
+
+ :uint32 Interval:
+
+ Indicates configured ISO interval.
+
+ :boolean Framing:
+
+ Indicates configured framing.
+
+ :byte PHY:
+
+ Indicates configured PHY.
+
+ :uint16 SDU:
+
+ Indicates configured SDU.
+
+ :byte Retransmissions:
+
+ Indicates configured retransmissions.
+
+ :uint16 Latency:
+
+ Indicates configured transport latency.
+
+ Possible values for Broadcast:
+
+ :byte BIG:
+
+ Indicates configured QoS BIG.
+
+ :byte BIS:
+
+ Indicates configured BIS.
+
+ :uint32 SyncFactor:
+
+ Indicates configured sync factor.
+
+ :uint32 Interval:
+
+ Indicates configured ISO interval.
+
+ :byte PHY:
+
+ Indicates configured PHY.
+
+ :uint16 SDU:
+
+ Indicates configured maximum SDU.
+
+ :byte SyncTimeout:
+
+ Indicates configured broadcast sync timeout.
+
+ :uint16 Latency:
+
+ Indicates configured transport latency.
diff --git a/doc/media-api.txt b/doc/media-api.txt
deleted file mode 100644
index cbcfac85c27b..000000000000
--- a/doc/media-api.txt
+++ /dev/null
@@ -1,889 +0,0 @@
-BlueZ D-Bus Media API description
-*********************************
-
-
-Media hierarchy
-===============
-
-Service org.bluez
-Interface org.bluez.Media1
-Object path [variable prefix]/{hci0,hci1,...}
-
-Methods void RegisterEndpoint(object endpoint, dict properties)
-
- Register a local end point to sender, the sender can
- register as many end points as it likes.
-
- Note: If the sender disconnects the end points are
- automatically unregistered.
-
- possible properties:
-
- string UUID:
-
- UUID of the profile which the endpoint
- is for.
-
- UUID must be in the list of
- SupportedUUIDS.
-
- byte Codec:
-
- Assigned number of codec that the
- endpoint implements. The values should
- match the profile specification which
- is indicated by the UUID.
-
- uint32_t Vendor [Optional]:
-
- Vendor-specific Company ID, Codec ID
- tuple that the endpoint implements.
-
- It shall be set to appropriate value
- when Vendor Specific Codec (0xff)
- is used.
-
- array{byte} Capabilities:
-
- Capabilities blob, it is used as it is
- so the size and byte order must match.
-
- array{byte} Metadata [Optional]:
-
- Metadata blob, it is used as it is
- so the size and byte order must match.
-
- Possible Errors: org.bluez.Error.InvalidArguments
- org.bluez.Error.NotSupported - emitted
- when interface for the end-point is
- disabled.
-
- void UnregisterEndpoint(object endpoint)
-
- Unregister sender end point.
-
- void RegisterPlayer(object player, dict properties)
-
- Register a media player object to sender, the sender
- 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.
-
- Possible Errors: org.bluez.Error.InvalidArguments
- org.bluez.Error.NotSupported
-
- void UnregisterPlayer(object player)
-
- Unregister sender media player.
-
- void RegisterApplication(object root, dict options)
-
- Register endpoints an player objects within root
- object which must implement ObjectManager.
-
- The application object path together with the D-Bus
- system bus connection ID define the identification of
- the application.
-
- Possible errors: org.bluez.Error.InvalidArguments
- org.bluez.Error.AlreadyExists
-
- void UnregisterApplication(object application)
-
- This unregisters the services that has been
- previously registered. The object path parameter
- must match the same value that has been used
- on registration.
-
- Possible errors: org.bluez.Error.InvalidArguments
- org.bluez.Error.DoesNotExist
-
-Properties array{string} SupportedUUIDs [readonly]:
-
- List of 128-bit UUIDs that represents the supported
- Endpoint registration.
-
-Media Control hierarchy
-=======================
-
-Service org.bluez
-Interface org.bluez.MediaControl1
-Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
-
-Methods void Play() [Deprecated]
-
- Resume playback.
-
- void Pause() [Deprecated]
-
- Pause playback.
-
- void Stop() [Deprecated]
-
- Stop playback.
-
- void Next() [Deprecated]
-
- Next item.
-
- void Previous() [Deprecated]
-
- Previous item.
-
- void VolumeUp() [Deprecated]
-
- Adjust remote volume one step up
-
- void VolumeDown() [Deprecated]
-
- Adjust remote volume one step down
-
- void FastForward() [Deprecated]
-
- Fast forward playback, this action is only stopped
- when another method in this interface is called.
-
- void Rewind() [Deprecated]
-
- Rewind playback, this action is only stopped
- when another method in this interface is called.
-
-Properties
-
- boolean Connected [readonly]
-
- object Player [readonly, optional]
-
- Addressed Player object path.
-
-
-MediaPlayer1 hierarchy
-======================
-
-Service org.bluez (Controller role)
-Interface org.bluez.MediaPlayer1
-Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX
-
-Methods void Play()
-
- Resume playback.
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void Pause()
-
- Pause playback.
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void Stop()
-
- Stop playback.
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void Next()
-
- Next item.
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void Previous()
-
- Previous item.
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void FastForward()
-
- Fast forward playback, this action is only stopped
- when another method in this interface is called.
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void Rewind()
-
- Rewind playback, this action is only stopped
- when another method in this interface is called.
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void Press(byte avc_key)
-
- Press a specific key to send as passthrough command.
- The key will be released automatically. Use Hold()
- instead if the intention is to hold down the key.
-
- Possible Errors: org.bluez.Error.InvalidArguments
- org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void Hold(byte avc_key)
-
- Press and hold a specific key to send as passthrough
- command. It is your responsibility to make sure that
- Release() is called after calling this method. The held
- key will also be released when any other method in this
- interface is called.
-
- Possible Errors: org.bluez.Error.InvalidArguments
- org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void Release()
-
- Release the previously held key invoked using Hold().
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
-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"
-
- string Status [readonly]
-
- 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.
-
- dict Track [readonly]
-
- Track metadata.
-
- Possible values:
-
- string Title:
-
- Track title name
-
- string Artist:
-
- Track artist name
-
- string Album:
-
- Track album name
-
- string Genre:
-
- Track genre name
-
- uint32 NumberOfTracks:
-
- Number of tracks in total
-
- uint32 TrackNumber:
-
- Track number
-
- uint32 Duration:
-
- Track duration in milliseconds
-
- object Device [readonly]
-
- Device object path.
-
- string Name [readonly]
-
- Player name
-
- string Type [readonly]
-
- Player type
-
- Possible values:
-
- "Audio"
- "Video"
- "Audio Broadcasting"
- "Video Broadcasting"
-
- string Subtype [readonly]
-
- Player subtype
-
- Possible values:
-
- "Audio Book"
- "Podcast"
-
- 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
-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.
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- array{objects, properties} ListItems(dict filter)
-
- Return a list of items found
-
- Possible Errors: org.bluez.Error.InvalidArguments
- org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- 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.
-
- Possible Errors: org.bluez.Error.InvalidArguments
- org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
-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
-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
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
- void AddtoNowPlaying()
-
- Add item to now playing list
-
- Possible Errors: org.bluez.Error.NotSupported
- org.bluez.Error.Failed
-
-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 (Server role)
- org.bluez (Client role)
-Interface org.bluez.MediaEndpoint1
-Object path freely definable (Server role)
- [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/sepX
- (Client role)
-
-Methods void SetConfiguration(object transport, dict properties)
-
- Set configuration for the transport.
-
- For client role transport must be set with a server
- endpoint oject which will be configured and the
- properties must contain the following properties:
-
- array{byte} Capabilities [Mandatory]
- array{byte} Metadata [ISO only]
- byte CIG [ISO only]
- byte CIS [ISO only]
- uint32 Interval [ISO only]
- bool Framing [ISO only]
- string PHY [ISO only]
- uint16 SDU [ISO only]
- byte Retransmissions [ISO only]
- uint16 Latency [ISO only]
- uint32 Delay [ISO only]
- uint8 TargetLatency [ISO Latency]
- byte BIG [ISO broadcast only]
- byte BIS [ISO broadcast only]
- byte SyncInterval [ISO broadcast only]
- byte Encryption [ISO broadcast only]
- byte Options [ISO broadcast only]
- uint16 Skip [ISO broadcast only]
- uint16 SyncTimeout [ISO broadcast only]
- byte SyncCteType [ISO broadcast only]
- byte MSE [ISO broadcast only]
- uint16 Timeout [ISO broadcast only]
- array{byte} BroadcastCode [ISO broadcast only]
-
- array{byte} SelectConfiguration(array{byte} capabilities)
-
- Select preferable configuration from the supported
- capabilities.
-
- Returns a configuration which can be used to setup
- a transport.
-
- Note: There is no need to cache the selected
- configuration since on success the configuration is
- send back as parameter of SetConfiguration.
-
- dict SelectProperties(dict properties)
-
- Select preferable properties from the supported
- properties:
- object Endpoint [ISO only]
- Refer to SetConfiguration for the list of
- other possible properties.
-
- Returns propeties which can be used to setup
- a transport.
-
- Note: There is no need to cache the selected
- properties since on success the configuration is
- send back as parameter of SetConfiguration.
-
- void ClearConfiguration(object transport)
-
- Clear transport configuration.
-
- void Release()
-
- This method gets called when the service daemon
- unregisters the endpoint. An endpoint can use it to do
- cleanup tasks. There is no need to unregister the
- endpoint, because when this method gets called it has
- already been unregistered.
-
-Properties string UUID [readonly, optional]:
-
- UUID of the profile which the endpoint is for.
-
- byte Codec [readonly, optional]:
-
- Assigned number of codec that the endpoint implements.
- The values should match the profile specification which
- is indicated by the UUID.
-
- uint32_t Vendor [readonly, Optional]:
-
- Vendor-specific Company ID, Codec ID tuple that the
- endpoint implements.
-
- It shall be set to appropriate value when Vendor
- Specific Codec (0xff) is used.
-
- array{byte} Capabilities [readonly, optional]:
-
- Capabilities blob, it is used as it is so the size and
- byte order must match.
-
- array{byte} Metadata [readonly, Optional]:
-
- Metadata blob, it is used as it is so the size and
- byte order must match.
-
- object Device [readonly, optional]:
-
- Device object which the endpoint is belongs to.
-
- bool DelayReporting [readonly, optional]:
-
- Indicates if endpoint supports Delay Reporting.
-
- byte Framing [ISO only]
-
- Indicates endpoint support framing.
-
- byte PHY [ISO only]
-
- Indicates endpoint supported PHY.
-
- uint16_t MaximumLatency [ISO only]
-
- Indicates endpoint maximum latency.
-
- uint32_t MinimumDelay [ISO only]
-
- Indicates endpoint minimum presentation delay.
-
- uint32_t MaximumDelay [ISO only]
-
- Indicates endpoint maximum presentation delay.
-
- uint32_t PreferredMinimumDelay [ISO only]
-
- Indicates endpoint preferred minimum presentation delay.
-
- uint32_t PreferredMinimumDelay [ISO only]
-
- Indicates endpoint preferred minimum presentation delay.
-
- uint32 Location [ISO only]
-
- Indicates endpoint supported locations.
-
- uint16 SupportedContext [ISO only]
-
- Indicates endpoint supported audio context.
-
- uint16 Context [ISO only]
-
- Indicates endpoint available audio context.
-
-MediaTransport1 hierarchy
-=========================
-
-Service org.bluez
-Interface org.bluez.MediaTransport1
-Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/fdX
-
-Methods fd, uint16, uint16 Acquire()
-
- Acquire transport file descriptor and the MTU for read
- and write respectively.
-
- Possible Errors: org.bluez.Error.NotAuthorized
- org.bluez.Error.Failed
-
- fd, uint16, uint16 TryAcquire()
-
- 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.
-
- Possible Errors: org.bluez.Error.NotAuthorized
- org.bluez.Error.Failed
- org.bluez.Error.NotAvailable
-
- void Release()
-
- Releases file descriptor.
-
-Properties object Device [readonly]
-
- Device object which the transport is connected to.
-
- string UUID [readonly]
-
- UUID of the profile which the transport is for.
-
- byte Codec [readonly]
-
- Assigned number of codec that the transport support.
- The values should match the profile specification which
- is indicated by the UUID.
-
- array{byte} Configuration [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
- property is only writeable when the transport was
- acquired by the sender.
-
- uint16 Volume [readwrite]
-
- Optional. Indicates volume level of the transport,
- this property is only writeable when the transport was
- acquired by the sender.
-
- Possible Values: 0-127
-
- object Endpoint [readonly, optional, experimental]
-
- Endpoint object which the transport is associated
- with.
-
- uint32 Location [readonly, ISO only, experimental]
-
- Indicates transport Audio Location.
-
- array{byte} Metadata [ISO Only, experimental]
-
- Indicates transport Metadata.
-
- array{object} Links [readonly, optional, ISO only, experimental]
-
- Linked transport objects which the transport is
- associated with.
-
- dict QoS [readonly, optional, ISO only, experimental]
-
- Only present when QoS is configured.
-
- Possible values for Unicast:
-
- byte CIG
-
- Indicates configured CIG.
-
- byte CIS
-
- Indicates configured CIS.
-
- uint32 Interval
-
- Indicates configured ISO interval.
-
- boolean Framing
-
- Indicates configured framing.
-
- byte PHY
-
- Indicates configured PHY.
-
- uint16 SDU
-
- Indicates configured SDU.
-
- byte Retransmissions
-
- Indicates configured retransmissions.
-
- uint16 Latency
-
- Indicates configured transport latency.
-
- Possible values for Broadcast:
-
- byte BIG
-
- Indicates configured QoS BIG.
-
- byte BIS
-
- Indicates configured BIS.
-
- uint32 SyncInterval
-
- Indicates configured broadcast sync interval.
-
- uint32 Interval
-
- Indicates configured ISO interval.
-
- byte PHY
-
- Indicates configured PHY.
-
- uint16 SDU
-
- Indicates configured maximum SDU.
-
- byte SyncTimeout
-
- Indicates configured broadcast sync timeout.
-
- uint16 Latency
-
- Indicates configured transport latency.
diff --git a/test/example-player b/test/example-player
index 1497d1107a16..167460badcff 100644
--- a/test/example-player
+++ b/test/example-player
@@ -96,7 +96,7 @@ class Player(dbus.service.Object):
"""PropertiesChanged(interface, properties, invalidated)
Send a PropertiesChanged signal. 'properties' is a dictionary
- containing string parameters as specified in doc/media-api.txt.
+ containing string parameters as specified in doc/media-api.rst.
"""
pass
diff --git a/test/simple-player b/test/simple-player
index 92682844d0f4..7bad3d14f848 100755
--- a/test/simple-player
+++ b/test/simple-player
@@ -78,7 +78,7 @@ class Player(dbus.service.Object):
"""PropertiesChanged(interface, properties, invalidated)
Send a PropertiesChanged signal. 'properties' is a dictionary
- containing string parameters as specified in doc/media-api.txt.
+ containing string parameters as specified in doc/media-api.rst.
"""
pass
--
2.41.0
