doc/media-api.txt

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.

				byte Codec:

					Assigned number of codec that the
					endpoint implements. The values should
					match the profile specification which
					is indicated by the UUID.

				array{byte} Capabilities:

					Capabilities 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.


Media Control hierarchy
=======================

Service		org.bluez
Interface	org.bluez.MediaControl1 [Deprecated]
Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX

Methods		void Play()

			Resume playback.

		void Pause()

			Pause playback.

		void Stop()

			Stop playback.

		void Next()

			Next item.

		void Previous()

			Previous item.

		void VolumeUp()

			Adjust remote volume one step up

		void VolumeDown()

			Adjust remote volume one step down

		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

		boolean Connected [readonly]


MediaPlayer1 hierarchy
======================

Service		org.bluez (Controller role)
Interface	org.bluez.MediaPlayer1 [Experimental]
Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/playerX

Methods		void Play()

			Resume playback.

		void Pause()

			Pause playback.

		void Stop()

			Stop playback.

		void Next()

			Next item.

		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"

		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.

MediaEndpoint1 hierarchy
========================

Service		unique name
Interface	org.bluez.MediaEndpoint1
Object path	freely definable

Methods		void SetConfiguration(object transport, dict properties)

			Set configuration for the transport.

		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.

		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.


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.

		boolean NREC [readwrite]

			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 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 and HFP specific (external to BlueZ).
			Indicates where is the transport being routed.

			Possible Values: "HCI" or "PCM"

		uint16 Volume [readwrite]

			Optional. Indicates volume level of the transport,
			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