[prev in list] [next in list] [prev in thread] [next in thread]
List: kde-core-devel
Subject: RFC: KDE4, KMix and a public Mixer API (possibly freedesktop.org)
From: Christian Esken <esken () kde ! org>
Date: 2006-10-08 18:03:05
Message-ID: 200610082003.06069.esken () kde ! org
[Download RAW message or body]
Hello,
I am currently working on a Mixer Service API for KDE4.
The API is targeted at mixer services (like kmixd), a Mixer (like kmix) and several \
MM apps. It can be used for changing volumes, retrieving volume changes, querying for \
mixers, detecting hot-plugged soundcards/mixers and some more services.
I am cross-posting this to kde-core-devel, because i am quite certain that many \
affected developers are not subscribed to the kde-multimedia ML.
Rationale:
1) Have a well defined interface for as many applicatons as possible (KMix, KMilo, \
Screensavers (might want to "dim Sound"), Phonon, VOIP-Apps, and more) 2) Have a \
"Cross-Desktop" API: Users like a coherent experience. Why should Audacity or \
Realplayer behave "differently" from native KDE appplications? So after all this \
might be eligible for freedesktop.org. 3) Have a "Cross-Platform" API: Applications, \
even if they do only a tiny bit of MM like changing volumes, can often only be \
compiled under Linux. In any case it will for example ease the pain to port to Mac OS \
X.
The API is noted in DBUS style (fully conversion of the signals open yet), and meant \
as a RFC. It will be changed and extended as comments flow in (for example I would \
like to add keyboard shortcut management, as currently 3-n applications fight e.g. \
for the XF86AudioRaiseVolume shortcut).
Comments are always welcome,
Christian
PS: People normally expect to see a lot of UDI stuff in the API But the UDI is used \
as little as possible. This is because it is "unstable" in the sense that it might \
change when unplugging and hotplugging again. For the same reason the UDI cannot be \
used in finding an appropriate configuration for a device, and so on. So the mixer \
server hides the UDI, and is responsible for creating a more "stable" ID. Today I am \
using the card name + instance number (e.g. "Sound_Fusion_CS46xx:0").
["Mixer Service API.xml" (text/xml)]
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" \
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
<interface name="org.kde.MixerService">
<!-- Retrieve an list of ID's for all currently known Mixers ("coldplug") -->
<method name="getMixers">
<arg name="id_list" type="as" direction="out"/>
</method>
<!-- Notifies client application that a mixer device with ID id was hotplugged. -->
<signal name="mixerPlugged">
<!-- This does not conform to DBUS DTD-->
<arg type="s"/> <!-- id -->
</signal>
<!-- Notifies client application that a mixer device with ID id was unplugged. -->
<signal name="mixerUnplugged">
<!-- This does not conform to DBUS DTD-->
<arg type="s"/> <!-- id -->
</signal>
<!-- Change volume of one control.
If the volume array contains exactly one value, all channels of this control \
will be changed.
Otherwise volume[0] is ignored and all given channels will be changed \
appropriately. Channels which do not exist are ignored.
Volume values with illegal values are ignored, and the affected channel(s) will \
not be changed.
-->
<method name="setVolume">
<arg name="mixer_id" type="s" direction="in"/>
<arg name="control_id" type="s" direction="in"/>
<arg name="volume" type="ax" direction="in"/>
</method>
<!-- Change switch state volume of one control
If the switch array contains exactly one value, all channels of this control \
will be changed.
Otherwise switch[0] is ignored and all given channels will be changed \
appropriately. Channels which do not exist are ignored.
-->
<method name="setSwitch">
<arg name="mixer_id" type="s" direction="in"/>
<arg name="control_id" type="s" direction="in"/>
<arg name="switch" type="ab" direction="in"/>
</method>
<!-- Change enum value of one control
Sets the new value of the Switch. You cannot pass arbitrary values, but only the \
ones supported by this switch.
Please see getMixer() and the enum attribute for details. If an unsupported \
value is passed, it is ignored.
-->
<method name="setEnum">
<arg name="mixer_id" type="s" direction="in"/>
<arg name="control_id" type="s" direction="in"/>
<arg name="value" type="s" direction="in"/>
</method>
<!-- Allows to rename a control or the mixer. This will lead to a broadcast of \
controlChanged(). --> <method name="setName">
<arg name="mixer_id" type="s" direction="in"/>
<arg name="control_id" type="s" direction="in"/>
<arg name="name" type="s" direction="in"/>
</method>
<!-- Notifies client application that control "id" in the mixer "mixer_id" has \
changed state.
Which component of the control has changed is given by the parameters.
It can be the volume, the switch, the enum, the name or other.
Please note that arrays of volumes (and arrays of switch values) are returned.
This is because a control can have 2 volumes (Stereo) and much more (Digital 5.1 \
or 7.1). volume[0] Average volume of all volumes of this control
switch[0] true, if ALL switches of thsi control are on. false otherwise.
volume[1] fl Front Left (same for switch[1]). 2.0 and higher
volume[2] fr Front Right (same for switch[2]). 2.0 and higher
volume[3] sl Surround Left (same for switch[3]). 4.0 and higher
volume[4] sr Surround Right (same for switch[4]). 4.0 and higher
volume[5] ce Center (same for switch[5]). Usually 5.0 and higher
volume[6] sw LFE/Subwoofer (same for switch[6]). Usually 4.1 and higher
volume[7] rl Rear Left (same for switch[7]). Used only in 7.0 and \
7.1.
volume[8] rr Rear Right (same for switch[8]). Used only in 7.0 and \
7.1.
volume[9] rc Rear Center (same for switch[9]). Used only in 6.0 and \
6.1.
"other" is an extension point, and normal applications SHOULD not evaluate the \
"other" parameter at all.
Appliations SHOULD use name-value pairs for the extension (key = value).
The first name value-pair SHOULD be "extension = <extension-id>", for example \
"extension = x-KDE-TooltipValue".
-->
<signal name="controlChanged">
<!-- This does not conform to DBUS DTD-->
<arg name="mixer_id" type="s" direction="in"/>
<arg name="control_id" type="s" direction="in"/>
<arg name="volume_changed" type="b" direction="in"/>
<arg name="volume" type="ax" direction="in"/>
<arg name="switch_changed" type="b" direction="in"/>
<arg name="switch" type="ab" direction="in"/>
<arg name="enum_changed" type="b" direction="in"/>
<arg name="enum" type="s" direction="in"/>
<arg name="name_changed" type="b" direction="in"/>
<arg name="name" type="s" direction="in"/>
<arg name="other" type="as" direction="in"/>
</signal>
<!-- Returns the state and the capabilites of a control.
You might want to use this after initialization of your application, to query \
all controls.
Return values that make no sense for the speific control are emtpy (empty string \
or empty array). For example a control of type "enum" has an empty volume[] array.
The "volume_caps" out parameter is a boolean array. The meaning is:
An empty list means, that there is no volume capability on this control.
volume_caps[0] == false : Control doesn't support the capability
volume_caps[0] == true : Control supports the capability and can be \
operated with control commands.
volume_caps[1..n] == true : Control supports the capability and can be \
operated with channel commands.
If you want to use channel commands, you must \
evaluate the volume_caps[]
to find out which channels are available. Please \
see controlChanged() for the
mapping from number to actual channel.
The same is valid for the "switch_caps" out parameter.
The enum_caps[] holds the list of valid enums values for the multiple choice \
selector. An empty list means,
that there is no enum capability on this \
control..
Mixer controls that support both playback AND capture are reported as two \
separate controls (independent of
the actual Mixer hardware). A control that supports multiple choice items is \
reported as another control.
-->
<method name="getControl">
<arg name="mixer_id" type="s" direction="in"/>
<arg name="control_id" type="s" direction="in"/>
<arg name="volume_caps" type="ab" direction="out"/>
<arg name="volume" type="ax" direction="out"/>
<arg name="switch_caps" type="ab" direction="out"/>
<arg name="switch" type="ab" direction="out"/>
<arg name="enum_caps" type="as" direction="out"/>
<arg name="enum" type="s" direction="out"/>
<arg name="name" type="s" direction="out"/>
<arg name="other" type="as" direction="out"/>
</method>
<!-- Retrieve information of the mixer given with ID mixer_id including a list of its \
controls.
@param mixer_id The Mixer in question. You can pass the string \
"Mixer::DEFAULT" to retrieve the users default mixer device.
@returns udi The UDI correspondign to the mixer_id
@returns dev Device name needed to access this device, e.g. "/dev/mixer2" \
or "hw:0". For diagnosis.
@returns name The name of the device in human readable form. Usable for \
displaying on a screen. @returns controls A list of unique control names. Mixer \
controls that support both playback AND capture are reported as two separate \
controls, independent of how the actual Mixer driver represents it. A control that \
supports multiple choices (an enum) is also reported as another \
control.
-->
<method name="getMixer">
<arg name="mixer_id" type="s" direction="in"/>
<arg name="udi" type="s" direction="out"/>
<arg name="dev" type="s" direction="out"/>
<arg name="name" type="s" direction="out"/>
<arg name="controls" type="as" direction="out"/>
</method>
</interface>
</node>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic