[pulseaudio-discuss] GSoC Proposal: Configurable maximum volume for sinks and sources

[Tanu Kaskinen]

On Sun, 2012-03-25 at 16:45 +0200, Matěj Laitl wrote:
> Hi Tanu and pulseaudio-discuss,
> I'd like to participate as a student in GSoC 2012 working on PulseAudio. Among 
> suggested ideas I've chosen Configurable maximum volume for sinks and sources, 
> below is a very draft of my proposal.

Excellent!

> I'd be very grateful for any comments, suggestions, pointed-out omissions and 
> general questions that may arise. I've also thought about extending the 
> proposal a bit to add code to deal with stereo microphones where one channel 
> is inverted (supposedly common problem) -- but I've heard on #pulseadio this 
> is already being worked on. What do you think?

IIRC, if someone is working on this, it's David Henningsson. My
impression is, though, that there's no implementation work done yet. So,
hopefully David can give a status update. Probably this microphone fix
would be a fine extra project for the summer. Do you have this
microphone problem yourself?

Note, however, that there's another "extra" job that you'd preferably do
before starting with the volume things (or at least before starting to
extend the client API), which reduces the probability of running out of
stuff to do. One of the project ideas is a "configuration system". There
was a discussion between me, Colin and Arun, and we thought that it
would be really good if the volume limit feature could use the
configuration system's client API as the client interface. Since the
configuration system doesn't exist, designing the client API for it
would have to be part of the volume limit project. The API probably can
be quite simple, since all it has to do is to provide means for getting
and setting configuration values and for subscribing to updates. You
wouldn't have to implement the whole configuration infrastructure, only
as much as is needed to make the limit configuration to work. We should
update the idea page to reflect this...

BTW, as you obviously have found #pulseaudio, what's your nick?

> Introduction
> =======
> Recent PulseAudio versions gained an ability to amplify signal of inputs and 
> outputs in software. While this is often needed for low-amplitude signals, 
> software amplification can cause negative effects such as clipping and should be 
> avoided if possible. Sometimes, even without amplification, outputs may be able 
> to produce sound that is unacceptably loud. In both situations user should be 
> able to set volume limit to prevent her ears and/or equipment from discomfort 
> or even damage. Many portable audio players are able to do this, this project 
> is about supporting volume limits in PulseAudio.
> 
> Project goals
> =======
> What will be implemented in PulseAudio in this project:
>  * support for enforcing volume limits in [TODO: ALSA-based?] Sources and 
> Sinks; the limits can be 
> changed on-the-fly
>  * support for persisting volume limits across PulseAudio restarts
>  * user-friendly GUI to configure volume limits by extending KDE's KMix or 
> PulseAudio's pavucontrol. [TODO: I would love to make both, but it's hard to 
> estimate how much time it will take]
> 
> Implementation
> =========
> [this section is based on my rather incomplete understanding of the code; 
> please correct me where I'm wrong]
> 
> PulseAudio's architecture is based on modules that can provide Sources (audio 
> inputs), Sinks (audio outputs), networking protocols and more. Sinks are 
> represented with a C struct pa_source defined in pulsecore/sink.h; Sources use 
> analogous structure pa_sink. Modules then implement Sources and Sinks by 
> setting various callbacks in the structs to their functions and filling fields 
> with their data.
> 
> [TODO: this project should focus on ALSA, right?] Relevant for this project is 
> the module-alsa-card (which shares Sink and Source code with module-alsa-sink, 
> module-alsa-source) that implements Sinks & Sources atop of the most prevalent 
> Linux sound system, ALSA. For the first iteration, the module(s) will be made 
> to accept volume_limit parameter that will be enforced in 
> {sink,source}_set_volume_cb() (TODO: this seems to only work for 	hardware 
> volumes?)

It should be possible to set limits for any devices, not only for alsa
devices. There may be need to adapt the backend modules to the changes,
but the focus should be in working with sinks, sources and device
ports[1] in general, not with some specific backend. The set_volume_cb
functions indeed only work with hardware volumes, so they aren't really
the right place to do the limit enforcement.

Volume handling is pretty complex in Pulseaudio, so getting a good
picture of the whole volume system will probably take some time. Here's
one hint: you'll want to apply the limit to reference_volume. That's the
volume that you see in KMix.

I wrote in the wiki that the project would start with making it possible
to configure the limits with module arguments, but actually I don't
think that is a very important feature in the end. You can do that if
you start with implementing the volume limits and you need the module
arguments for experimenting in the beginning, but if you start with the
client API, that should make experimenting easy without any new module
arguments.

[1] The limits need to be handled separately for each port. It's not
sufficient to have per-sink limits.

> For complete integration, pa_{sink,source} structs along with related 
> functions will have to be extended to cope with volume limits. To expose these 
> limits, the pulseaudio native protocol, cli protocol (therefore pacmd tool) 
> and the pactl tool will be extended, along with the PulseAudio client library, 
> libpulse. Finally, KDE's KMix will be tweaked to allow displaying and setting 
> the volume limits. (preferably in the same widget where the volume is set)
> 
> Timeline
> =====
> [subject to change as many implementation details are not yet ironed out]
>  * Community bonding period: ironing out the design; where and how volume
>    limits should be implemented.
>  * 1. & 2. week: volume limits passed through module params enforced for ALSA 
> Sinks & Sources
>  * 3. & 4. week: pa_{sink,source} extended to cope with volume limits
>  * 5. week: cli protocol extended so that volume limits can be shown and set 
> in pacmd
>  * 6. week: pacmd tool extended, work on preserving volume limits across 
> restarts
>  * 7. week: native protocol extended
>  --- mid-term evaluation
>  * 1. & 2. week: extending KMix to show & set volume limits
>  * 3. & 4. week: [TODO] extending pavucontrol? unit-tests? 
>  * 5. week: resolving any remaining issues..
> 
> About me
> ======
> I'm a 24-year-old student of mathematical informatics from Prague, Czech 
> Republic. I've been passionate about FLOSS since high school and recently I've 
> started contributing to a couple of projects, most notably Amarok [1]; I even 
> have one small patch in the Linux kernel [2]. I know C, C++, Python, Java, a 
> bit of French (pun intended) and some other less relevant languages. Thanks to 
> Amarok I have experience in GUI programming in Qt & KDE libs, I'd like to 
> learn GTK[mm].
> 
> I've chosen PulseAudio because it appears to me as a sound-system-done-right, 
> in order to learn how to make clean modular apps in C and to work on a project 
> founded by the famous GNU/Linux innovator, Lennart. To get started I've 
> fixed bug 38728 [3].

Sounds very promising so far! Sorry for ruining your timeline
planning :)

-- 
Tanu