TVAudioControl API

This API provides the audio control features (such as volume and mute) on the TV associated device. There will be a tizen.tvaudiocontrol object that allows access to the functionality of the TV Audio Control API.

Since: 2.3

Table of Contents

Summary of Interfaces and Methods

Interface Method
AudioControlManagerObject
AudioControlManager
void setMute (boolean mute)
boolean isMute ()
void setVolume (unsigned short volume)
void setVolumeUp ()
unsigned short getVolume ()
VolumeChangeCallback
void onchanged (unsigned short volume)

1. Type Definitions

1.1. AudioOutputMode

An enumerator to indicate the audio output mode. 
  enum AudioOutputMode { "PCM", "DOLBY", "DTS", "AAC", "DOLBY_DIGITAL_PLUS" };

Since: 2.3

  • PCM - PCM(Pulse-code modulation) audio output mode
  • DOLBY - Dolby audio output mode
  • DTS - DTS(Digital Theater System) audio output mode
  • AAC - AAC(Advanced Audio Coding) audio output mode
  • DOLBY_DIGITAL_PLUS - Dolby Digital Plus audio output mode

Remark: DOLBY_DIGITAL_PLUS is supported since Tizen 5.5

1.2. AudioBeepType

An enumerator to indicate the beep type. 
  enum AudioBeepType { "UP", "DOWN", "LEFT", "RIGHT", "PAGE_LEFT", "PAGE_RIGHT", "BACK", "SELECT", "CANCEL", "WARNING", "KEYPAD",
    "KEYPAD_ENTER", "KEYPAD_DEL", "MOVE", "PREPARING" };

Since: 2.3

  • UP - The UP sound
  • DOWN - The DOWN sound
  • LEFT - The LEFT sound
  • RIGHT - The RIGHT sound
  • PAGE_LEFT - The PAGE LEFT sound
  • PAGE_RIGHT - The PAGE RIGHT sound
  • BACK - The BACK sound
  • SELECT - The SELECT sound
  • CANCEL - The CANCEL sound
  • WARNING - The WARNING sound
  • KEYPAD - The KEYPAD sound
  • KEYPAD_ENTER - The KEYPAD ENTER sound
  • KEYPAD_DEL - The KEYPAD DEL sound
  • MOVE - The MOVE sound
  • PREPARING - The PREPARING sound

2. Interfaces

2.1. AudioControlManagerObject

This interface defines what is instantiated by the Tizen object. 
  [NoInterfaceObject] interface AudioControlManagerObject {
    readonly attribute AudioControlManager tvaudiocontrol;
  };
  Tizen implements AudioControlManagerObject;

Since: 2.3

There will be a tizen.tvaudiocontrol object that allows the access to the Audio Control API.

2.2. AudioControlManager

This interface provides access to the API funtionalities through the tizen.tvaudiocontrol interface. 
  [NoInterfaceObject] interface AudioControlManager {
    void setMute(boolean mute) raises(WebAPIException);
    boolean isMute() raises(WebAPIException);
    void setVolume(unsigned short volume) raises(WebAPIException);
    void setVolumeUp() raises(WebAPIException);
    void setVolumeDown() raises(WebAPIException);
    unsigned short getVolume() raises(WebAPIException);
    void setVolumeChangeListener(VolumeChangeCallback callback) raises(WebAPIException);
    void unsetVolumeChangeListener() raises(WebAPIException);
    AudioOutputMode getOutputMode() raises(WebAPIException);
    void playSound(AudioBeepType type) raises(WebAPIException);
  };

Since: 2.3

Methods

setMute
Turns on or off the silent mode 
void setMute(boolean mute);

Since: 2.3

Note that turning on mute mode does not change volume level but it simply disables any sound. Turning off the mute will enable sound with the volume level. If setVolumeUp or setVolumeDown functions are used, then mute is disabled.

Parameters:

  • mute: The mute state (true = turn on the silent mode, false = turn off the silent mode)

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

Code example:

/* Turns on the silent mode. */
tizen.tvaudiocontrol.setMute(true);

Code example:

/* Turns off the silent mode. */
tizen.tvaudiocontrol.setMute(false);
isMute
Gets the mute state. 
boolean isMute();

Since: 2.3

Return value:

    boolean: boolean The current mute state

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

Code example:

/* Mutes to turn off the sound. */
tizen.tvaudiocontrol.setMute(true);

/* Checks if it is mute or not. */
if (tizen.tvaudiocontrol.isMute())
{
  console.log("At this moment, the sound output of this device is turned off");
}
else
{
  alert("It's not possible!");
}

Code example:

/* Checks if increasing the volume makes the silent mode turned off. */

/* Mutes to turn off the sound. */
tizen.tvaudiocontrol.setMute(true);

/* By increasing the volume level, the mute state is changed to off. */
tizen.tvaudiocontrol.setVolumeUp();

/* Checks if it is mute or not. */
if (tizen.tvaudiocontrol.isMute())
{
  alert("It's not possible!");
}
else
{
  console.log("setVolumeUp() turns off the silent mode");
}
setVolume
Changes the volume level. 
void setVolume(unsigned short volume);

Since: 2.3

The value of volume is allowed from 0 to 100. If an invalid value is passed, InvalidValuesError will occur.

Parameters:

  • volume: The volume (the available volume range is 0 ~100)

Exceptions:

  • WebAPIException

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

Code example:

/* Sets the volume. */
tizen.tvaudiocontrol.setVolume(10);

try
{
  tizen.tvaudiocontrol.setVolume(-1);
}
catch (e)
{
  if (e.name === "InvalidValuesError")
  {
    alert("The passed value value should be in the range of 0 to 100");
  }
  else
  {
    alert("Unexpected error: " + e.name);
  }
}
setVolumeUp
Increases the volume by 1 level. If it is called when the volume level is 100, it will be ignored because the maximum volume level is 100. If mute is enabled, then execution of this functions will disable it. 
void setVolumeUp();

