[pulseaudio-tickets] [Bug 39403] New: The D-Bus interface's sample playing methods have a bad volume API

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=39403

           Summary: The D-Bus interface's sample playing methods have a
                    bad volume API
           Product: PulseAudio
           Version: unspecified
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: medium
         Component: modules
        AssignedTo: pulseaudio-bugs at lists.freedesktop.org
        ReportedBy: tanuk at iki.fi
         QAContact: pulseaudio-bugs at lists.freedesktop.org
                CC: lennart at poettering.net


The Sample.Play and Sample.PlayToSink methods take a volume parameter with type
UInt32. The documentation for the parameter is the following:

"The volume at which to play the sample. Pass 65536 to play at the default
level. Larger values are allowed, but those almost never make sense, because
digital amplification very likely causes distortion."

The documentation mentions "the default level". That means the volume that is
saved as the default volume for the sample. The sample volume is determined as
follows:

1. If there's no default volume set, and there's also no volume specified at
the time of playing the sample, the resulting stream will be subject to the
usual volume policy (stream-restore) rules.

2. If there's no default volume set, but there's volume specified at the time
of playing the sample, the resulting stream will use the specified volume. The
policy rules don't apply, at least in the case of stream-restore.

3. If there's a default volume set, and there's no volume specified at the time
of playing the sample, the resulting stream will use the default volume. The
policy rules don't apply, at least in the case of stream-restore.

4. If there's a default volume set, and there's also some volume specified at
the time of playing the sample, the resulting stream will use the default
volume and the play-time volume combined. The policy rules don't apply, at
least in the case of stream-restore.

The right way to use the sample cache is almost always case 1, because that way
stream-restore can do its magic properly. The D-Bus interface can't be used in
this way, because it requires the method caller to always specify some volume,
which means that only scenarios 2 or 4 can ever be triggered. I think the
correct fix would be to make the volume argument a fake "Maybe" type: make it
an array with zero or one member, zero meaning null, ie. no volume specified.

A sidenote: I don't really see how the default volume for samples is useful. Is
that feature used by anyone?

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.