Sound API

The Sound API provides functions to control the volume level for several sound types and to check whether a specified sound device type is connected.

You can get the maximum volume level for system, notifications, alarm, media and so on. Also, you can change or get the current volume level.

For more information on the Sound features, see Audio Management Guide.

Since: 2.3

Table of Contents

Summary of Interfaces and Methods

Interface Method
SoundManagerObject
SoundManager
void setVolume (SoundType type, double volume)
double getVolume (SoundType type)
SoundDeviceInfo
SoundModeChangeCallback
SoundVolumeChangeCallback
void onsuccess (SoundType type, double volume)
SoundDeviceStateChangeCallback

1. Type Definitions

1.1. SoundType

Sound type to control 
  enum SoundType { "SYSTEM", "NOTIFICATION", "ALARM", "MEDIA", "VOICE", "RINGTONE" };

Since: 2.3

  • SYSTEM - for system sounds
  • NOTIFICATION - for notifications
  • ALARM - for alarm
  • MEDIA - for media playback
  • VOICE - for voice
  • RINGTONE - for the phone ring

Remark: VOICE type might not be supported on a device which does not support voice recognition.

1.2. SoundModeType

Sound mode type 
  enum SoundModeType { "SOUND", "VIBRATE", "MUTE" };

Since: 2.3

  • SOUND - the sound mode
  • VIBRATE - the vibrate mode
  • MUTE - the mute mode

1.3. SoundDeviceType

Sound device type 
  enum SoundDeviceType { "SPEAKER", "RECEIVER", "AUDIO_JACK", "BLUETOOTH", "HDMI", "MIRRORING", "USB_AUDIO", "MIC" };

Since: 2.3.1

The possible types are:

  • SPEAKER - For sound output using the built-in device speaker
  • RECEIVER - For sound output using the built-in device receiver
  • AUDIO_JACK - For sound input and/or output using the device audio jack which can be connected to a wired accessory such as a headset or headphone
  • BLUETOOTH - For sound input and/or output through a device that is connected by Bluetooth
  • HDMI - For sound output through a device that is connected by HDMI
  • MIRRORING - For sound output through a device that is connected by mirroring
  • USB_AUDIO - For sound output through a device that is connected by USB
  • MIC - For sound input using the built-in device microphone

1.4. SoundIOType

Sound device I/O type 
  enum SoundIOType { "IN", "OUT", "BOTH" };

Since: 2.3.1

The possible types are:

  • IN - For sound device type which only support input
  • OUT - For sound device type which only support output
  • BOTH - For sound device type which supports both input and output

2. Interfaces

2.1. SoundManagerObject

The SoundManagerObject interface defines what is instantiated in the tizen object. 
  [NoInterfaceObject] interface SoundManagerObject {
    readonly attribute SoundManager sound;
  };
  Tizen implements SoundManagerObject;

Since: 2.3

There is a tizen.sound object that allows accessing the functionality of the Sound API.

Attributes

  • readonly SoundManager sound
    Object representing a sound manager.

    Since: 2.3

2.2. SoundManager

The SoundManager interface provides the functionalities to control the volume level. 
  [NoInterfaceObject] interface SoundManager {
    SoundModeType getSoundMode() raises(WebAPIException);
    void setVolume(SoundType type, double volume) raises(WebAPIException);
    double getVolume(SoundType type) raises(WebAPIException);
    void setSoundModeChangeListener(SoundModeChangeCallback callback) raises(WebAPIException);
    void unsetSoundModeChangeListener() raises(WebAPIException);
    void setVolumeChangeListener(SoundVolumeChangeCallback callback) raises(WebAPIException);
    void unsetVolumeChangeListener() raises(WebAPIException);
    SoundDeviceInfo[] getConnectedDeviceList() raises(WebAPIException);
    SoundDeviceInfo[] getActivatedDeviceList() raises(WebAPIException);
    long addDeviceStateChangeListener(SoundDeviceStateChangeCallback callback) raises(WebAPIException);
    void removeDeviceStateChangeListener(long id) raises(WebAPIException);
  };

Since: 2.3

Methods

getSoundMode
Gets the current sound mode. 
SoundModeType getSoundMode();

Since: 2.3

Return value:

    SoundModeType: The current sound mode.

Exceptions:

  • WebAPIException

    • with error type UnknownError in any error case.

setVolume
Sets the volume level for a specified sound type. 
void setVolume(SoundType type, double volume);

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/volume.set

Parameters:

  • type: The sound type.
  • volume: The volume level to set
    The level ranges from 0 to 1.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if the given type is not supported. (e.g. when VOICE type is given on a Tizen wearable device).

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

    • 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.

    • with error type UnknownError in any other error case.

