IVI/AudioSystemAPI

From Tizen Wiki
< IVI
Jump to: navigation, search

Contents

The audio system API

Authors:

  • Tanu Kaskinen <tanu.kaskinen@linux.intel.com>
  • Jaska Uimonen <jaska.uimonen@intel.com>
  • Amarnath Valluri <amarnath.valluri@intel.com>


Full IDL

interface AudioSystemObject {
    readonly attribute AudioSystem audiosystem;
};

Tizen implements AudioSystemObject;

callback AudioSystemSuccessCallback = void (AudioSystemContext context);

interface AudioSystem : EventTarget {
    void connect(AudioSystemSuccessCallback success_callback, optional ErrorCallback? error_callback);
    void disconnect();

    attribute EventHandler ondisconnected;
};

interface AudioSystemContext : EventTarget {
    readonly attribute VolumeControl[] volume_controls;
    readonly attribute VolumeControl? main_output_volume_control;
    readonly attribute VolumeControl? main_input_volume_control;
    readonly attribute MuteControl[] mute_controls;
    readonly attribute MuteControl? main_output_mute_control;
    readonly attribute MuteControl? main_input_mute_control;
    readonly attribute AudioDevice[] devices;
    readonly attribute AudioStream[] streams;
    readonly attribute AudioGroup[] audio_groups;

    attribute EventHandler onsync;
    attribute EventHandler onvolumecontroladded;
    attribute EventHandler onvolumecontrolremoved;
    attribute EventHandler onmainoutputvolumecontrolchanged;
    attribute EventHandler onmaininputvolumecontrolchanged;
    attribute EventHandler onmutecontroladded;
    attribute EventHandler onmutecontrolremoved;
    attribute EventHandler onmainoutputmutecontrolchanged;
    attribute EventHandler onmaininputmutecontrolchanged;
    attribute EventHandler ondeviceadded;
    attribute EventHandler ondeviceremoved;
    attribute EventHandler onstreamadded;
    attribute EventHandler onstreamremoved;
    attribute EventHandler onaudiogroupadded;
    attribute EventHandler onaudiogroupremoved;
};

interface VolumeControl : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString label;
    readonly attribute double volume;
    readonly attribute double[]? volume_steps;
    readonly attribute ChannelBalance[] balance;

    attribute EventHandler onlabelchanged;
    attribute EventHandler onvolumechanged;
    attribute EventHandler onvolumestepschanged;
    attribute EventHandler onbalancechanged;

    void set_volume(double volume, optional SuccessCallback? success_callback,
                    optional ErrorCallback? error_callback);
    void set_balance(double[] balance,
                     optional SuccessCallback? success_callback,
                     optional ErrorCallback? error_callback);
    void set_simplified_balance(SimplifiedBalance balance,
                                optional SuccessCallback? success_callback,
                                optional ErrorCallback? error_callback);
    SimplifiedBalance get_simplified_balance();
};

interface MuteControl : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString label;
    readonly attribute boolean muted;

    attribute EventHandler onlabelchanged;
    attribute EventHandler onmutedchanged;

    void set_muted(boolean muted, optional SuccessCallback? success_callback,
                   optional ErrorCallback? error_callback);
};

interface AudioDevice : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString label;
    readonly attribute Direction direction;
    readonly attribute DOMString[] device_types;
    readonly attribute VolumeControl? volume_control;
    readonly attribute MuteControl? mute_control;

    attribute EventHandler onlabelchanged;
    attribute EventHandler ondevicetypeschanged;
    attribute EventHandler onvolumecontrolchanged;
    attribute EventHandler onmutecontrolchanged;
};

interface AudioStream : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString label;
    readonly attribute Direction direction;
    readonly attribute VolumeControl? volume_control;
    readonly attribute MuteControl? mute_control;

    attribute EventHandler onlabelchanged;
    attribute EventHandler onvolumecontrolchanged;
    attribute EventHandler onmutecontrolchanged;
};

interface AudioGroup : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString name;
    readonly attribute DOMString label;
    readonly attribute VolumeControl? volume_control;
    readonly attribute MuteControl? mute_control;

    attribute EventHandler onlabelchanged;
    attribute EventHandler onvolumecontrolchanged;
    attribute EventHandler onmutecontrolchanged;
};

dictionary ChannelBalance {
	ChannelPosition position;
        DOMString label;
        double balance;
};

enumeration ChannelPosition {
    "unspecified",
    "front_left",
    "front_right",
    "front_center",
    "side_left",
    "side_right",
    "back_left",
    "back_right",
    "back_center",
    "front_left_of_center",
    "front_right_of_center",
    "left_height",
    "right_height"
};

dictionary SimplifiedBalance {
    double balance;
    double fade;
};

enumeration Direction {
    "input",
    "output",
    "bidirectional"
};

interface DisconnectedEvent : Event {
};

interface AudioSystemContextSyncEvent : Event {
};

interface VolumeControlAddedEvent : Event {
    readonly attribute VolumeControl control;
};

interface VolumeControlRemovedEvent : Event {
    readonly attribute VolumeControl control;
};

interface MainOutputVolumeControlChangedEvent : Event {
};

interface MainInputVolumeControlChangedEvent : Event {
};

interface MuteControlAddedEvent : Event {
    readonly attribute MuteControl control;
};

interface MuteControlRemovedEvent : Event {
    readonly attribute MuteControl control;
};

