View source

== Proposer ==

Lennart Poettering (http://0pointer.de/lennart)

== Purpose ==

Implementing a module that adds "volume-follows-focus" behaviour to PulseAudio (PA). 

== Abstract ==

"volume-follows-focus" behaviour shall mean that if you have one Totem and one swfdec window open on your desktop, if Totem is in foreground its sound should be at 100% volume while swfdec should be at 20%. If you switch focus so that swfdec is in foreground its volume shall be slided up to 100% while Totem is attenuated to 20% or similar.

Basically this shall integrate window and volume management in a sensible and user-friendly way. We will follow inside PA what the focussed window on the screen is and then adjust the volume for all streams that are tagged to be owned by the this window or by the same process.

== Pre-requisites ==

You need to know C well.

You should have read up about PA. I.e. you should understand what sink/source/sink inputs/source outputs are. How modules are configured. it would be good to also have a superficial knowledge of the PA source code. However the really complex IO/real-time/atomic-operation parts of PA need not be understood, since it won't be necessary for our workout.

You should have a superficial knowledge of X11. I.e. what windows, window properties, screens, displays and so on are. You should read a few man pages, such as XGetWindowProperty(3) and related pages. You should have played around with xprops and xprops -root.

You should have read the EWMH specs, http://standards.freedesktop.org/wm-spec/wm-spec-latest.html, specifically the parts about _NET_ACTIVE_WINDOW and related.

=== Languages, tools to be known ===

As mentioned, you should know C. And a bit of the autotools (automake, autoconf, ...)

=== Getting and compiling the code ===

You should get a current checkout of PA from git, and installed all dependencies so that you can build it locally. If you have questions about this ask on #pulseaudio in freenode. With a bit persistance you'll find someone who can respond to your questions.

=== Links to overall design/architecture ===

There's a bit of documentation about PA's internals. It's a bit out of date and should be taken with a grain of salt.

http://pulseaudio.org/wiki/DeveloperDocumentation#DevelopingModules

== Pre-event planning ==

Note much necessary. The goal should be clear. 

=== Tasks ===

1. Write some code that allows our little PA module to follow which window is focussed on the screen
2. Write some code that allows our little PA module to follow which streams are created/removed
3. Write some code that is able to recognize which windows and streams belong together (via process info, ...)
4. Write some code that uses this information to actually adjust the volume.
5. Play around with things and develop a policy that actually covers most uses cases. (i.e. event sounds probably should not be touched by this modules. We should never emphasize, only attenuate. We should not attenuate unless there is at least one stream that belongs to the active window, and so on)
6. ...
7. Profitt!!!

(In the unlikely event that we will have too much time we will work on modifying this logic for soft fading when window switches happen)

=== Existing work ===

There are a few modules in the PA build tree that can use as example how to write modules. module-stream-restore is one example.

=== Getting in touch ===

#pulseaudio on irc.freenode.org

http://pulseaudio.org/wiki/Community

== Participants ==

* Lennart Poetterin
* Debarshi Ray
* Arjun
* Shreyas Srinivasan
* Arun Raghavan

== Report ==

* Some time spent on introduction, PA internals
* Need to maintain a mapping of stream <-> window_list for an application (no real way to map for now, so will use <hostname, pid> for matching)
* Need to keep mapping updated across the following events:
** Window creation
** Window deletion
** Stream creation
** Stream deletion
** Window focus change
* Divided into 2 tasks
** Investigate, write code to get window events from above list (Debarshi, Arjun) (basically done)
** Write a PA module with hooks for stream/creation deletion, write infrastructure to maintain above list (Arun, Shreyas) (first done, second TBD)
** Integrate these 2, change volume on focus change, ???, Profit!!!