getVolume
Gets the current volume level for a specified sound type. 
double getVolume(SoundType type);

Since: 2.3

Parameters:

  • type: The sound type.

Return value:

    double: The current volume level.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if the given type is not supported.

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

    • with error type UnknownError in any other error case.

setSoundModeChangeListener
Registers a listener to be called when the sound mode is changed. 
void setSoundModeChangeListener(SoundModeChangeCallback callback);

Since: 2.3

Parameters:

  • callback: Callback method to be invoked when the sound mode is changed.

Exceptions:

  • WebAPIException

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

    • with error type UnknownError in any other error case.

unsetSoundModeChangeListener
Unsubscribes from receiving notification about the sound mode change. 
void unsetSoundModeChangeListener();

Since: 2.3

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

Exceptions:

  • WebAPIException

    • with error type UnknownError in any error case.

setVolumeChangeListener
Registers a listener to be called when the volume level is changed. 
void setVolumeChangeListener(SoundVolumeChangeCallback callback);

Since: 2.3

Parameters:

  • callback: Callback method to be invoked when the volume level is changed.

Exceptions:

  • WebAPIException

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

    • with error type UnknownError in any other error case.

unsetVolumeChangeListener
Unsubscribes from receiving notification when the volume level is changed. 
void unsetVolumeChangeListener();

Since: 2.3

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

Exceptions:

  • WebAPIException

    • with error type UnknownError in any other error case.

getConnectedDeviceList
Gets a list of connected sound devices. 
SoundDeviceInfo[] getConnectedDeviceList();

Since: 2.3.1

Return value:

    SoundDeviceInfo[]: List of connected sound devices.

Exceptions:

  • WebAPIException

    • with error type UnknownError in any other error case.

Code example:

var infoArr = tizen.sound.getConnectedDeviceList();

for (var i = 0; i < infoArr.length; i++)
{
  console.log(infoArr[i].device);
}
getActivatedDeviceList
Gets a list of activated sound devices.

Deprecated. Deprecated since 8.0. 'Activated' concept is deprecated and replaced with 'running'. Use SoundManager::getConnectedDeviceList and check isRunning property to get running devices. 

SoundDeviceInfo[] getActivatedDeviceList();

Since: 2.3.1

Return value:

    SoundDeviceInfo[]: List of activated sound devices.

Exceptions:

  • WebAPIException

    • with error type UnknownError in any other error case.

Code example:

var infoArr = tizen.sound.getActivatedDeviceList();

for (var i = 0; i < infoArr.length; i++)
{
  console.log(infoArr[i].device);
}
addDeviceStateChangeListener
Registers a listener that is to be called when the sound device state is changed. 
long addDeviceStateChangeListener(SoundDeviceStateChangeCallback callback);

Since: 2.3.1

There are the following types of device state changes:

  • Connectivity: When a device changes from being connected to being disconnected or from being disconnected to being connected.
  • Activation: When a device changes from being activated to being deactivated or from being deactivated to being activated.
  • Running: When a device changes from being stopped to being running or from being running to being stopped.

Parameters:

  • callback: Callback method to be invoked when the sound device state is changed.

Return value:

    long: ID of the listener that can be used to remove the listener later.

Exceptions:

  • WebAPIException

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

    • with error type UnknownError in any other error case.

Code example:

/* Callback. */
var onChanged = function(info)
{
  /* Some code to execute when a sound device state is changed. */
  if (info.isConnected)
  {
    /* Some code to execute if the device is connected. */
    console.log(info.device + " is connected");
  }
  else
  {
    /* Some code to execute if the device is not connected. */
    console.log(info.device + " is not connected");
  }
  if (info.isRunning)
  {
    /* Some code to execute if the device is running. */
    console.log(info.device + " is running");
  }
  else
  {
    /* Some code to execute if the device is not running. */
    console.log(info.device + " is not running");
  }
};

var id = tizen.sound.addDeviceStateChangeListener(onChanged);
removeDeviceStateChangeListener
Unsubscribes from receiving notifications when the sound device state is changed. 
void removeDeviceStateChangeListener(long id);

Since: 2.3.1

Parameters:

  • id: An ID that identifies the listener.

Exceptions:

  • WebAPIException

    • with error type UnknownError in any error case.

Code example:

/* Listener should be registered previously. */
tizen.sound.removeDeviceStateChangeListener(id);

2.3. SoundDeviceInfo

The SoundDeviceInfo interface specifies the information about a sound device. 
  [NoInterfaceObject] interface SoundDeviceInfo {
    readonly attribute long id;
    readonly attribute DOMString name;
    readonly attribute SoundDeviceType device;
    readonly attribute SoundIOType direction;
    readonly attribute boolean isConnected;
    readonly attribute boolean isActivated;
    readonly attribute boolean isRunning;
  };