interface MainOutputMuteControlChangedEvent : Event {
};

interface MainInputMuteControlChangedEvent : Event {
};

interface DeviceAddedEvent : Event {
    readonly attribute AudioDevice device;
};

interface DeviceRemovedEvent : Event {
    readonly attribute AudioDevice device;
};

interface StreamAddedEvent : Event {
    readonly attribute AudioStream stream;
};

interface StreamRemovedEvent : Event {
    readonly attribute AudioStream stream;
};

interface AudioGroupAddedEvent : Event {
    readonly attribute AudioGroup group;
};

interface AudioGroupRemovedEvent : Event {
    readonly attribute AudioGroup group;
};

interface LabelChangedEvent : Event {
};

interface VolumeChangedEvent : Event {
};

interface VolumeStepsChangedEvent : Event {
};

interface BalanceChangedEvent : Event {
    boolean channel_positions_changed;
    boolean balance_values_changed;
};

interface MutedChangedEvent : Event {
};

interface VolumeControlChangedEvent : Event {
};

interface MuteControlChangedEvent : Event {
};

interface DeviceTypesChangedEvent : Event {
};


Related specifications

The callbacks of asynchronous operations use the SuccessCallback and ErrorCallback, which are defined in the Tizen interface: https://developer.tizen.org/dev-guide/2.3.0/org.tizen.mobile.web.device.apireference/tizen/tizen.html


Supported volume models

The goal of the this design is to support many different volume models (ideally all sensible ones). The flexibility is achieved by having independent volume control (and mute control) objects, and by making no assumptions what those volume controls are associated with. The audio system implementation decides the model, that is, decides what volume controls exist and how they are associated with other objects such as devices and streams. Applications have to adapt to the model imposed by the audio system. The different models described below aren't necessarily mutually exclusive, so the audio system can support multiple models.


Individual device and stream volumes

An application may want to present the audio system to the user as a list of devices and streams, and show volume controls separately for each device and stream. If the audio system wants to support such applications, it can create AudioDevice and AudioStream objects and associate each of them with a VolumeControl object.

If the audio system doesn't want to expose the device and stream volumes to the user, it can choose to not create any AudioDevice or AudioStream objects, or it can create them but use null references for the volume controls.


Single main volume

The audio system may want to have only one user-controllable volume control in the system, which may control different things (e.g. different devices) depending on the context. In that case it can set the main_output_volume_control and/or main_input_volume_control attributes of the AudioSystemContext object.

It's also possible to have a main volume control while having more fine-grained controls at the same time. For example, it's common for desktop user interfaces to have an easily accessible "volume applet" and also a separate application for fine-grained volume control. The volume applet typically shows only a single volume control, which usually controls the "current device" (whatever that means), and the separate volume application allows individual control of the device and stream volumes.


Stream group volume

Instead of (or in addition to) individual volumes for every stream, the audio system may want to define stream groups such as "music", "phone call audio", "alarm" and so on. Every stream in a stream group is then associated with a single volume control that affects all streams in the group. To make it possible for applications to enumerate the groups in the system and present them to the user, the audio system can create AudioGroup objects and associate them with a VolumeControl object.


Open questions

Headsets are represented with two separate AudioDevice objects. It's currently not possible for applications to reliably figure out that the two AudioDevices are one physical object. Should we make that possible?

Should the asynchronous operations be cancellable? What's the usual web API convention?

One application may create multiple streams. Should we add an AudioApplication or AudioSystemClient interface to the API so that UIs could group streams based on the owning application?


The AudioSystemObject interface

This interface exists just as a hook to the Tizen interface. Applications only need to know that they can get to the AudioSystem object via window.tizen.audiosystem.

interface AudioSystemObject {
    readonly attribute AudioSystem audiosystem;
};

Tizen implements AudioSystemObject;


Attributes

audiosystem

The AudioSystem object.


The AudioSystem interface

Applications use the AudioSystem interface to connect to the platform's audio system, and to get notified of disconnection. The AudioSystem object is part of the application's Window object, accessible via window.tizen.audiosystem. Actual interaction with the audio system is done via the AudioSystemContext object, which can be accessed once the connect() method call has succeeded (the context object is passed to the success callback of connect()).

callback AudioSystemSuccessCallback = void (AudioSystemContext context);

interface AudioSystem : EventTarget {
    void connect(AudioSystemSuccessCallback success_callback, optional ErrorCallback? error_callback);
    void disconnect();

    attribute EventHandler ondisconnected;
};

Example:

// This example shows how to connect to the platform's audio system.

function connect_success(context) {
    console.log("Connected to the audio system.");
}

function connect_error(error) {
    console.log("Failed to connect to the audio system: " + error.message);
}

function disconnected(event) {
    console.log("Connection to the audio system lost.");
}

window.tizen.audiosystem.connect(connect_success, connect_error);
window.tizen.audiosystem.addEventListener("disconnected", disconnected);


Methods

connect()

Establishes a connection to the platform's audio system. This is an asynchronous operation. When the operation finishes, success_callback or error_callback is called depending on whether the operation succeeded or not.


disconnect()

Disconnects the application from the platform's audio system. If the application is already disconnected, this does nothing.


Events

"disconnected"

A DisconnectedEvent is dispatched when the connection to the audio system is lost.


The AudioSystemContext interface

The application interacts with the platform's audio system via the AudioSystemContext object. The context object can be acquired with AudioSystem's connect() method. When the AudioSystem disconnects, the AudioSystemContext object and the objects contained by it become non-functional.

