Make properties Device, Volume and IsMuted writable in the stream restore entry interface.

Add GetEntryByName method to the stream restore interface.

2009-07-31

Change the non-extension object path prefix from /org/pulseaudio1/ to /org/pulseaudio/core1/. This way the core and the extensions have consistent object path prefix (/org/pulseaudio/).

Add signals .Core1.NewExtension and .Core1.ExtensionRemoved.

Rework the stream restore interface.

2009-07-15

Remove the sink argument from Sample.Play() and add new method Sample.PlayToSink().

2009-07-12

Add Cards property to Core.

2009-07-09

Rearrange the channel position enumeration so that the numbering matches the one used internally and with the C API.

2009-07-01

Change the org.pulseaudio prefix to org.PulseAudio.

Replace the lookup service's GetAddress method with the Address property.

Remove sample loading methods that use files. Hide the difference between lazy and non-lazy samples.

Add Sinks and Sources properties to Card.

Prefix boolean properties with "Is" or "Has".

Move FlatVolume property from Sink to Device.

Change enumeration types from Byte to Uint32.

Remove the Self interface, move the functionality to Core and Client interfaces.

Move everything in the PlaybackStream interface to the Stream interface and remove PlaybackStream.

Add StreamEvent to the Stream interface.

Rename proplist -> property list.

Change argument names to lowercase, as it seems to be the standard way (this statement is actually only based on that the D-Bus spec has them lowercase in the examples).

Overview

Previously the only D-Bus services PulseAudio provided were an implementation of the Device Reservation spec for sound cards and reservation of the org.pulseaudio.Server name on the session or system bus for server tracking purposes. Those features remain untouched, and this document doesn't have anything to do with them.

The new functionality consists of two parts: a server lookup service and the main control interface. When clients want to use the control interface, they have to first figure out where they should connect to. How to connect to the control interface is specified on the ConnectingToServer page. The main control interface is provided as a "D-Bus server". That is, it's not available on any bus, but instead clients make direct connections to PulseAudio.

Requiring clients to use peer-to-peer connections instead of the traditional system/session bus has turned out to cause lots of trouble and confusion. It was perhaps a bad decision, but initially it seemed like a good idea:

It's not possible to connect to a session bus remotely. The chosen approach allows remote connections, without any special handling needed in the applications.

PulseAudio is a user daemon, not a session daemon, so the session bus is not a good match. This point is undermined by the fact that the discovery service is on the session bus - any problems related to the user/session mismatch affect also the discovery service.

Open Questions

Does it make sense for clients to save card names? If not, the .Core1.GetCardByName method is probably unneeded.

Same for .Core1.Card.GetProfileByName.

Same for .Core1.Device.GetPortByName.

Do error cases need better documentation? The current guideline has been that if an error can be returned even if the situation is more like a special case than an error, it is explicitly documented.

Control API

The detailed descriptions are spread to separate pages, roughly one per object type. This page provides only a minimal reference and links to the details.

Notation

Arrays are written as []. For example, [Byte] is an array of bytes.

Dictionaries are written as { -> }. For example, {String -> [Byte]} is a dictionary with strings as keys and byte arrays as values.

Structs are written as (, , ..., ). For example (Byte, Uint32) is a struct with two members: a byte and an unsigned 32 bit integer.

On this page only, property access is denoted with (r) for read and with (rw) for read/write.

The rest should be obvious.

Property Lists

Property lists (not to be confused with D-Bus properties) are dictionaries that are associated with many objects. The keys are utf-8 strings and the values are arbitrary data (usually they are utf-8 strings too, though). Property lists are used to attach many kinds of metadata to the objects: names, descriptions, intended roles and so on. For now the best source of information about available properties is the proplist.h file documentation.