Samsung Electronics logo

Samsung Web API: AudioControl


Introduction

This API provides the audio control features (such as volume and mute) on the TV associated device.

There will be a webapis.audiocontrol object that allows accessing the functionality of the audiocontrol API.

For more information on the Audio Control features, see Audio Control Guide.


Table of Contents


Summary of Interfaces and Methods

Interface Method
WebAPIsAudioControlManager
AudioControlManager boolean setMute(boolean mute)
boolean getMute()
unsigned short getOutputMode()
boolean setVolume(unsigned short volume)
boolean setVolumeUp()
boolean setVolumeDown()
unsigned short getVolume()
void playSound(unsigned short soundType)

1. Interfaces

1.1. WebAPIsAudioControlManager

The AudioControl module supports the control of audio-related functions of the Smart TV platform.

    [NoInterfaceObject] interface WebAPIsAudioControlManager {
        readonly attribute AudioControlManager audiocontrol;
    };
    WebAPIs implements WebAPIsAudioControlManager;

A webapis.audiocontrol object provides access to the functionality of the TV Audio Control module.

1.2. AudioControlManager

The AudioControl interface that provides access to the TV audio API. This manager interface exposes the TV audio API to provide functionality for setting audio sources, volume, etc.

    [NoInterfaceObject] interface AudioControlManager {

        const short MODE_AUDIO_OUTPUT_PCM = 0;

        const short MODE_AUDIO_OUTPUT_DOLBY = 1;

        const short MODE_AUDIO_OUTPUT_DTS = 2;

        const short AUDIO_SOUND_TYPE_UP = 1;

        const short AUDIO_SOUND_TYPE_DOWN = 2;

        const short AUDIO_SOUND_TYPE_LEFT = 3;

        const short AUDIO_SOUND_TYPE_RIGHT = 4;

        const short AUDIO_SOUND_TYPE_PAGE_LEFT = 5;

        const short AUDIO_SOUND_TYPE_PAGE_RIGHT = 6;

        const short AUDIO_SOUND_TYPE_BACK = 7;

        const short AUDIO_SOUND_TYPE_SELECT = 8;

        const short AUDIO_SOUND_TYPE_CANCEL = 9;

        const short AUDIO_SOUND_TYPE_WARNING = 10;

        const short AUDIO_SOUND_TYPE_KEYPAD = 11;

        const short AUDIO_SOUND_TYPE_KEYPAD_ENTER = 12;

        const short AUDIO_SOUND_TYPE_KEYPAD_DEL = 13;

        const short AUDIO_SOUND_TYPE_SMARTCONTROL_MOVE = 14;

        const short AUDIO_SOUND_TYPE_SMARTCONTROL_SELECT = 15;

        const short AUDIO_SOUND_TYPE_MOVE = 16;

        const short AUDIO_SOUND_TYPE_PREPARING = 17;
  
        boolean setMute(boolean mute);
 
        boolean getMute();
 
        unsigned short getOutputMode();
 
        boolean setVolume(unsigned short volume);
        
        boolean setVolumeUp();
        
        boolean setVolumeDown();
 
        unsigned short getVolume();      
        
        void playSound(unsigned short soundType);       
    };

CONSTANTS

short MODE_AUDIO_OUTPUT_PCM

identifier for the PCM audio output mode

short MODE_AUDIO_OUTPUT_DOLBY

identifier for the DOLBY audio output mode

short MODE_AUDIO_OUTPUT_DTS

identifier for the DTS audio output mode

short AUDIO_SOUND_TYPE_UP

identifier for the UP sound

short AUDIO_SOUND_TYPE_DOWN

identifier for the DOWN sound

short AUDIO_SOUND_TYPE_LEFT

identifier for the LEFT sound

short AUDIO_SOUND_TYPE_RIGHT

identifier for the RIGHT sound

short AUDIO_SOUND_TYPE_PAGE_LEFT

identifier for the PAGE LEFT sound

short AUDIO_SOUND_TYPE_PAGE_RIGHT

identifier for the PAGE RIGHT sound

short AUDIO_SOUND_TYPE_BACK

identifier for the BACK sound

short AUDIO_SOUND_TYPE_SELECT

identifier for the SELECT sound

short AUDIO_SOUND_TYPE_CANCEL

identifier for the CANCEL sound

short AUDIO_SOUND_TYPE_WARNING

identifier for the WARNING sound

short AUDIO_SOUND_TYPE_KEYPAD

identifier for the KEYPAD sound

short AUDIO_SOUND_TYPE_KEYPAD_ENTER

identifier for the KEYPAD ENTER sound

short AUDIO_SOUND_TYPE_KEYPAD_DEL

identifier for the KEYPAD DEL sound

short AUDIO_SOUND_TYPE_SMARTCONTROL_MOVE

identifier for the SMART CONTROL MOVE sound

short AUDIO_SOUND_TYPE_SMARTCONTROL_SELECT

identifier for the SMART CONTROL SELECT sound

short AUDIO_SOUND_TYPE_MOVE

identifier for the MOVE sound

short AUDIO_SOUND_TYPE_PREPARING

identifier for the PREPARING sound

METHODS

setMute

Sets the muting state of the audio device.

Signature
boolean setMute(boolean mute);
Parameters
  • mute
    • Optional: No.
    • Nullable: No.
    • Type: boolean.
    • Description: true = mute, false = unmute
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError, In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 webapis.audiocontrol.setMute(true);
 

getMute

Gets the muting state of the audio device.

