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

[Matěj Laitl]

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.

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?

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?)

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].

Regards,
			Matěj

[1] https://www.ohloh.net/accounts/strohel
[2] goo.gl/WNsnB
[3] goo.gl/rCVGa