interface AudioSystemContext : EventTarget {
    readonly attribute VolumeControl[] volume_controls;
    readonly attribute VolumeControl? main_output_volume_control;
    readonly attribute VolumeControl? main_input_volume_control;
    readonly attribute MuteControl[] mute_controls;
    readonly attribute MuteControl? main_output_mute_control;
    readonly attribute MuteControl? main_input_mute_control;
    readonly attribute AudioDevice[] devices;
    readonly attribute AudioStream[] streams;
    readonly attribute AudioGroup[] audio_groups;

    attribute EventHandler onsync;
    attribute EventHandler onvolumecontroladded;
    attribute EventHandler onvolumecontrolremoved;
    attribute EventHandler onmainoutputvolumecontrolchanged;
    attribute EventHandler onmaininputvolumecontrolchanged;
    attribute EventHandler onmutecontroladded;
    attribute EventHandler onmutecontrolremoved;
    attribute EventHandler onmainoutputmutecontrolchanged;
    attribute EventHandler onmaininputmutecontrolchanged;
    attribute EventHandler ondeviceadded;
    attribute EventHandler ondeviceremoved;
    attribute EventHandler onstreamadded;
    attribute EventHandler onstreamremoved;
    attribute EventHandler onaudiogroupadded;
    attribute EventHandler onaudiogroupremoved;
};


Attributes

volume_controls

An array of VolumeControl objects. The array contains all the volume controls that exist in the audio system. When the system creates new VolumeControl objects or removes existing ones, the "volume_control_added" and "volume_control_removed" events are dispatched on the AudioSystemContext.

Example:

// This example prints the list of VolumeControls in the AudioSystemContext
// every time the list changes.

function print_all_controls(context) {
    for (var i = 0; i < context.volume_controls.length; i++)
        console.log(context.volume_controls[i].label);
}

function added(event) {
    console.log("VolumeControl added: " + event.volume_control.label);
    print_all_controls(event.target);
}

function removed(event) {
    console.log("VolumeControl removed: " + event.volume_control.label);
    print_all_controls(event.target);
}

function connect_success(context) {
    console.log("Connected to the audio system.");
    print_all_controls(context);
    context.addEventListener("volume_control_added", added);
    context.addEventListener("volume_control_removed", removed);
}

window.tizen.audioosystem.connect(context_success, null);


main_output_volume_control

This is the VolumeControl object that is currently used as the "main" output volume control.

If the system has multiple outputs, it's not obvious what the "main" volume control should do - should it always control the default output, should it always control all outputs, or should it do the decision dynamically based on what outputs happen to be currently in use or other criteria. Despite this ambiguity, user interfaces often offer a single volume slider even if there are multiple outputs. This VolumeControl makes it easy to write such user interfaces, because the visible user interface component doesn't need to care about the logic of how to choose the appropriate output(s) to adjust. The platform implementation does the decision.

This may be null, if, for example, there are no output volume controls at all in the system, or if the platform implementation doesn't support this feature.

The VolumeControl object that is used as the main output volume control may change any time due to changes in connected hardware, user actions or some other reason. For example, if the platform implements this feature so that the main volume control controls the default output device volume, then this attribute will likely point to the VolumeControl object of the device, and if another device becomes the default, then this attribute will change to point to the VolumeControl object of the new default device. When this attribute changes value (meaning that a different VolumeControl object becomes the main volume control), the "main_output_volume_control_changed" event is dispatched on the AudioSystemContext.


main_input_volume_control

See main_output_volume_control.


mute_controls

An array of MuteControl objects. The array contains all the mute controls that exist in the audio system. When the system creates new MuteControl objects or removes existing ones, the "mute_control_added" and "mute_control_removed" events are dispatched on the AudioSystemContext.


main_output_mute_control

This is the MuteControl object that is currently used as the "main" output mute control.

This may be null, if, for example, there are no output mute controls at all in the system, or if the platform implementation doesn't support this feature.

The MuteControl object that is used as the main output mute control may change any time due to changes in connected hardware, user actions or some other reason. For example, if the platform implements this feature so that the main mute control controls the default output device mute state, then this attribute will likely point to the MuteControl object of the device, and if another device becomes the default, then this attribute will change to point to the MuteControl object of the new default device. When this attribute changes value (meaning that a different MuteControl object becomes the main mute control), the "main_output_mute_control_changed" event is dispatched on the AudioSystemContext.


main_input_mute_control

See main_output_mute_control.


devices

An array of AudioDevice objects. The array contains all the devices that exist in the audio system. When the system creates new AudioDevice objects or removes existing ones, the "device_added" and "device_removed" events are dispatched on the AudioSystemContext.


streams

An array of AudioStream objects. The array contains all the streams that exist in the audio system. When the system creates new AudioStream objects or removes existing ones, the "stream_added" and "stream_removed" events are dispatched on the AudioSystemContext.


audio_groups

An array of AudioGroup objects. The array contains all the audio groups that exist in the audio system. When the system creates new AudioGroup objects or removes existing ones, the "audio_group_added" and "audio_group_removed" events are dispatched on the AudioSystemContext.


Events

The application can get notifications of events concerning the AudioSystemContext by using the standard EventTarget interface, or the EventHandler attributes.


"sync"

