Simonc: Created page with "= Volume Service = == Overview == The Volume service provides a means of controlling various settings which affect the product's volume (signal amplitude) measured at the output ..."

2015-12-15T13:00:03Z

Created page with "= Volume Service = == Overview == The Volume service provides a means of controlling various settings which affect the product's volume (signal amplitude) measured at the output ..."

New page

= Volume Service =
== Overview ==
The Volume service provides a means of controlling various settings which affect the product's volume (signal amplitude) measured at the output channels. A product may have one or more output channels. Balance or Fade settings may result in different volumes at each output. In the Mute state, all output channels are reduced to zero volume.

If a device's [[Av:Developer:Eriskay:ProductService | Product]] service reports an attribute <tt>"Volume"</tt>, then that device is guaranteed to bear the Volume service. If the Volume service is available, all its properties and actions must be fully implemented.

<tt>Volume</tt> is an adjustable setting that controls the loudness of the audio at the output channels of the product. It can be set to an absolute value or incremented/decremented in single steps of integrator-defined size. The maximum <tt>Volume</tt> setting is defined by the current value of <tt>VolumeLimit</tt>. The minimum Volume setting is always zero.

<tt>Balance</tt> is an adjustable setting that specifies the bias in volume between left and right output channels. A setting of zero results in neutral balance (i.e. no bias applied) between left and right output channels. Negative values amplify left and attenuate right output channels. Conversely, positive values attenuate left and amplify right output channels. Increasing absolute values result in progressively larger amplification/attenuation being applied to output channels in this asymmetric manner. At or near the maximum settings, the attenuated channels may ended up being effectively reduced to volume zero.

<tt>Fade</tt> is an adjustable setting that specifies the bias in volume between the front and rear output channels.

== Evented Properties ==
=== Volume ===
The current user volume setting, i.e. an integer value in the range <tt>[0..VolumeLimit]</tt>.

=== Mute ===
A boolean setting indicating whether all output channels are currently forced to zero volume.

Note that (un)muting a product has no effect on its <tt>TransportState</tt> or it's ability to send audio to other rooms.

=== VolumeLimit ===
User-imposed (soft) maximum volume setting. Must be in the range <tt>[0..VolumeMax]</tt>; other values will be ignored.

=== VolumeMax ===
System-imposed (hard) maximum volume setting. Must be exactly divisible by <tt>VolumeSteps</tt>.

=== VolumeUnity ===
System-specific volume setting that results in the input signal amplitude equalling the output signal amplitude (0dB gain), i.e. an integer in the range <tt>[0..VolumeMax]</tt>.

Values in the range <tt>[0..VolumeUnity)</tt> will be attenuated. Values in the range <tt>(VolumeUnity..VolumeLimit]</tt> will be amplified.

=== VolumeSteps ===
System-specific number of user-visible volume steps that would increase the volume from zero to <tt>VolumeMax</tt>.

=== UnityGain ===
<tt>true</tt> if the active source as reported by the ["ProductServiceEriskay" Product] service is already volume controlled; <tt>false</tt> otherwise.

Changes to <tt>Volume</tt> will be accepted while <tt>UnityGain</tt> is enabled but will have no immediate effect.

=== Balance ===
Current setting of bias between left and right output channels, i.e. an integer value in the range <tt>[-BalanceMax..+BalanceMax]</tt>.

Negative values amplify left and attenuate right output channels. Conversely, positive values attenuate left and amplify right output channels.

A value of zero specifies no bias.

=== BalanceMax ===
System-specific balance value for maximum bias between left and right channels.

=== Fade ===
Current setting of bias between front and back output channels, i.e. an integer value in the range <tt>[-FadeMax..+FadeMax]</tt>.

A value of zero specifies no bias.

=== FadeMax ===
System-specific fade value for maximum bias between front and rear between channels.

== Actions ==
=== Characteristics ===
<tt>
Arguments: (out uint volMax, out uint volUnity, out uint volSteps, out uint balanceMax, out uint fadeMax)
</tt> 
Return the values of the system-specified properties which do not change at run-time - <tt>VolumeMax</tt>, <tt>VolumeUnity</tt>, <tt>VolumeSteps</tt>, <tt>BalanceMax</tt> and <tt>FadeMax</tt>.

=== Volume ===
<tt>
Arguments: (out uint volume)
</tt> 
Return the current value of the <tt>Volume</tt> property.

=== SetVolume ===
<tt>
Arguments: (in uint volume)
</tt> 
Set the <tt>Volume</tt> property to an absolute value.

Any attempt to set a value above the <tt>VolumeLimit</tt> must reset <tt>Volume</tt> to <tt>VolumeLimit</tt>.

