Bug 39403

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?