An AudioSystemContextSyncEvent is dispatched after each "logical event" that happens in the audio system. One logical event may result in multiple events being sent to applications. A logical event is analogous to a transaction in database context: a database transaction can have multiple steps, and during the transaction the database may be in an inconsistent state, but applications never see those inconsistent states. To an application the database transactions appear to move the database atomically from one consistent state to another. A logical event is similar: when e.g. a USB sound card is attached to a system, the audio system will probably handle that as one logical event, but it will generate several smaller events like "device_added", "volume_control_added" and maybe "main_output_volume_control_changed". The "sync" event allows the audio system to mark the end of a logical event. At the time of a "sync" event the system is in a consistent state (for example, there are no references to removed objects).

The application can use the "sync" event, for example, to ensure that it doesn't do unnecessary updates to the UI. Let's assume that an application wants to show four lists of volume controls simultaneously: device volume controls, stream volume controls, audio group controls and in the last list volume controls that don't belong to any of the other lists. When a device is added to a system, a volume control for it is added too. In case the "volume_control_added" event is dispatched first, the application doesn't know yet that the volume control will be associated with a device. Without the "sync" event, the application might add the volume to the "other" list and redraw the user interface. Then, when the "device_added" event is processed very shortly afterwards, the application moves the volume control from the "other" list to the "devices" list and redraws the user interface again. This causes the volume control to have a short flash in the "other" list, which can annoy the user. If the application waits for the "sync" event before redrawing the user interface, there will be no annoying flicker.


"volume_control_added"

A VolumeControlAddedEvent is dispatched when a new VolumeControl object is added to the AudioSystemContext.


"volume_control_removed"

A VolumeControlRemovedEvent is dispatched when a VolumeControl object is removed from the AudioSystemContext.


"main_output_volume_control_changed"

A MainOutputVolumeControlChangedEvent is dispatched when the main_output_volume_control attribute of the AudioSystemContext changes. Note that this event is only dispatched when the current main volume control is replaced by another VolumeControl object (or when the attribute changes to null); this is not dispatched when merely an ordinary volume change occurs. For listening to volume change events, use the "volume_changed" event of VolumeControl.


"main_input_volume_control_changed"

A MainInputVolumeControlChangedEvent is dispatched when the main_input_volume_control attribute of the AudioSystemContext changes. Note that this event is only dispatched when the current main volume control is replaced by another VolumeControl object (or when the attribute changes to null); this is not dispatched when merely an ordinary volume change occurs. For listening to volume change events, use the "volume_changed" event of VolumeControl.


"mute_control_added"

A MuteControlAddedEvent is dispatched when a new MuteControl object is added to the AudioSystemContext.


"mute_control_removed"

A MuteControlRemovedEvent is dispatched when a MuteControl object is removed from the AudioSystemContext.


"main_output_mute_control_changed"

A MainOutputMuteControlChangedEvent is dispatched when the main_output_mute_control attribute of the AudioSystemContext changes. Note that this event is only dispatched when the current main mute control is replaced by another MuteControl object (or when the attribute changes to null); this is not dispatched when merely an ordinary mute state change occurs. For listening to mute state change events, use the "muted_changed" event of MuteControl.


"main_input_mute_control_changed"

A MainInputMuteControlChangedEvent is dispatched when the main_input_mute_control attribute of the AudioSystemContext changes. Note that this event is only dispatched when the current main mute control is replaced by another MuteControl object (or when the attribute changes to null); this is not dispatched when merely an ordinary mute state change occurs. For listening to mute state change events, use the "muted_changed" event of MuteControl.


"device_added"

A DeviceAddedEvent is dispatched when a new AudioDevice object is added to the AudioSystemContext.


"device_removed"

A DeviceRemovedEvent is dispatched when an AudioDevice object is removed from the AudioSystemContext.


"stream_added"

A StreamAddedEvent is dispatched when a new AudioStream object is added to the AudioSystemContext.


"stream_removed"

A StreamRemovedEvent is dispatched when an AudioStream object is removed from the AudioSystemContext.


"audio_group_added"

An AudioGroupAddedEvent is dispatched when a new AudioGroup object is added to the AudioSystemContext.


"audio_group_removed"

An AudioGroupRemovedEvent is dispatched when a AudioGroup object is removed from the AudioSystemContext.


The VolumeControl interface

The platform's audio system usually provides volume controls that applications can use to read and change the volumes in the system. Volume controls can be associated with devices and application streams, but also with more abstract things like stream groups (one volume control controlling the volume of multiple streams) or anything else that the platform wants.

VolumeControl objects don't themselves have the information about what entities they are associated with, because they may be associated with many kinds of entities, possibly simultaneously, so representing the relationships would probably result in a cumbersome API. If an application wants, for example, to answer the question "does this VolumeControl control an audio group", the application needs to iterate through all AudioGroup objects to see if any of them reference the VolumeControl object in question.

interface VolumeControl : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString label;
    readonly attribute double volume;
    readonly attribute double[]? volume_steps;
    readonly attribute ChannelBalance[] balance;

    attribute EventHandler onlabelchanged;
    attribute EventHandler onvolumechanged;
    attribute EventHandler onvolumestepschanged;
    attribute EventHandler onbalancechanged;

    void set_volume(double volume, optional SuccessCallback? success_callback,
                    optional ErrorCallback? error_callback);
    void set_balance(double[] balance,
                     optional SuccessCallback? success_callback,
                     optional ErrorCallback? error_callback);
    void set_simplified_balance(SimplifiedBalance balance,
                                optional SuccessCallback? success_callback,
                                optional ErrorCallback? error_callback);
    SimplifiedBalance get_simplified_balance();
};


