Re: Telephony API draft updated

On Thu, Nov 29, 2012 at 9:33 PM, Jonas Sicking <jonas@sicking.cc> wrote:
> On Fri, Nov 23, 2012 at 1:24 AM, Kis, Zoltan <zoltan.kis@intel.com> wrote:
>> Hello,
>>
>> On Mon, Nov 19, 2012 at 12:35 PM, EDUARDO FULLEA CARRERA <efc@tid.es> wrote:
>>> Hi,
>>>
>>> Please note that an update version of the Telephony API proposal has been uploaded:
>>> http://sysapps.github.com/sysapps/proposals/Telephony/Telephony.html
>>>
>>> This version incorporate feedback received on the first draft, mainly (may not be comprehensive):
>>> -removing record functionality
>>> -Changes in the states: removing 'error' and 'busy', adding 'accepted' and 'waiting'
>>> -Adding two state diagrams for inbound and outbound calls.
>>> -An issue note has been created indicating that it needs to be decided whether the state transitions (both in diagrams and textual description) are normative or not, as there is no consensus among the editors
>>
>> Before taking up that discussion, I would like to raise a new issue
>> perhaps easier to agree upon.
>>
>> Since telephony user experience of today is consistent with it, I
>> think it would make sense to have the HW related call controls (audio,
>> mike, ...) in the context of a telephone call, rather than on the main
>> telephony interface (where it gives the impression of a system
>> interface, irrespective of whether is there a telephony service
>> available or any call in progress - whereas it is should be just a
>> facade to these system controls from the context of a call).
>>
>> Therefore I propose moving these controls to a separate interface, and
>> include it in TelephonyCall.  The WebIDL would become the following:
>>
>> [NoInterfaceObject]
>> interface Telephony : EventTarget {
>>     readonly attribute DOMString[]     ownTelNumbers;
>>     readonly attribute DOMString[]     emergencyNumbers;
>>     readonly attribute TelephonyCall   active;
>>     readonly attribute TelephonyCall[] calls;
>>     TelephonyCall dial (DOMString number, DialParams params);
>>     void          startTone (DOMString tone);
>>     void          stopTone ();
>>     void          sendTone (DOMString tone);
>>              attribute EventHandler    onincoming;
>>              attribute EventHandler    oncallschanged;
>> };
>>
>> [NoInterfaceObject]
>> interface TelephonyMediaControl {
>>     attribute boolean          speakerEnabled;
>>     attribute boolean          headsetEnabled;
>>     attribute double            audioVolume;
>>     attribute boolean          audioMuted;
>>     attribute double            micVolume;
>>     attribute boolean          micMuted;
>>     /**
>>      * examples for future extension (remove me)
>>      * attribute boolean          frontCameraEnabled;
>>      * attribute boolean          backCameraEnabled;
>>      * attribute boolean          sendingLocalVideoEnabled;
>>      * attribute boolean          receivingRemoteVideoEnabled;
>>      */
>> }
>>
>> [NoInterfaceObject]
>> interface TelephonyCall : EventTarget {
>>     readonly attribute TelephonyMediaControl controls;
>>     readonly attribute DOMString    number;
>>     readonly attribute DOMString    state;
>>     readonly attribute DOMError     error;
>>     readonly attribute DOMString?   reason;
>>     void answer ();
>>     void disconnect ();
>>     void hold ();
>>     void resume ();
>>     void redirect (DOMString redirectNumber);
>>              attribute EventHandler onstatechange;
>>              attribute EventHandler ondialing;
>>              attribute EventHandler onalerting;
>>              attribute EventHandler onaccepted;
>>              attribute EventHandler onconnecting;
>>              attribute EventHandler onconnected;
>>              attribute EventHandler ondisconnecting;
>>              attribute EventHandler ondisconnected;
>>              attribute EventHandler onholding;
>>              attribute EventHandler onheld;
>>              attribute EventHandler onresuming;
>>              attribute EventHandler onredirecting;
>>              attribute EventHandler onerror;
>> };
>
> I don't think this change is a good idea.
>
> I agree that using the API before a call is started makes no changes
> that are visible to the user or possibly even to hardware. However
> that doesn't mean that it doesn't make sense to have the API on the
> Telephony object.
>
> Consider for example the element.style.color API. This API allows
> modifying the text-color that an element is rendered in. If an element
> is removed from the document, the element is obviously not rendered at
> all. If we were to apply the same argument as is used for the
> telephony API, we shouldn't have an API like element.style.color since
> in some situations the API doesn't have any effect that is visible to
> the user.
>
> However the element.style.color API is very popular with authors. Not
> only because it is intuitive, I.e. the API to change an element is
> located on the element itself, but also because in some cases changing
> the color before an element is rendered makes the code flow for the
> application simpler. I.e. it allows the application to modify the
> color whenever you want. If that happens to not change something on
> the screen until later, or even at all, that's ok.
>
> The call volume is a orthogonal property to any given call. Imagine a
> dialer UI which displays audio controls like "speaker" and "microphone
> volume" at all times. It would certainly be possible for an
> application to create such a UI even with the API proposed here. The
> application would have to remember the state using application logic
> and once a TelephonyCall object becomes available it would modify
> those properties on that object right away. It would then switch the
> application logic such that when the user interacts with the UI it
> finds the closest TelephonyCall object and modifies that, rather than
> modifying the internal application state.
>
> However it seems much more intuitive to put the audio properties on
> the Telephony interface. This way it's clear that the settings are
> per-call but rather global for all telephony interactions. And the
> application can always wire the UI directly up to API without having
> to switch between using application state or the API depending on if a
> TelephonyCall object happens to be connected. It also means that we
> won't have to address complex edge cases such as what happens if
> someone uses the API on a disconnected TelephonyCall object.
>
> In short, we should focus on what creates a useable API. We shouldn't
> focus on that the API has to map directly to hardware behavior. We
> also shouldn't focus on creating the API that is as simple as possible
> to implement. Application-author friendliness should be a higher
> priority than implementor friendliness.

Even after that long email, of course I forgot to mention a few things :-)

The first one is that just because the implementation of the API might
not have a backend to talk to until there is a call connected, doesn't
mean that we couldn't create an API which allows setting the volume
anytime. The API would simply have to take over the logic of tracking
if there's a call connected and if there isn't, remember the stored
values until a call is connected.

The second point is that I'm not convinced that the telephony API
should contain audio controls at all. In Firefox OS we've recently
started working on a Audio API which we've needed to manage various
non-telephony related audio channels. This API deals with things like
muting currently playing music when the alarm clock goes off. And
allowing UI audio volume to be separated from the volume of "incoming
SMS" and "incoming Email" notification sounds.

Our goal is to allow this API to also modify the audio channels that
are used by a telephony application which is built on WebRTC. I.e. if
you receive an incoming WebRTC call, you'll want the same type of
audio controls as we've been talking about for the telephony API.
However I don't think it would be correct to let a WebRTC-based
application use the telephony API to control audio volumes. If nothing
else it would create a much more complex security model since of
course the WebRTC-based application shouldn't have access to the
telephony hardware.

The API is still in early stages and I wouldn't recommend removing the
audio features on the Telephony API for now since we don't yet have a
full replacement. But I think it's something that we should keep in
mind as we're talking about audio features for telephony.

Here is what the API looks like so far:

https://wiki.mozilla.org/WebAPI/AudioChannels

/ Jonas

Received on Friday, 30 November 2012 05:45:59 UTC