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.

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);       
    };    
};

Samsung Web API: AudioControl

Introduction

Table of Contents

Summary of Interfaces and Methods

1. Interfaces

1.1. WebAPIsAudioControlManager

1.2. AudioControlManager

CONSTANTS

METHODS

Signature

Parameters

Return value

Exceptions

Code example

Signature

Return value

Exceptions

Code example

Signature

Return value

Exceptions

Code example

Signature

Parameters

Return value

Exceptions

Code example

Signature

Return value

Exceptions

Code example

Signature

Return value

Exceptions

Code example

Signature

Return value

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

2. Full WebIDL