Attributes

id

An identifier for a VolumeControl object. There can never be two VolumeControl objects with the same id belonging to the same AudioSystemContext object.


label

The human-readable description of the VolumeControl object, suitable to be shown in user interfaces. When the label changes, the "label_changed" event is dispatched on the VolumeControl.


volume

The overall volume. The normal range is from 0.0 (muted) to 1.0 (full volume). It's possible to use values higher than 1.0, but that can easily result in distorted audio. It's not actually guaranteed that 0.0 means muted, but it almost always does.

If an application provides a graphical volume control element in its user interface, the application should map the value of this attribute linearly to a position in the user interface element. This is because the application can not assume any particular curve for the volume function. The platform implementation is responsible for defining the curve so that the progression from 0.0 to 1.0 behaves in a user-friendly way. This also means that there's no way to reliably map the volume value to a dB value.

When the volume changes, the "volume_changed" event is dispatched on the VolumeControl.

The set_volume() method can be used to change the volume.


volume_steps

An array of possible volume values. Some volume controls don't support a continuous volume scale. Those volume controls can set this attribute so that applications know the granularity of the volume control. Volume controls that have a continuous scale should set this attribute to null.

For example, if the volume steps are [0.0, 0.5, 1.0], then the volume can only have three distinct values. An application can try to set the volume to 0.6, but the audio system is expected to round that to the nearest step, which in this example is 0.5.

When the volume steps change, the "volume_steps_changed" event is dispatched on the VolumeControl.


balance

An array of ChannelBalances, one for each channel.

When the balance changes, the "balance_changed" event is dispatched on the VolumeControl.

The set_balance() and set_simplified_balance() methods can be used to change the balance.

If an application wants to have only one balance slider for the left-right balance in its user interface, and possibly another slider for the front-back balance, the set_simplified_balance() and get_simplified_balance() methods can be used to convert between the full per-channel balance representation and the simplified representation.


Methods

set_volume()

Set the volume attribute of the VolumeControl. This is an asynchronous operation. When the operation finishes, success_callback or error_callback is called depending on whether the operation succeeded or not.


set_balance()

Set the balance of the VolumeControl. The new balance is passed as an array of doubles instead of an array of ChannelBalances, because applications can't change the channel positions, so positions would be redundant information.

This is an asynchronous operation. When the operation finishes, success_callback or error_callback is called depending on whether the operation succeeded or not.


set_simplified_balance()

Set the balance attribute of the VolumeControl. This is an asynchronous operation. When the operation finishes, success_callback or error_callback is called depending on whether the operation succeeded or not.

The difference to set_balance() is that instead of specifying the full per-channel balance, the balance parameter is a SimplifiedBalance. The SimplifiedBalance is mapped to a per-channel balance by the platform implementation, and the specifics of that mapping are implementation-defined.


get_simplified_balance()

Map the current balance attribute value to a SimplifiedBalance. The specifics of that mapping are implementation-defined.


Events

The application can get notifications of events concerning the VolumeControl by using the standard EventTarget interface, or the EventHandler attributes.


"label_changed"

A LabelChangedEvent is dispatched when the label attribute of a VolumeControl changes.


"volume_changed"

A VolumeChangedEvent is dispatched when the volume attribute of a VolumeControl changes.


"volume_steps_changed"

A VolumeStepsChangedEvent is dispatched when the volume_steps attribute of a VolumeControl changes.


"balance_changed"

A BalanceChangedEvent is dispatched when the balance attribute of a VolumeControl changes.


"channel_positions_changed"

A ChannelPositionsChangedEvent is dispatched when the channel_positions attribute of a VolumeControl changes.


The MuteControl interface

The platform's audio system usually provides mute controls that applications can use to read and change the mute states in the system. Mute controls can be associated with devices (hardware or virtual) and application streams, but also with more abstract things like stream groups (one mute control controlling the mute state of multiple streams) or anything else that the platform wants.

MuteControl objects don't themselves have the information about what entities they are associated with, because they may be associated with many kinds of entities, possibly simultaneously, so representing the relationships would probably result in a cumbersome API. If an application wants, for example, to answer the question "does this MuteControl control an audio group", the application needs to iterate through all AudioGroup objects to see if any of them reference the MuteControl object in question.

interface MuteControl : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString label;
    readonly attribute boolean muted;

    attribute EventHandler onlabelchanged;
    attribute EventHandler onmutedchanged;

    void set_muted(boolean muted, optional SuccessCallback? success_callback,
                   optional ErrorCallback? error_callback);
};


Attributes

id

An identifier for a MuteControl object. There can never be two MuteControl objects with the same id belonging to the same AudioSystemContext object.


label

The human-readable description of the MuteControl object, suitable to be shown in user interfaces. When the label changes, the "label_changed" event is dispatched on the MuteControl.


muted

The mute status. When the mute status changes, the "muted_changed" event is dispatched on the MuteControl.

The set_muted() method can be used to change the mute status.


Methods

set_muted()

Set the muted attribute of the MuteControl. This is an asynchronous operation. When the operation finishes, success_callback or error_callback is called depending on whether the operation succeeded or not.


Events

The application can get notifications of events concerning the MuteControl by using the standard EventTarget interface, or the EventHandler attributes.


"label_changed"

