Re: Telephony API draft updated

On Fri, Nov 30, 2012 at 1:21 AM, Kis, Zoltan <zoltan.kis@intel.com> wrote:
>> I don't think this change is a good idea.
>
> Yes, it just tackled the visibility issue, but there other issues as well.
> It looks like you responded to the last archived email, but the 2
> latest messages (from Hsin-Yi Tsai and my reply) are missing from the
> thread in the archive. Those should explain some more background for
> this proposal.

I haven't received those emails. Not sure if there was some problem
with the list. I did receive this email though (obviously) and it does
seem to have gotten appropriately archived.

>> 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.
>
> Are you saying the API functionality should be dependent on whether
> there is a call, or not?

Depends on the definition of "API functionality" I guess. My
definition of it is "When there's audio coming from the telephony
interface, the volume of that audio will be scaled by this much".

> So should it just silently do nothing audible, except setting internal
> audio defaults, when there is no call (and not even return an error,
> or raise an exception) and just work when there is a call?

I assume that you wouldn't consider it a kludge that the API works
when you're on a call and the other side isn't saying anything? Or
when the other side is muted? At that point the API also does not have
an audible effect.

Likewise, would you consider the element.style.color API a kludge
since it allows setting the color of an element that isn't rendered?

>> 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.
>
> Are you suggesting that just because we happen to use color setting in
> a particular way, which is popular, we should apply this pattern in
> Telephony, despite it introduces ambiguity in API behavior?
> I don't take this as a good argument.

No. I was demonstrating an example of an, in my opinion proven well
designed API, as an example of where an API can hold state even though
that state isn't directly affecting the user.

In what way does the API introduce ambiguity? There would be a strict
requirement that once a call is connected the volume and mute states
that have been set through the API is immediately applied to that
call.

>> The call volume is a orthogonal property to any given call.
>
> I agree with this. Volume control should actually be on the stream
> (source volume, or sink volume).

If it applies only to that stream then I agree. Is that the proposal?

>> 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.
>
> I have not yet seen such dialers, but maybe it's time to have them.
> The world is changing.
> Technically it is not impossible, since the app class is given
> (telephony), so we may know the volume scale.

I've definitely several times wanted to be able to set my phone to
"mute" before connecting to a call. Very useful when calling in to a
telephony conferance when I happen to be in a noisy place.

> BTW what do you mean by "closest" TelephonyCall object?

If the volume settings apply globally to all TelephonyCall objects,
even though the properties live on the individual objects, then if the
user modifies the volume using the UI, the application has to find
just any'ol TelephonyCall object and modify the properties there. I.e.
you wouldn't care which object you got, as long as you got one of
them.

>> 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.
>
> A disconnected call object obviously could not possibly set any
> volume, since there is no audio stream.
>
>>
>> In short, we should focus on what creates a useable API.
>
> Which should not be disconnected from the reality of how things work.

Are you worried that it would be hard to implement if the audio
controls lived on a global object like Telephony? I believe Firefox OS
has implemented it without much hassle, but of course it could be
harder elsewhere. I'd be curious to know if the backend of the Firefox
OS implementation is able to go to a global setting when the volume is
modified, or if it has to find some sort of internal representation of
a call object and modify things there.

>> 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.
>
> For a first step could we agree in defining a separate interface for
> audio etc controls, and include that object in Telephony API rather
> than a bunch of properties?
> Then, we may discuss later what would be a better place for it.
>
> An updated proposal including volume scale:
>
> [NoInterfaceObject]
> interface TelephonyMediaControl : EventHandler {
>     attribute boolean          speakerEnabled;
>     attribute boolean          headsetEnabled;
>     attribute double            audioVolume; // from 0.0 to 1.0
>     attribute unsigned short audioVolumeSteps; // scale
>     attribute boolean          audioMuted; // from 0.0 to 1.0
>     attribute double            micVolume;
>     attribute unsigned short micVolumeSteps; // scale
>     attribute boolean          micMuted;
>
>     attribute EventHandler onvolumechanged; // including muting
>     attribute EventHandler onmicrophonechanged; // including muting
>     attribute EventHandler onaudioroutingchanged;
>
>     /** for future use */
>     attribute boolean          frontCameraEnabled;
>     attribute boolean          backCameraEnabled;
>     attribute boolean          localVideoOn;  // send video
>     attribute boolean          remoteVideoOn; // receive video
>     attribute EventHandler oncamerachanged;
> }

I think it's hard to talk in the abstract about which properties we
should have until we know where they live. But sure, let's tentatively
say that the above set of properties are good. Though I'd prefer to
leave video out of it for now as to keep the discussion simpler.

/ Jonas

Received on Friday, 30 November 2012 10:57:04 UTC