Mixer API Design

Thursday, September 20. 2007

After playing with the mixer API a bit I feel confident to be able to go forward a propose a design.

class diagram

I'm happy for people to look over it. Don't think about implementation details but whether this API would be easy to understand, use and still powerful enough for all our desktop uses.

Update: latest version of the diagram at http://vir.homelinux.org/phononmixer.png

Posted by Matthias Kretz in Phonon at 15:09 | Comments (29) | Trackbacks (0)

Trackbacks

Trackback specific URI for this entry

No Trackbacks

Comments

Display comments as (Linear | Threaded)

Just curious, why the difference in IntegerControl::valueChanged() vs. EnumControl::indexChanged() ?

#1 Diederik van der Boor on 2007-09-20 15:58 (Reply)

typical use for an IntegerControl would be a QSlider
typical use for an EnumControl would be a QComboBox

so I modeled their API as counterparts to QSlider/QComboBox

#1.1 Matthias Kretz (Homepage) on 2007-09-20 16:19 (Reply)

If the anticipated UI for an IntegerControl is a QSlider, it might be a good idea to have singleStep and pageStep

#1.1.1 Kevin Krammer on 2007-09-20 19:38 (Reply)

I agree, even though I cannot get that information from ALSA. I guess I just have to implement some sensible algorithm to calculate those values.

#1.1.1.1 Matthias Kretz (Homepage) on 2007-09-20 19:56 (Reply)

Would it not be better to give each node in the graph an id, then give the parent nodes removeElement(id) or removeControl(id) methods and ditch the remove() methods in Element, Control, etc?

This has a couple benefits:

1. Nodes don't have to know their parent
2. Nodes can have multiple parents. Might there be a usecase for sharing a control between multiple elements? (An alternative solution to this would be to connect the signals and slots of related controls)

In other words, this allows the mixer chain to be a DAG, not just a tree. Allowing a DAG now seems more flexible to me.

#2 Craig Howard on 2007-09-20 18:05 (Reply)

regarding (2.): I don't see how a DAG would make sense wrt a mixer. I like to think about these things in physical terms - then it becomes obvious that elements and controls cannot be shared. Consider a physical mixer: it has multiple tracks (elements) each of which contains controls (switches, knobs, sliders). The situation for soundcard mixers is no different (in hardware) only that you could make one Control object change two hardware controls at the same time. But how could a library decide that this is what is wanted? If a task like this needs to be accomplished it's the application's responsibility.

regarding (1.): that's an implementation detail IMO

but I'm considering instead of

control.remove();

element.remove(control);

and instead of

element.remove();

mixer.remove(element);

Otherwise it's too much like "delete this" - which is not wrong, just awkward.

#2.1 Matthias Kretz (Homepage) on 2007-09-20 18:21 (Reply)

I can't think of any concrete use for a DAG either; however, element.remove(control) has more flexibility. This is what I'm proposing and used a DAG as a motivating example.

Yes #1 is an implementation detail, but the original proposed API forces that detail (without jumping through some crazy hoops). In my experience it's worth thinking about the implementation, just not letting the initial implementation bind your hands.

I also suggested creating an id to avoid the question of value type vs comparing pointers. Again, I feel it's a more flexible solution.

#2.1.1 Craig Howard on 2007-09-20 18:28 (Reply)

Ok, let's think a bit about implementations: Why do you need an id (integer you're thinking, I guess) if you already have the Mixer/Element/Control objects? Those objects identify the relevant hardware. Code examples:

QList<Mixer> allMixers = MixerList::availableMixers();
Mixer specificMixer("hw:0");
foreach(const Mixer &m, allMixers) {
if (specificMixer == m) {
// success
}
}

The same holds for Element and Control objects, though I think there it's more obvious that the objects are equal since those classes don't have their own ctors.

Do you agree that the object is the id?

Regarding #1 again: can you come up with a use case/code example where it would be a problem/hindrance to have a parent relationship? Because I currently can't see how decoupling would help, instead I think that (coming from the physical picture again) a control/element cannot exist without a mixer.

#2.1.1.1 Matthias Kretz (Homepage) on 2007-09-20 18:43 (Reply)

I agree that using the object itself as the identifier works well. However, that means that you either:

a. Allocate on the heap and use pointer equality

or

b. Make the objects all value classes, so you can put them in containers, compare them, etc.

Granted option b. makes it obvious how you're supposed to compare two objects and find the equivalent one to remove from the list, I just feel that adding an identifier makes it that much more obvious when two objects are equivalent. Perhaps that's exposing an implementation detail (I agree with you in this case).

I wouldn't make the id just an integer. I'd probably define a type that wraps an integer, but won't implicitly convert. This prevents mixing up id types.

And, no, I can't come up with a use case where it's problem/hindrance to force a parent/child relationship. But why force it, when you can leave either option open with a small API change? I don't want to try to predict how this API will be used five years from now.

BTW, I haven't mentioned this previously, but nice work! I'm mostly nitpicking.

#2.1.1.1.1 Craig Howard on 2007-09-21 08:55 (Reply)

I'm currently going for b: explicitly shared value-based classes.

Can you give an example how the API would look like, because I still don't really see what you mean. I.e. how can you have a Control object without an explicit Element parent which has an explicit Mixer parent?

#2.1.1.1.1.1 Matthias Kretz (Homepage) on 2007-09-21 12:44 (Reply)