A LabelChangedEvent is dispatched when the label attribute of a MuteControl changes.


"muted_changed"

A VolumeChangedEvent is dispatched when the muted attribute of a MuteControl changes.


The AudioDevice interface

An AudioDevice object represents something "device-like". It's hard to come up with a clear definition for what is a "device"; here are some examples that might be represented by an AudioDevice object:

  • physical audio endpoints in the audio graph: speakers, microphones, headphones etc.
  • connectors: analog, S/PDIF, HDMI etc.
  • virtual devices: fake sound cards, multiple stereo devices combined into one logical surround device, a surround device split into multiple logical stereo devices etc.

An important property of AudioDevice objects is that they should represent a device that deals with only one audio stream (possibly with multiple channels). "Dealing with only one audio stream" doesn't mean that there can't be multiple application streams connected to an output AudioDevice, it means that the output AudioDevice must mix the application streams instead of maintaining the separation of the streams. For example, two speakers are one AudioDevice if the speakers are used in a stereo configuration, but if the two speakers are used independently as two mono outputs, then there should be two AudioDevice objects. It's also fine to model those two speakers as three AudioDevice objects: one stereo and two mono ones. Another example: a headset consists of two AudioDevices: one for output and one for the headset microphone.

The reason for limiting the AudioDevice concept to only one stream is to avoid unnecessary complexity: if one AudioDevice could handle multiple audio streams separately, it should then be possible to have multiple volume controls and mute controls for one AudioDevice, which would complicate things for applications. If there's need to group AudioDevice objects so that e.g. a headset could be handled as a single object, a separate grouping interface can be added later.

interface AudioDevice : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString label;
    readonly attribute Direction direction;
    readonly attribute DOMString[] device_types;
    readonly attribute VolumeControl? volume_control;
    readonly attribute MuteControl? mute_control;

    attribute EventHandler onlabelchanged;
    attribute EventHandler ondevicetypeschanged;
    attribute EventHandler onvolumecontrolchanged;
    attribute EventHandler onmutecontrolchanged;
};


Attributes

id

An identifier for an AudioDevice object. There can never be two AudioDevice objects with the same id belonging to the same AudioSystemContext object.


label

The human-readable description of the AudioDevice object, suitable to be shown in user interfaces. When the label changes, the "label_changed" event is dispatched on the AudioDevice.


direction

The device direction. Devices that receive audio from outside the audio system are input devices and devices that send audio out of the audio system are output devices. Platform implementations are recommended to not use the "bidirectional" value. If there's for example a simple physical effects box that has one input and one output, and the platform wants to expose that device to applications, it's better to model that as two AudioDevices (one for input and one for output).


device_types

A list of device types that describe what the AudioDevice object represents. Applications can use this information to show a device type dependent icon next to a volume slider, for example. The list may be empty (for example, the platform may not know the device type).

Typically only one type is needed, but supporting a list of types makes it easier to handle a situation where it turns out that some previously defined type should be split into multiple subtypes. In that situation the old type can be kept in the list to maintain compatibility with old applications that aren't aware of the new subtypes.

There are a few standard types documented here, but the platform may define custom types too (applications may not understand their meaning, however). The platform should prefix custom device types to avoid name conflicts in applications that aim to be cross-platform. The suggested prefixing convention is to use "x-" to denote a non-standard type, plus an additional vendor-specific prefix. Example: "x-foo-megaphone".

The currently defined standard device types:

  • "analog-input"
  • "analog-output"
  • "earpiece" (the sort of speaker that you put against your ear, commonly found in phones)
  • "hdmi-input"
  • "hdmi-output"
  • "headphones"
  • "headset-microphone"
  • "headset-output"
  • "microphone"
  • "spdif-input"
  • "spdif-output"
  • "speakers" (one or more loudspeakers)

The device types that describe a link type (analog, S/PDIF, HDMI) are meant to be used only when the AudioDevice object represents a link and not the final audio destination or original source that is connected via the link. For example, if the audio system has an AudioDevice object for speakers that are connected via S/PDIF, the AudioDevice object should not include "spdif-output" in its device types list, because the AudioDevice doesn't represent the S/PDIF link.

When the device types change, the "device_types_changed" event is dispatched on the AudioDevice.


volume_control

The volume control that is associated with this device. When this attribute changes value (meaning that a different VolumeControl object becomes associated with the device), the "volume_control_changed" event is dispatched on the AudioDevice.


mute_control

The mute control that is associated with this device. When this attribute changes value (meaning that a different MuteControl object becomes associated with the device), the "mute_control_changed" event is dispatched on the AudioDevice.


Events

The application can get notifications of events concerning the AudioDevice by using the standard EventTarget interface, or the EventHandler attributes.


"label_changed"

A LabelChangedEvent is dispatched when the label attribute of an AudioDevice changes.


"device_types_changed"

A DeviceTypesChangedEvent is dispatched when the device_types attribute of an AudioDevice changes.


"volume_control_changed"

A VolumeControlChangedEvent is dispatched when the volume_control attribute of an AudioDevice changes.


"mute_control_changed"

A MuteControlChangedEvent is dispatched when the mute_control attribute of an AudioDevice changes.


The AudioStream interface

When applications want to play back or record audio, they will create one or more streams in the audio system. AudioStream objects typically represent a streams created by an applications, but it's also possible that the audio system creates some kind of virtual AudioStreams too, which are not created by any application.