Signature
boolean getMute();
Return value
true if the system muted, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError, In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 try {
     if (webapis.audiocontrol.getMute()) {
         console.log("tv is on mute");
     } else {
         console.log("tv is not on mute");
     }
 } catch (error) {
     console.log(error.name);
 }
 

getOutputMode

Gets the current audio output mode (PCM, DOLBY, DTS, ..)

Signature
unsigned short getOutputMode();
Return value
Output mode if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError, In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 try {
     var output = webapis.audiocontrol.getOutputMode();
     switch(output) {
         case webapis.audiocontrol.MODE_AUDIO_OUTPUT_PCM : 
             console.log("audio mode is PCM");
             break;
         case webapis.audiocontrol.MODE_AUDIO_OUTPUT_DOLBY : 
             console.log("audio mode is DOLBY");
             break;
         case webapis.audiocontrol.MODE_AUDIO_OUTPUT_DTS : 
             console.log("audio mode is DTS");
             break;
     } 
 } catch (error) {
     console.log(error.name);
 }
 

setVolume

Sets the volume level on Smart TV system. The volume range is 0 ~ 100.

Signature
boolean setVolume(unsigned short volume);
Parameters
  • volume
    • Optional: No.
    • Nullable: No.
    • Type: unsigned short.
    • Description: Numeric volume level (0 ~ 100)
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 var volume = 10;
 try {
     if (webapis.audiocontrol.setVolume(volume)) {
         console.log("Volume is " + volume);
     }
 } catch (error) {
     console.log(error.name);
 }
 

setVolumeUp

Raises the volume level up on the Smart TV system. The volume range is 0 ~ 100. If setVolumeUp() is invoked when the volume is 100, it will be ignored.

Signature
boolean setVolumeUp();
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 try {
     if (webapis.audiocontrol.setVolumeUp()) {
         console.log("Volume is up");
     }
 } catch (error) {
     console.log(error.name);
 }
 

setVolumeDown

Lowers the volume level on the Smart TV system. The volumn range is 0 ~ 100. If setVolumeDown() is invoked when volume is 0, it will be ignored.

Signature
boolean setVolumeDown();
Return value
true if the operation is successful, otherwise false.
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 try {
     if (webapis.audiocontrol.setVolumeDown()) {
         console.log("Volume is down");
     }
 } catch (error) {
     console.log(error.name);
 }
 

getVolume

Gets the volume level from the Smart TV system. The volumn range is 0 ~ 100.

Signature
unsigned short getVolume();
Return value
unsigned short audio volume level (0 ~ 100)
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

Code example
 try {
     var volume = webapis.audiocontrol.getVolume();
     console.log("Volume is " + volume);
 } catch (error) {
     console.log(error.name);
 }
 

playSound

Plays a specific beep sound

Signature
void playSound(unsigned short soundType);
Parameters
  • soundType
    • Optional: No.
    • Nullable: No.
    • Type: unsigned short.
    • Description: beep sound type which will be played
Exceptions
  • WebAPIException:

    with error type UnknownError In the case of any other error.

    with error type NotSupportedError if the feature is not supported.

    with error type SecurityError if this functionality is not allowed.

    with error type InvalidValuesError if the input attributes do not contain a valid value

    with error type TypeMismatchError if any of the input attributes are of the wrong type

Code example
 try {
     webapis.audiocontrol.playSound(webapis.audiocontrol.AUDIO_SOUND_TYPE_UP);
 } catch (error) {
     console.log(error.name);
 }
 

2. Full WebIDL

module AudioControl {
 
    [NoInterfaceObject] interface WebAPIsAudioControlManager {
        readonly attribute AudioControlManager audiocontrol;
    };
    WebAPIs implements WebAPIsAudioControlManager;

    [NoInterfaceObject] interface AudioControlManager {

        const short MODE_AUDIO_OUTPUT_PCM = 0;

        const short MODE_AUDIO_OUTPUT_DOLBY = 1;

        const short MODE_AUDIO_OUTPUT_DTS = 2;

        const short AUDIO_SOUND_TYPE_UP = 1;

        const short AUDIO_SOUND_TYPE_DOWN = 2;

        const short AUDIO_SOUND_TYPE_LEFT = 3;

        const short AUDIO_SOUND_TYPE_RIGHT = 4;

        const short AUDIO_SOUND_TYPE_PAGE_LEFT = 5;

        const short AUDIO_SOUND_TYPE_PAGE_RIGHT = 6;

        const short AUDIO_SOUND_TYPE_BACK = 7;

        const short AUDIO_SOUND_TYPE_SELECT = 8;

        const short AUDIO_SOUND_TYPE_CANCEL = 9;

        const short AUDIO_SOUND_TYPE_WARNING = 10;

        const short AUDIO_SOUND_TYPE_KEYPAD = 11;

        const short AUDIO_SOUND_TYPE_KEYPAD_ENTER = 12;

        const short AUDIO_SOUND_TYPE_KEYPAD_DEL = 13;

        const short AUDIO_SOUND_TYPE_SMARTCONTROL_MOVE = 14;

        const short AUDIO_SOUND_TYPE_SMARTCONTROL_SELECT = 15;

        const short AUDIO_SOUND_TYPE_MOVE = 16;

        const short AUDIO_SOUND_TYPE_PREPARING = 17;
  
        boolean setMute(boolean mute);
 
        boolean getMute();
 
        unsigned short getOutputMode();
 
        boolean setVolume(unsigned short volume);
        
        boolean setVolumeUp();
        
        boolean setVolumeDown();
 
        unsigned short getVolume();      
        
        void playSound(unsigned short soundType);       
    };    
};