[pulseaudio-discuss] RCF: Public API for managing nodes

[Tanu Kaskinen]

On Tue, 2013-07-16 at 14:01 +0200, David Henningsson wrote:
> On 07/13/2013 05:48 PM, Tanu Kaskinen wrote:
> > Hi all,
> >
> > I've written up a proposal for a public API for controlling routing with
> > nodes:
> > http://www.freedesktop.org/wiki/Software/PulseAudio/RFC/RoutingAPI/
> >
> > Comments would be very welcome.
> >
> > Also, if anyone wants to write a proof-of-concept GUI for exercising the
> > API, or extend pavucontrol, that would be awesome. I probably won't do
> > it.
> 
> I've tried to read it through and initially I'm trying to grasp the 
> concepts here.
> 
> A few points:
> 
>   * The docs say "since 5.0", are you really planning that, or given our 
> new schedule, should it rather be since 6.0?

Very likely 6.0, but let's see what we have when the freeze starts.

>   * I also wonder about the basic rules for edges/connections here. Can 
> we line them up:
>     - Edges are directed (stream flows from node A to node B)

Obviously audio flows from input to output. If this is what you meant,
then yes, they are directed.

There exists also some sort of "initiation ownership" of connections,
that is, a connection usually (but not necessarily always) originates
from a stream node (either input or output), and the device node is a
more passive participant in the relationship. This ownership is explicit
with the default connections (a node has "own" and "other" default
connections), but for explicit connections there is no such ownership
(or it's implied by the node type: if a stream is left without
connections, it needs to be "rescued", but there's no need to rescue a
sink when it's left without connections).

>     - A node can have more than one incoming edge (mixes input to single 
> output)

Yep.

>     - Can a node have more than one outgoing edge, and how is this then 
> handled for playback (clock deviation etc)? Automatic insert of combine 
> modules?

Yes, automatic use of the combine module is planned (the combining
functionality would move to the core, because what's the point of having
code in a module if the core directly depends on that code).

>     - And recording has the same thing but different, i e, spreading 
> data is not a problem but mixing requires clock synchronisation

Yes. I don't know what the solution will be (or whether we even need any
solution in the near future), but I guess this could be implemented
relatively easily with looping back the sources to a null sink and
recording from the null sink's monitor.

>     - Can there be more than one edge between the same nodes? E g, one 
> default connection and one explicit connection? Or how does this work?

Yes, there can be both an explicit and a default connection between two
nodes, or it can be also thought as being one connection that is both
explicit and default. I don't know what is a better way to think about
it, but perhaps it doesn't matter anyway.

>     - Can edges have properties, e g, a volume?

I don't know. Currently I'm not aware of a requirement to have
properties on the connections. My current thinking regarding volume
specifically is that we shouldn't attach volume to nodes: let's keep the
nodes for routing only.

>   * As for possible node operations, a move operation would be the same 
> as a "batched remove + add" operation. Maybe therefore the batch 
> solution would be better, i e, the client API inputs an array of node 
> operations?

I don't like the idea that if a client wants to move a stream, it has to
break the operation down to "remove + add", and then the server tries to
guess what the client really meant. Having a "move" operations keeps the
client intention obvious.

>   * The operations on changing the default connections does not make 
> sense to me. If the definition for default connections are those made 
> automatically by the routing system, if you change them then you broke 
> the definition...?

What operations do you mean? Moving or removing a default connection is
not supported as such, but if the client tries that anyway, we can
implicitly convert the connection to an explicit one and disable default
connections, or we can require the client to do these operations
explicitly, but I think the latter would be too inconvenient for the
client.

Adding a default connection is of course a totally impossible operation.

>   * Now, streams can be moved using either the new node API or the 
> existing stream/sink API. Will either cause consequences for the other, 
> e g changing node connections will cause an update event for the sink, 
> and changing stream/sink connection will cause update events for the 
> relevant nodes?

Yes, clients can do routing with either API, and changes done with one
API will cause events in the other API.

>   * And an bird's eye thought - I was thinking that these nodes were 
> something for policy/routing modules primarily. Is a client API the next 
> step here?

pactl support is very useful for testing and debugging while developing,
so I think it makes sense to have that before writing policy modules
that operate on nodes. (There's also the aspect that Janos wanted to
work on the policy module side. He's currently on vacation, though, but
this means that I will not work on any policy module before Janos has
some code ready.)

-- 
Tanu