interface AudioStream : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString label;
    readonly attribute Direction direction;
    readonly attribute VolumeControl? volume_control;
    readonly attribute MuteControl? mute_control;

    attribute EventHandler onlabelchanged;
    attribute EventHandler onvolumecontrolchanged;
    attribute EventHandler onmutecontrolchanged;
};


Attributes

id

An identifier for an AudioStream object. There can never be two AudioStream objects with the same id belonging to the same AudioSystemContext object.


label

The human-readable description of the AudioStream object, suitable to be shown in user interfaces. When the label changes, the "label_changed" event is dispatched on the AudioStream.


direction

The stream direction. Streams that are used for playback are output streams and streams that are used for recording are input streams. Streams can't be bidirectional.


volume_control

The volume control that is associated with this stream. When this attribute changes value (meaning that a different VolumeControl object becomes associated with the stream), the "volume_control_changed" event is dispatched on the AudioStream.


mute_control

The mute control that is associated with this stream. When this attribute changes value (meaning that a different MuteControl object becomes associated with the stream), the "mute_control_changed" event is dispatched on the AudioStream.


Events

The application can get notifications of events concerning the AudioStream by using the standard EventTarget interface, or the EventHandler attributes.


"label_changed"

A LabelChangedEvent is dispatched when the label attribute of an AudioStream changes.


"volume_control_changed"

A VolumeControlChangedEvent is dispatched when the volume_control attribute of an AudioStream changes.


"mute_control_changed"

A MuteControlChangedEvent is dispatched when the mute_control attribute of an AudioStream changes.


The AudioGroup interface

An audio group allows the platform to communicate to applications how the platform groups things (mainly streams). For example, the platform may define a music group that is associated with a volume control, and all music streams will then share the same volume control. Applications can get a list of all audio groups in the system, or they can look for a specific audio group with certain semantics. The semantics, such as "the group for music streams", are platform-defined, so applications that want to access an audio group with certain semantics will have to refer to the platform documentation. Some standardization may happen in the future.

interface AudioGroup : EventTarget {
    readonly attribute long id;
    readonly attribute DOMString name;
    readonly attribute DOMString label;
    readonly attribute VolumeControl? volume_control;
    readonly attribute MuteControl? mute_control;

    attribute EventHandler onlabelchanged;
    attribute EventHandler onvolumecontrolchanged;
    attribute EventHandler onmutecontrolchanged;
};


Attributes

id

An identifier for an AudioGroup object. There can never be two AudioGroup objects with the same id belonging to the same AudioSystemContext object.


name

Name for the audio group. There can't be two audio groups with the same name in the system at the same time.

The platform may associate names with specific semantics. For example, names "x-foo-music" and "x-foo-call" could refer to a music group and a call audio group, respectively. There are no standardized names at this point. The platform should prefix its names to avoid name conflicts in applications that aim to be cross-platform. The suggested prefixing convention is to use "x-" to denote a non-standard name, plus an additional vendor-specific prefix.


label

The human-readable description of the AudioGroup object, suitable to be shown in user interfaces. When the label changes, the "label_changed" event is dispatched on the AudioGroup.


volume_control

The volume control of the audio group. May be null, if the audio group isn't used for controlling volume, or if there are currently no suitable volume controls in the system.

The VolumeControl object that is associated with the audio group may change any time due to changes in connected hardware, user actions or some other reason. For example, the platform may use a different volume control for the music group depending on where music is currently routed. In this example, when music is routed to speakers, this attribute will point to the VolumeControl object representing the "speakers/music" volume control, and when headphones are plugged in, this attribute will change to point to the VolumeControl object representing the "headphones/music" volume control. When this attribute changes value (meaning that a different VolumeControl object becomes associated with the audio group), the "volume_control_changed" event is dispatched on the AudioGroup.


mute_control

The mute control of the audio group. May be null, if the audio group isn't used for controlling muting, or if there are currently no suitable mute controls in the system.

The MuteControl object that is associated with the audio group may change any time due to changes in connected hardware, user actions or some other reason. For example, the platform may use a different mute control for the music group depending on where music is currently routed. In this example, when music is routed to speakers, this attribute will point to the MuteControl object representing the "speakers/music" mute control, and when headphones are plugged in, this attribute will change to point to the MuteControl object representing the "headphones/music" mute control. When this attribute changes value (meaning that a different MuteControl object becomes associated with the audio group), the "mute_control_changed" event is dispatched on the AudioGroup.


Events

The application can get notifications of events concerning the AudioGroup by using the standard EventTarget interface, or the EventHandler attributes.


"label_changed"

A LabelChangedEvent is dispatched when the label attribute of an AudioGroup changes.


"volume_control_changed"

A VolumeControlChangedEvent is dispatched when the volume_control attribute of an AudioGroup changes.


"mute_control_changed"

A MuteControlChangedEvent is dispatched when the mute_control attribute of an AudioGroup changes.


The ChannelBalance Dictionary

dictionary ChannelBalance {
	ChannelPosition position;
        DOMString label;
        double balance;
};


Members

position

The position of this channel.


label

A user-friendly (possibly localized) label that describes the channel position. The label could be shown in per-channel volume controls, for example. Applications may want to treat the "unspecified" position specially: for example, if a volume control has two channels and both have unspecified position, it may be better to use "Channel 1" and "Channel 2" as the labels, instead of labeling both channels with the default "Unspecified".


balance