I thought the plan was for Phonon to use an external Mixer, hardware ALSA or Pulse for examples. With Phonon it would be very easy to redicet all KDE applications to the relivent Mixer.

What caused this change in the plan?

#3 somebody on 2007-09-20 18:55 (Reply)

No change in plans. This is about an API for accessing the mixer of the soundcard, e.g. what kmix does.

#3.1 Matthias Kretz (Homepage) on 2007-09-20 19:04 (Reply)

Thanks for the quick reply

Could this also access the mixer for Pulse, JACK or whatever you plug phonon into?

#3.1.1 somebody on 2007-09-21 14:23 (Reply)

Yes, it could. AFAIK jack (from the versions I know) has no native mixer controls, but I'd expect pulse to have them.

#3.1.1.1 Matthias Kretz (Homepage) on 2007-09-21 14:59 (Reply)

Probably rename the SwitchControl to ToggleControl

#4 Kevin Krammer on 2007-09-20 19:10 (Reply)

Good suggestion, thanks. I updated the diagram.

#4.1 Matthias Kretz (Homepage) on 2007-09-20 19:21 (Reply)

The methods probably more along QAbstractButton's API, i.e.
isChecked, setChecked
signal:toggled(bool)

#4.1.1 Kevin Krammer on 2007-09-20 19:49 (Reply)

OTOH I thought it would be nice if the API of the different Control subclasses would be similar.

#4.1.1.1 Matthias Kretz (Homepage) on 2007-09-20 19:57 (Reply)

Ah no, you're right. EnumControl is already different anyway. I'll change it.

#4.1.1.1.1 Matthias Kretz (Homepage) on 2007-09-20 20:01 (Reply)

Any more comments about the class names?

suggestions for Element:
- MixerElement
- Track
- MixerTrack
- Channel
- MixerChannel

Element is very generic, Channel also has a meaning like left/right channel, Track makes me think of a specific thing: gain, EQ, Aux, mute, volume slider, routing which this is not about.

#5 Matthias Kretz (Homepage) on 2007-09-20 19:19 (Reply)

Can you given an example for an Element?

#5.1 Kevin Krammer on 2007-09-20 19:31 (Reply)

Examples:
- Master (Volume slider, Panorama, mute button)
- PCM (Volume slider, Panorama, mute button)
- Capture (Volume slider, Panorama, capture source enum)
- External Amplifier (toggle button)

#5.1.1 Matthias Kretz (Homepage) on 2007-09-20 19:42 (Reply)

I think both Element as well as Channel or Item would be ok.

Probably also Device

#5.1.1.1 Kevin Krammer on 2007-09-20 19:45 (Reply)

So far we have:
- Item
- MixerItem
- Element
- MixerElement
- Channel
- MixerChannel
- Device
- MixerDevice
- Track
- MixerTrack

#5.2 Matthias Kretz (Homepage) on 2007-09-20 20:07 (Reply)

There is a typo in isWriteable(), should be isWritable()

I also always get this wrong and trigger a nice reminder by the compiler

#6 Kevin Krammer on 2007-09-20 19:47 (Reply)

Yes, I don't see the need for Control::remove() either. Thus I sustain your comment #2.1

#7 Cristian Tibirna on 2007-09-21 12:56 (Reply)

What I cannot see yet in the Phonon api is how it will be possible to handle a more complex application, say a videoconferencing app.

This app would need a mixer for handling the microphone input and a mixer for handling the speaker output.

Is the phonon api capable of handling such a combination? Everything seems poised towards playback for now...

#8 Claudio Bantaloukas (Homepage) on 2007-09-21 18:02 (Reply)

Right, the API currently omits everything that the backend does not implement (phonon-xine uses xine-lib and that does only playback, so your observation is correct

). Otherwise you'd have a frustrating experience using Phonon as a developer...

Mixer in the context you're using it is ambiguous. Do you mean mixing two audio streams into one, or do you mean the volume/mute controls? The latter does not <b>have</b> to be handled by the application IMHO, but it would be nice if it could. And with the work I'm currently doing this will be possible.

#8.1 Matthias Kretz (Homepage) on 2007-09-21 18:24 (Reply)

I meant the volume/mute controls.

In the beginning I thought that KMixer would attach to an object representing a full duplex audio device (i.e. a typical soundcard with sound input and output).
If that were the case, it would have to provide a way for the calling programs to know whether an element (volume control) is for recording or for playback (so that a logical separation can be achieved like in kmixer)

But it seems to me like a KMixer is an object you attach in a pipeline between the AudioOutput object and the MediaObject that needs to be played back.

Since there is no corresponding Audio_Input_ object, my comment is out of scope, maybe something like this would be an interesting addition... an a one-stop recording solution for kde programs...

#9 Claudio Bantaloukas (Homepage) on 2007-09-21 20:10 (Reply)

Add Comment

Name
Email
Homepage
In reply to
Comment	E-Mail addresses will not be displayed and will only be used for E-Mail notifications To prevent automated Bots from commentspamming, please enter the string you see in the image below in the appropriate input box. Your comment will only be submitted if the strings match. Please ensure that your browser supports and accepts cookies, or your comment cannot be verified correctly. Enter the string from the spam-prevention image above: HTML-Tags will be converted to Entities. You can use [geshi lang=lang_name [,ln={y\|n}]][/lang] tags to embed source code snippets Standard emoticons like :-) and ;-) are converted to images.
	Remember Information? Subscribe to this entry