Since: 2.3.1

Attributes

  • readonly long id
    The sound device ID

    Since: 2.3.1

  • readonly DOMString name
    The sound device name

    Since: 2.3.1

  • readonly SoundDeviceType device
    The sound device type

    Since: 2.3.1

  • readonly SoundIOType direction
    The sound device I/O type

    Since: 2.3.1

  • readonly boolean isConnected
    True if the sound device state is connected

    Since: 2.3.1

  • readonly boolean isActivated
    True if the sound device state is activated

    Deprecated. Deprecated since 8.0. Instead, use SoundDeviceInfo::isRunning.

    Since: 2.3.1

  • readonly boolean isRunning
    True if the sound device state is running. Device is considered as in 'running' state, when at least one stream actually goes out or into the device.

    Since: 8.0

2.4. SoundModeChangeCallback

The SoundModeChangeCallback interface specifies a mode change callback for getting notified about the sound mode changes. 
  [Callback=FunctionOnly, NoInterfaceObject] interface SoundModeChangeCallback {
    void onsuccess(SoundModeType mode);
  };

Since: 2.3

Methods

onsuccess
Called when the sound mode has changed. 
void onsuccess(SoundModeType mode);

Since: 2.3

Parameters:

  • mode: Sound mode.

2.5. SoundVolumeChangeCallback

The SoundVolumeChangeCallback interface specifies a volume change callback for getting notified about the volume changes. 
  [Callback=FunctionOnly, NoInterfaceObject] interface SoundVolumeChangeCallback {
    void onsuccess(SoundType type, double volume);
  };

Since: 2.3

Methods

onsuccess
Called when the volume level has changed. 
void onsuccess(SoundType type, double volume);

Since: 2.3

Parameters:

  • type: Sound type.
  • volume: New volume level.

2.6. SoundDeviceStateChangeCallback

The SoundDeviceStateChangeCallback interface specifies a sound device type change callback for getting notified when the sound device state changes. 
  [Callback=FunctionOnly, NoInterfaceObject] interface SoundDeviceStateChangeCallback {
    void onchanged(SoundDeviceInfo info);
  };

Since: 2.3.1

Methods

onchanged
Method invoked when the sound device state changes. 
void onchanged(SoundDeviceInfo info);

Since: 2.3.1

Parameters:

  • info: The info to have changed.

3. Full WebIDL

module Sound {
  enum SoundType { "SYSTEM", "NOTIFICATION", "ALARM", "MEDIA", "VOICE", "RINGTONE" };
  enum SoundModeType { "SOUND", "VIBRATE", "MUTE" };
  enum SoundDeviceType { "SPEAKER", "RECEIVER", "AUDIO_JACK", "BLUETOOTH", "HDMI", "MIRRORING", "USB_AUDIO", "MIC" };
  enum SoundIOType { "IN", "OUT", "BOTH" };
  Tizen implements SoundManagerObject;
  [NoInterfaceObject] interface SoundManagerObject {
    readonly attribute SoundManager sound;
  };
  [NoInterfaceObject] interface SoundManager {
    SoundModeType getSoundMode() raises(WebAPIException);
    void setVolume(SoundType type, double volume) raises(WebAPIException);
    double getVolume(SoundType type) raises(WebAPIException);
    void setSoundModeChangeListener(SoundModeChangeCallback callback) raises(WebAPIException);
    void unsetSoundModeChangeListener() raises(WebAPIException);
    void setVolumeChangeListener(SoundVolumeChangeCallback callback) raises(WebAPIException);
    void unsetVolumeChangeListener() raises(WebAPIException);
    SoundDeviceInfo[] getConnectedDeviceList() raises(WebAPIException);
    long addDeviceStateChangeListener(SoundDeviceStateChangeCallback callback) raises(WebAPIException);
    void removeDeviceStateChangeListener(long id) raises(WebAPIException);
  };
  [NoInterfaceObject] interface SoundDeviceInfo {
    readonly attribute long id;
    readonly attribute DOMString name;
    readonly attribute SoundDeviceType device;
    readonly attribute SoundIOType direction;
    readonly attribute boolean isConnected;
    readonly attribute boolean isRunning;
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface SoundModeChangeCallback {
    void onsuccess(SoundModeType mode);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface SoundVolumeChangeCallback {
    void onsuccess(SoundType type, double volume);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface SoundDeviceStateChangeCallback {
    void onchanged(SoundDeviceInfo info);
  };
};
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.