The balance of this channel. The valid range is from 0.0 (channel muted) to 1.0 (full volume). It's not actually guaranteed that 0.0 means muted, but it almost always does.

If an application provides a separate graphical balance control element for each channel in its user interface, the application should map the balance value linearly to positions in the user interface element. This is because the application can not assume any particular curve for the function that maps the balance value to a volume multiplication factor. The platform implementation is responsible for defining the curve so that the progression from 0.0 to 1.0 behaves in a user-friendly way. This also means that there's no way to reliably map the balance value to a dB value.


The ChannelPosition enumeration

This enumeration lists all "standard" channel positions. The special "unspecified" position is useful when the audio content of a channel doesn't really correspond to any of the standard positions, like in the case of mono audio or a 4-channel microphone array.

The source for this particular set of channels is [1]. More channels may be added to the enumeration in the future, if necessary.

enumeration ChannelPosition {
    "unspecified",
    "front_left",
    "front_right",
    "front_center",
    "side_left",
    "side_right",
    "back_left",
    "back_right",
    "back_center",
    "front_left_of_center",
    "front_right_of_center",
    "left_height",
    "right_height"
};


The SimplifiedBalance dictionary

dictionary SimplifiedBalance {
    double balance;
    double fade;
};


Members

balance

The left-right balance, expressed with a value between -1.0 (leftmost panning) and 1.0 (rightmost panning). 0.0 means equal volume for left and right channels.


fade

The front-back balance, expressed with a value between -1.0 (backmost panning) and 1.0 (frontmost panning). 0.0 means equal volume for front and back channels.


The Direction enumeration

enumeration Direction {

   "input",
   "output",
   "bidirectional"

};


The DisconnectedEvent interface

interface DisconnectedEvent : Event {
};


The AudioSystemContextSyncEvent interface

interface AudioSystemContextSyncEvent : Event {
};


The VolumeControlAddedEvent interface

interface VolumeControlAddedEvent : Event {
    readonly attribute VolumeControl control;
};


Attributes

control

The VolumeControl object that was added to the AudioSystemContext.


The VolumeControlRemovedEvent interface

interface VolumeControlRemovedEvent : Event {
    readonly attribute VolumeControl control;
};


Attributes

control

The VolumeControl object that was removed from the AudioSystemContext.


The MainOutputVolumeControlChangedEvent interface

interface MainOutputVolumeControlChangedEvent : Event {
};


The MainInputVolumeControlChangedEvent interface

interface MainInputVolumeControlChangedEvent : Event {
};


The MuteControlAddedEvent interface

interface MuteControlAddedEvent : Event {
    readonly attribute MuteControl control;
};


Attributes

control

The MuteControl object that was added to the AudioSystemContext.


The MuteControlRemovedEvent interface

interface MuteControlRemovedEvent : Event {
    readonly attribute MuteControl control;
};


Attributes

control

The MuteControl object that was removed from the AudioSystemContext.


The MainOutputMuteControlChangedEvent interface

interface MainOutputMuteControlChangedEvent : Event {
};


The MainInputMuteControlChangedEvent interface

interface MainInputMuteControlChangedEvent : Event {
};


The DeviceAddedEvent interface

interface DeviceAddedEvent : Event {
    readonly attribute AudioDevice device;
};


Attributes

device

The AudioDevice object that was added to the AudioSystemContext.


The DeviceRemovedEvent interface

interface DeviceRemovedEvent : Event {
    readonly attribute AudioDevice device;
};


Attributes

device

The AudioDevice object that was removed from the AudioSystemContext.


The StreamAddedEvent interface

interface StreamAddedEvent : Event {
    readonly attribute AudioStream stream;
};


Attributes

stream

The AudioStream object that was added to the AudioSystemContext.


The StreamRemovedEvent interface

interface StreamRemovedEvent : Event {
    readonly attribute AudioStream stream;
};


Attributes

stream

The AudioStream object that was removed from the AudioSystemContext.


The AudioGroupAddedEvent interface

interface AudioGroupAddedEvent : Event {
    readonly attribute AudioGroup group;
};


=== Attributes ===

==== group ====

The AudioGroup object that was added to the AudioSystemContext.


== The AudioGroupRemovedEvent interface ==

 <nowiki>
interface AudioGroupRemovedEvent : Event {
    readonly attribute AudioGroup group;
};


Attributes

group

The AudioGroup object that was removed from the AudioSystemContext.


The LabelChangedEvent interface

interface LabelChangedEvent : Event {
};


The VolumeChangedEvent interface

interface VolumeChangedEvent : Event {
};


The VolumeStepsChangedEvent interface

interface VolumeStepsChangedEvent : Event {
};


The BalanceChangedEvent interface

interface BalanceChangedEvent : Event {
    boolean channel_positions_changed;
    boolean balance_values_changed;
};

Attributes

channel_positions_changed

If there are changes in the channel positions, this is set to true.


balance_values_changed

If there are changes in the balance values, this is set to true.


The MutedChangedEvent interface

interface MutedChangedEvent : Event {
};


The VolumeControlChangedEvent interface

interface VolumeControlChangedEvent : Event {
};


The MuteControlChangedEvent interface

interface MuteControlChangedEvent : Event {
};


The DeviceTypesChangedEvent interface

interface DeviceTypesChangedEvent : Event {
};


Implementation with PulseAudio

https://wiki.tizen.org/wiki/User:Tanuk/AudioSystemAPI/PulseAudio