Since: 2.3

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

Code example:

/* Sets the volume. */
tizen.tvaudiocontrol.setVolume(99);

tizen.tvaudiocontrol.setVolumeUp();

/* Checks if the current volume is 100 or not. */
if (tizen.tvaudiocontrol.getVolume() === 100)
{
  alert("setVolumeUp() was called successfully");
}

tizen.tvaudiocontrol.setVolumeUp();

/* Checks if the volume level has been changed or not at the maximum volume level. */
if (tizen.tvaudiocontrol.getVolume() === 100)
{
  alert("setVolumeUp() was successfully called");
}
setVolumeDown
Decreases the volume by 1 level. 
void setVolumeDown();

Since: 2.3

If it is called when the volume level is 0, it will be ignored because the minimum volume level is 0. If mute is enabled, then execution of this functions will disable it.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

Code example:

/* Sets the volume. */
tizen.tvaudiocontrol.setVolume(1);

tizen.tvaudiocontrol.setVolumeDown();

/* Checks if the current volume is 0 or not. */
if (tizen.tvaudiocontrol.getVolume() === 0)
{
  alert("setVolumeDown() was successfully called");
}

tizen.tvaudiocontrol.setVolumeDown();

/* Check if the volume level has been changed or not at the minimum volume level. */
if (tizen.tvaudiocontrol.getVolume() === 0)
{
  alert("setVolumeDown() was successfully called");
}
getVolume
Gets the current volume level. 
unsigned short getVolume();

Since: 2.3

Return value:

    unsigned short: unsigned short The current volume (the volume range is 0 ~ 100)

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

setVolumeChangeListener
Registers a volume change callback for getting notified when TV volume has been changed. 
void setVolumeChangeListener(VolumeChangeCallback callback);

Since: 2.3

Note that this method overwrites the previously registered listener.

Parameters:

  • callback: The method to invoke when the volume has been changed. It will not be triggered when the silent mode is changed.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any input attribute is not compatible with the expected type for this attribute.

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

Code example:

var expectedVolumeLevel = 50;

function onVolumeChanged(volume)
{
  if (volume === expectedVolumeLevel)
  {
    console.log("Success! The volume level has been changed to " + volume);
  }
  else
  {
    alert("Failure! The volume level has been changed to: " + volume + ", we expected: " +
          expectedVolumeLevel);
  }
}

tizen.tvaudiocontrol.setVolume(0);

tizen.tvaudiocontrol.setVolumeChangeListener(onVolumeChanged);

tizen.tvaudiocontrol.setVolume(expectedVolumeLevel);
unsetVolumeChangeListener
Unregisters the volume change callback for detecting the volume changes. 
void unsetVolumeChangeListener();

Since: 2.3

Calling this function has no effect if listener is not set.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

Code example:

var expectedVolumeLevel = 50;

function onVolumeChanged(volume)
{
  alert("This function must not be called");
}

tizen.tvaudiocontrol.setVolume(0);

tizen.tvaudiocontrol.setVolumeChangeListener(onVolumeChanged);
tizen.tvaudiocontrol.unsetVolumeChangeListener();

tizen.tvaudiocontrol.setVolume(expectedVolumeLevel);
getOutputMode
Gets the current audio output mode. 
AudioOutputMode getOutputMode();

Since: 2.3

Return value:

    AudioOutputMode: AudioOutputMode The current audio output mode

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

playSound
Plays the sound of a specific beep. 
void playSound(AudioBeepType type);

Since: 2.3

Parameters:

  • type: The beep type to play

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type UnknownError in an unspecified error case.

2.3. VolumeChangeCallback

This interface defines a volume change callback for getting notified information about the volume changes. 
  [Callback=FunctionOnly, NoInterfaceObject] interface VolumeChangeCallback {
    void onchanged(unsigned short volume);
  };

Since: 2.3

Methods

onchanged
The method invoked when the volume has been changed. 
void onchanged(unsigned short volume);

Since: 2.3

Parameters:

  • volume: The changed volume

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee the running of this application on a device with a TV audio control support, define the following requirements in the config file:

  • http://tizen.org/feature/tv.audio

    • For more information, see Application Filtering.

    4. Full WebIDL

    module TVAudioControl {
  enum AudioOutputMode { "PCM", "DOLBY", "DTS", "AAC", "DOLBY_DIGITAL_PLUS" };
  enum AudioBeepType { "UP", "DOWN", "LEFT", "RIGHT", "PAGE_LEFT", "PAGE_RIGHT", "BACK", "SELECT", "CANCEL", "WARNING", "KEYPAD",
    "KEYPAD_ENTER", "KEYPAD_DEL", "MOVE", "PREPARING" };
  Tizen implements AudioControlManagerObject;
  [NoInterfaceObject] interface AudioControlManagerObject {
    readonly attribute AudioControlManager tvaudiocontrol;
  };
  [NoInterfaceObject] interface AudioControlManager {
    void setMute(boolean mute) raises(WebAPIException);
    boolean isMute() raises(WebAPIException);
    void setVolume(unsigned short volume) raises(WebAPIException);
    void setVolumeUp() raises(WebAPIException);
    void setVolumeDown() raises(WebAPIException);
    unsigned short getVolume() raises(WebAPIException);
    void setVolumeChangeListener(VolumeChangeCallback callback) raises(WebAPIException);
    void unsetVolumeChangeListener() raises(WebAPIException);
    AudioOutputMode getOutputMode() raises(WebAPIException);
    void playSound(AudioBeepType type) raises(WebAPIException);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface VolumeChangeCallback {
    void onchanged(unsigned short volume);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.