=== VolumeInc ===
<tt>
Arguments: None
</tt> 
Increase <tt>Volume</tt> by <tt>VolumeMax / VolumeSteps</tt>.

=== Volume Dec ===
<tt>
Arguments: None
</tt> 
Decrease <tt>Volume</tt> by <tt>VolumeMax / VolumeSteps</tt>.

=== VolumeLimit ===
<tt>
Arguments: (out uint limit)
</tt> 
Return the value of the <tt>VolumeLimit</tt> property.

=== UnityGain ===
<tt>
Arguments: (out uint unityGain)
</tt> 
Return the value of the <tt>UnityGain</tt> property.

=== Balance ===
<tt>
Arguments: (out int balance)
</tt> 
Return the value of the <tt>Balance</tt> property.

=== SetBalance ===
<tt>
Arguments: (in int balance)
</tt> 
Set the <tt>Balance</tt> property to an absolute value.

=== BalanceInc===
<tt>
Arguments: None
</tt> 
Increase <tt>Balance</tt> by <tt>1</tt>.

=== BalanceDec ===
<tt>
Arguments: None
</tt> 
Decrease <tt>Balance</tt> by <tt>1</tt>.

=== Fade ===
<tt>
Arguments: (out int fade)
</tt> 
Return the value of the <tt>Fade</tt> property.

=== SetFade ===
<tt>
Arguments: (in int fade)
</tt> 
Set the <tt>Fade</tt> property to an absolute value.

=== FadeInc ===
<tt>
Arguments: None
</tt> 
Increase <tt>Fade</tt> by <tt>1</tt>.

=== FadeDec ===
<tt>
Arguments: None
</tt> 
Decrease <tt>Fade</tt> by <tt>1</tt>.

=== Mute ===
<tt>
Arguments: (out bool mute)
</tt> 
Return the value of the <tt>Mute</tt> property.

=== SetMute(in bool mute) ===
<tt>
Arguments: (in bool mute)
</tt> 
Set the <tt>Mute</tt> property.

== UPnP Service Description ==
For devices supporting the UPnP protocol, the service description is

<tt>name: "Volume"
 domain: "openhome.org.eriskay"
 version: "1"</tt>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>Characteristics</name>
<argumentList>
<argument>
<name>VolumeMax</name>
<direction>out</direction>
<relatedStateVariable>VolumeMax</relatedStateVariable>
</argument>
<argument>
<name>VolumeUnity</name>
<direction>out</direction>
<relatedStateVariable>VolumeUnity</relatedStateVariable>
</argument>
<argument>
<name>VolumeSteps</name>
<direction>out</direction>
<relatedStateVariable>VolumeSteps</relatedStateVariable>
</argument>
<argument>
<name>BalanceMax</name>
<direction>out</direction>
<relatedStateVariable>BalanceMax</relatedStateVariable>
</argument>
<argument>
<name>FadeMax</name>
<direction>out</direction>
<relatedStateVariable>FadeMax</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetVolume</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Volume</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>VolumeInc</name>
</action>
<action>
<name>VolumeDec</name>
</action>
<action>
<name>Volume</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Volume</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetBalance</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Balance</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>BalanceInc</name>
</action>
<action>
<name>BalanceDec</name>
</action>
<action>
<name>Balance</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Balance</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetFade</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Fade</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>FadeInc</name>
</action>
<action>
<name>FadeDec</name>
</action>
<action>
<name>Fade</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Fade</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>SetMute</name>
<argumentList>
<argument>
<name>Value</name>
<direction>in</direction>
<relatedStateVariable>Mute</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>Mute</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>Mute</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>VolumeLimit</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>VolumeLimit</relatedStateVariable>
</argument>
</argumentList>
</action>
<action>
<name>UnityGain</name>
<argumentList>
<argument>
<name>Value</name>
<direction>out</direction>
<relatedStateVariable>UnityGain</relatedStateVariable>
</argument>
</argumentList>
</action>
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>Volume</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Mute</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Balance</name>
<dataType>i4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>Fade</name>
<dataType>i4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>VolumeLimit</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>VolumeMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>VolumeUnity</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>VolumeSteps</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>UnityGain</name>
<dataType>boolean</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>BalanceMax</name>
<dataType>ui4</dataType>
</stateVariable>
<stateVariable sendEvents="yes">
<name>FadeMax</name>
<dataType>ui4</dataType>
</stateVariable>
</serviceStateTable>
</scpd>
</syntaxhighlight>

Av:Developer:Eriskay:VolumeService - Revision history

Simonc: Created page with "= Volume Service = == Overview == The Volume service provides a means of controlling various settings which affect the product's volume (signal amplitude) measured at the output ..."