Re: WebFM API proposals

[Cameron McCormack]

Pin Zhang:
> For a FM app[1], i think these features are required:
> 1) Display the availability of the device
> 2) Indicator of FM device status, e.g. on or off
> 3) Notify user if the antenna is plugged or unplugged
> 4) Manually change the radio frequency
> 5) Display the current frequency
> 6) Display the range of radio frequencies
> 7) Location selection, e.g. be able to change the range of
> frequencies based on the location
> 8) Auto scan available radio program, up and down
> 9) Cancel radio program seeking
> 10) Record the sound of FM

I wonder if it makes sense not to bake in the term "FM" into the API.
At some point we will probably have devices that can receive DAB (and
there may even be some that do AM now), and I don't think a separate API
should be needed to access those.

[regisedua...@gmail.com]

Do not forget a timer to turn off the radio, I think it would be interesting.

;)

Att.
Régis

[regisedua...@gmail.com]

Do not forget a timer to turn off the radio, I think it would be interesting.

;)

Att.
Régis

Em terça-feira, 22 de maio de 2012 22h27min00s UTC-3, Cameron McCormack escreveu:

[Pin Zhang]

Why do we need a timer to turn off the radio?

在 2012年5月23日星期三UTC+8上午9时36分40秒，regisedua...@gmail.com写道：

[Pin Zhang]

If considering both AM and DAB, may be the "radio" could be used, but i am not sure if the API proposals is still appropriate.

[Pin Zhang]

If considering both AM and DAB, may be the "radio" could be used, but i am not sure if the API proposals is still appropriate.

On Wednesday, May 23, 2012 9:27:00 AM UTC+8, Cameron McCormack wrote:

[regisedua...@gmail.com]

Some days ago I wanted to sleep listening to music, but do not want to leave my smartphone connected all night because of battery. It's just an idea, I would like the music player and FM radio had a timer.

[regisedua...@gmail.com]

Some days ago I wanted to sleep listening to music, but do not want to leave my smartphone connected all night because of battery. It's just an idea, I would like the music player and FM radio had a timer.


Em quarta-feira, 23 de maio de 2012 05h59min48s UTC-3, Pin Zhang escreveu:

Em quarta-feira, 23 de maio de 2012 05h59min48s UTC-3, Pin Zhang escreveu:

[regisedua...@gmail.com]

Some days ago I wanted to sleep listening to music, but do not want to leave my smartphone connected all night because of battery. It's just an idea, I would like the music player and FM radio had a timer.


Em quarta-feira, 23 de maio de 2012 05h59min48s UTC-3, Pin Zhang escreveu:

Em quarta-feira, 23 de maio de 2012 05h59min48s UTC-3, Pin Zhang escreveu:

[Pin Zhang]

OK, i see, there is "off" in the API, so this feature could be implemented by setting an timeout to call the "off" function.

[Pin Zhang]

OK, i see, there is "off" in the API, so this feature could be implemented by setting an timeout to call the "off" function.

On Wednesday, May 23, 2012 7:33:40 PM UTC+8, regisedua...@gmail.com wrote:

[Pin Zhang]

OK, i see, there is "off" in the API, so this feature could be implemented by setting an timeout to call the "off" function.

On Wednesday, May 23, 2012 7:33:40 PM UTC+8, regisedua...@gmail.com wrote:

[regisedua...@gmail.com]

Of course, it would be nice!

[regisedua...@gmail.com]

Of course, it would be nice!


Em quarta-feira, 23 de maio de 2012 09h46min06s UTC-3, Pin Zhang escreveu:

[regisedua...@gmail.com]

Of course, it would be nice!


Em quarta-feira, 23 de maio de 2012 09h46min06s UTC-3, Pin Zhang escreveu:

[JOSE MANUEL CANTERA FONSECA]

El 23/05/12 15:05, "regisedua...@gmail.com"
<regisedua...@gmail.com> escribió:

>Of course, it would be nice!
>
>
>Em quarta-feira, 23 de maio de 2012 09h46min06s UTC-3, Pin Zhang
>escreveu:
>> OK, i see, there is "off" in the API, so this feature could be
>>implemented by setting an timeout to call the "off" function.

I think that functionality could be achieved through the Alarm API

>_______________________________________________
>dev-webapi mailing list
>dev-w...@lists.mozilla.org
>https://lists.mozilla.org/listinfo/dev-webapi
>



Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.
This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at
http://www.tid.es/ES/PAGINAS/disclaimer.aspx

[JOSE MANUEL CANTERA FONSECA]

[Philipp von Weitershausen]

Nice work on this initial draft! A few comments below:

On Mon, May 21, 2012 at 7:43 AM, Pin Zhang <zhang...@gmail.com> wrote:
> For a FM app[1], i think these features are required:
>  1) Display the availability of the device
>  2) Indicator of FM device status, e.g. on or off
>  3) Notify user if the antenna is plugged or unplugged
>  4) Manually change the radio frequency
>  5) Display the current frequency
>  6) Display the range of radio frequencies
>  7) Location selection, e.g. be able to change the range of
> frequencies based on the location
>  8) Auto scan available radio program, up and down
>  9) Cancel radio program seeking
>  10) Record the sound of FM

I'm not entirely convinced (10) is absolutely necessary for a first
iteration. But it doesn't concern the API design, either.

> Based on these features, here are the api descriptions:
> interface FM : EventTarget
> {
>  /* Indicate if FM is on */
>  readonly attribute boolean isOn;

Other APIs such as the Wifi API use `enabled`

>  /* Fired when antenna is plugged */
>  attribute Function onantennaavailable;
>
>  /* Fired when antenna is unplugged */
>  attribute Function onantennaunavailable;

Could collapse these into a single "antennavailablechange" or just
"antennachange" event.

>  /* Fired when FM HW is power on */
>  attribute Function onpoweron;
>
>  /* Fired when FM HW is power off */
>  attribute Function onpoweroff;

Same here: collapse into "powerchange" event

>  /*
>   Fired when FM frequency is changed. The current frequency will be
> returned as the freq of event object.
>   */
>  attribute Function onfreqchanged;

We can afford to spell out words: "frequencychanged"

>  /* Turn on the FM, onsuccess will be triggered if FM is turned on.
> */
>  DOMRequest on();
>
>  /* Turn off the FM */
>  DOMRequest off();

Wifi (and possibly other APIs) use a single

DOMRequest setEnabled(in bool enabled);

method. Or, if you want to mathc the "powerchange" event above, you can call it

DOMRequest setPower(in bool on);

>  /* Current frequncy will be returned as result of request */
>  DOMRequest getFreq();

Why can't this be a

readonly double frequency;

? Simply fetch the freuqency and make it available under this member
before each time we fire a "frequencychange" event.

>  /*
>   onsuccess will be triggered if frequency is set successfully.
>   The frequency may not be the value passed, for example: the freq is
> out of the range, app should listen on the "onfreqchanged" to get the
> right frequency.
>   */
>  DOMRequest setFreq(in long freq);

Same point as above: spell out words fully. Also, shouldn't frequency
be a double? I guess not if you're specifying the frequency in kHz. In
any case, the unit has to be documented and be part of the spec.
Initial value / value when the radio is off could simply be `null` (in
that case you need to specify it as a `jsval`).

[Gervase Markham]

On 24/05/12 09:29, Philipp von Weitershausen wrote:
> I'm not entirely convinced (10) is absolutely necessary for a first
> iteration. But it doesn't concern the API design, either.

I think 10 needs to be done outside this API. B2G should have a
mechanism to record audio streams. It's not specific to FM.

Gerv

[Gervase Markham]

On 24/05/12 09:29, Philipp von Weitershausen wrote:

> Other APIs such as the Wifi API use `enabled`

Regarding your other points: is there a Web API "style guide" somewhere
which outlines these things, such as standard names for booleans, when
to use functions and when to use properties, etc.?

Gerv

[Pin Zhang]

inline reply below

On Thursday, May 24, 2012 4:29:50 PM UTC+8, Philipp von Weitershausen wrote:
> Nice work on this initial draft! A few comments below:
>

> On Mon, May 21, 2012 at 7:43 AM, Pin Zhang wrote:
> > For a FM app[1], i think these features are required:
> >  1) Display the availability of the device
> >  2) Indicator of FM device status, e.g. on or off
> >  3) Notify user if the antenna is plugged or unplugged
> >  4) Manually change the radio frequency
> >  5) Display the current frequency
> >  6) Display the range of radio frequencies
> >  7) Location selection, e.g. be able to change the range of
> > frequencies based on the location
> >  8) Auto scan available radio program, up and down
> >  9) Cancel radio program seeking
> >  10) Record the sound of FM
>
> I'm not entirely convinced (10) is absolutely necessary for a first
> iteration. But it doesn't concern the API design, either.
>
> > Based on these features, here are the api descriptions:
> > interface FM : EventTarget
> > {
> >  /* Indicate if FM is on */
> >  readonly attribute boolean isOn;
>
> Other APIs such as the Wifi API use `enabled`

Is this a convention?

>
> >  /* Fired when antenna is plugged */
> >  attribute Function onantennaavailable;
> >
> >  /* Fired when antenna is unplugged */
> >  attribute Function onantennaunavailable;
>
> Could collapse these into a single "antennavailablechange" or just
> "antennachange" event.

There are only two different statuses for antenna, i think this is more convenient.

>
> >  /* Fired when FM HW is power on */
> >  attribute Function onpoweron;
> >
> >  /* Fired when FM HW is power off */
> >  attribute Function onpoweroff;
>
> Same here: collapse into "powerchange" event

Same reason.

>
> >  /*
> >   Fired when FM frequency is changed. The current frequency will be
> > returned as the freq of event object.
> >   */
> >  attribute Function onfreqchanged;
>
> We can afford to spell out words: "frequencychanged"
>
> >  /* Turn on the FM, onsuccess will be triggered if FM is turned on.
> > */
> >  DOMRequest on();
> >
> >  /* Turn off the FM */
> >  DOMRequest off();
>
> Wifi (and possibly other APIs) use a single
>
> DOMRequest setEnabled(in bool enabled);
>
> method. Or, if you want to mathc the "powerchange" event above, you can call it
>
> DOMRequest setPower(in bool on);
>
> >  /* Current frequncy will be returned as result of request */
> >  DOMRequest getFreq();
>
> Why can't this be a
>
> readonly double frequency;

It will fail to get or set frequency when FM HW is off, and the action to set frequency could be stucked if the FM is seeking station.

>
> ? Simply fetch the freuqency and make it available under this member
> before each time we fire a "frequencychange" event.
>
> >  /*
> >   onsuccess will be triggered if frequency is set successfully.
> >   The frequency may not be the value passed, for example: the freq is
> > out of the range, app should listen on the "onfreqchanged" to get the
> > right frequency.
> >   */
> >  DOMRequest setFreq(in long freq);
>
> Same point as above: spell out words fully. Also, shouldn't frequency
> be a double? I guess not if you're specifying the frequency in kHz. In
> any case, the unit has to be documented and be part of the spec.
> Initial value / value when the radio is off could simply be `null` (in
> that case you need to specify it as a `jsval`).

I think most of the FM chip take integer as input, you can check the implementations of CM:
https://github.com/CyanogenMod/android_frameworks_base/blob/0620b6bb2a9b0b1d3a84fcf429609e6dba046c2e/core/jni/android_hardware_fm_si4709.cpp
https://github.com/CyanogenMod/android_frameworks_base/blob/0620b6bb2a9b0b1d3a84fcf429609e6dba046c2e/core/jni/android_hardware_fm_bcm4325.cpp
https://github.com/CyanogenMod/android_frameworks_base/blob/0620b6bb2a9b0b1d3a84fcf429609e6dba046c2e/core/jni/android_hardware_fm_wi1271.cpp

[Pin Zhang]

Will we define a separate API for media streams?

[Pin Zhang]

inline reply below

On Thursday, May 24, 2012 4:29:50 PM UTC+8, Philipp von Weitershausen wrote:

> Nice work on this initial draft! A few comments below:
>

> On Mon, May 21, 2012 at 7:43 AM, Pin Zhang wrote:
> > For a FM app[1], i think these features are required:
> >  1) Display the availability of the device
> >  2) Indicator of FM device status, e.g. on or off
> >  3) Notify user if the antenna is plugged or unplugged
> >  4) Manually change the radio frequency
> >  5) Display the current frequency
> >  6) Display the range of radio frequencies
> >  7) Location selection, e.g. be able to change the range of
> > frequencies based on the location
> >  8) Auto scan available radio program, up and down
> >  9) Cancel radio program seeking
> >  10) Record the sound of FM
>
> I'm not entirely convinced (10) is absolutely necessary for a first
> iteration. But it doesn't concern the API design, either.
>
> > Based on these features, here are the api descriptions:
> > interface FM : EventTarget
> > {
> >  /* Indicate if FM is on */
> >  readonly attribute boolean isOn;
>
> Other APIs such as the Wifi API use `enabled`

Is this a convention?

>
> >  /* Fired when antenna is plugged */
> >  attribute Function onantennaavailable;
> >
> >  /* Fired when antenna is unplugged */
> >  attribute Function onantennaunavailable;
>
> Could collapse these into a single "antennavailablechange" or just
> "antennachange" event.

There are only two different statuses for antenna, i think this is more convenient.

>

> >  /* Fired when FM HW is power on */
> >  attribute Function onpoweron;
> >
> >  /* Fired when FM HW is power off */
> >  attribute Function onpoweroff;
>
> Same here: collapse into "powerchange" event

Same reason.

>
> >  /*
> >   Fired when FM frequency is changed. The current frequency will be
> > returned as the freq of event object.
> >   */
> >  attribute Function onfreqchanged;
>
> We can afford to spell out words: "frequencychanged"
>
> >  /* Turn on the FM, onsuccess will be triggered if FM is turned on.
> > */
> >  DOMRequest on();
> >
> >  /* Turn off the FM */
> >  DOMRequest off();
>
> Wifi (and possibly other APIs) use a single
>
> DOMRequest setEnabled(in bool enabled);
>
> method. Or, if you want to mathc the "powerchange" event above, you can call it
>
> DOMRequest setPower(in bool on);
>
> >  /* Current frequncy will be returned as result of request */
> >  DOMRequest getFreq();
>
> Why can't this be a
>
> readonly double frequency;

It will fail to get or set frequency when FM HW is off, and the action to set frequency could be stucked if the FM is seeking station.

>

> ? Simply fetch the freuqency and make it available under this member
> before each time we fire a "frequencychange" event.
>
> >  /*
> >   onsuccess will be triggered if frequency is set successfully.
> >   The frequency may not be the value passed, for example: the freq is
> > out of the range, app should listen on the "onfreqchanged" to get the
> > right frequency.
> >   */
> >  DOMRequest setFreq(in long freq);
>
> Same point as above: spell out words fully. Also, shouldn't frequency
> be a double? I guess not if you're specifying the frequency in kHz. In
> any case, the unit has to be documented and be part of the spec.
> Initial value / value when the radio is off could simply be `null` (in
> that case you need to specify it as a `jsval`).

[Henri Sivonen]

On Mon, May 21, 2012 at 5:43 PM, Pin Zhang <zhang...@gmail.com> wrote:
>  /* Turn on the FM, onsuccess will be triggered if FM is turned on.
> */
>  DOMRequest on();

What does it mean to turn the FM radio "on"? Will turning the FM radio
"on" play sound or just activate a part of the chipset? (I would
expect an HTML audio element to be used for making sound play even if
the sound comes from an FM tuner instead of the network. That is, I
would expect the radio tuner to act as a data source from which an
HTML audio elements can pull data.)

>  /* FM media API */
>  DOMString getFmURI();

What are the URLs expected to be like? Will a URL specify a frequency
or a tuner device? If it's typically possible to tune multiple
frequencies at the same time, it would probably make sense to make
different frequencies URL-addressable. On the other hand, if the
hardware is always expected to limit the tuner to listen to one
frequency at a time, it might be useful to have a special URL that
points to the data stream coming out of the tuner and can be used as
the src of an HTML audio element regardless of what frequency the
tuner is currently set to.

--
Henri Sivonen
hsiv...@iki.fi
http://hsivonen.iki.fi/

[pzhang]

On 05/28/2012 06:34 PM, Henri Sivonen wrote:
> On Mon, May 21, 2012 at 5:43 PM, Pin Zhang<zhang...@gmail.com> wrote:
>> /* Turn on the FM, onsuccess will be triggered if FM is turned on.
>> */
>> DOMRequest on();
> What does it mean to turn the FM radio "on"? Will turning the FM radio
> "on" play sound or just activate a part of the chipset? (I would
> expect an HTML audio element to be used for making sound play even if
> the sound comes from an FM tuner instead of the network. That is, I
> would expect the radio tuner to act as a data source from which an
> HTML audio elements can pull data.)

“on/off” means turn the FM chip power on/off, and the FM chip will talk
to audio HW directly if it is turned on.
Of course you can get the FM audio data source as an media URI by
"getFmURI", set it to the source of an audio element,
and you can make sound recording or draw images of sound etc.

>> /* FM media API */
>> DOMString getFmURI();
> What are the URLs expected to be like? Will a URL specify a frequency
> or a tuner device? If it's typically possible to tune multiple
> frequencies at the same time, it would probably make sense to make
> different frequencies URL-addressable. On the other hand, if the
> hardware is always expected to limit the tuner to listen to one
> frequency at a time, it might be useful to have a special URL that
> points to the data stream coming out of the tuner and can be used as
> the src of an HTML audio element regardless of what frequency the
> tuner is currently set to.

The url may look like this: fm://radio0，the FM device listen to one
frequency at a time, so it should only specify a FM device.

[Mounir Lamouri]

On 05/21/2012 04:43 PM, Pin Zhang wrote:
> Based on these features, here are the api descriptions:
> interface FM : EventTarget
> {
> /* Indicate if FM is on */
> readonly attribute boolean isOn;

Is this related to |onpoweron| and |onpoweroff|.

> /* Indicate if antenna is available */
> readonly attribute boolean isAntennaAvailable;

>
> /* Fired when antenna is plugged */
> attribute Function onantennaavailable;
>
> /* Fired when antenna is unplugged */
> attribute Function onantennaunavailable;

Do we have phones nowadays that allow you to plug/unplug an antenna? I'm
not sure I understand why we are showing that.

> /* Fired when FM HW is power on */
> attribute Function onpoweron;
>
> /* Fired when FM HW is power off */
> attribute Function onpoweroff;

Couldn't that be handled by the Settings API?

> /*
> Fired when FM frequency is changed. The current frequency will be
> returned as the freq of event object.
> */
> attribute Function onfreqchanged;

|onfrequencychanged|, as said philikon.

> /* Turn on the FM, onsuccess will be triggered if FM is turned on.
> */
> DOMRequest on();
>

> /* Turn off the FM */
> DOMRequest off();

setEnabled(boolean) would be better.

> /* Current frequncy will be returned as result of request */
> DOMRequest getFreq();
>

> /*
> onsuccess will be triggered if frequency is set successfully.
> The frequency may not be the value passed, for example: the freq is
> out of the range, app should listen on the "onfreqchanged" to get the
> right frequency.
> */
> DOMRequest setFreq(in long freq);

You should consider .frequency as said philikon.

> /*
> Tell FM seek up, the next frequency will be returned as result of
> request, in the mean time,
> if frequency is changed, onfreqchanged will be triggered.
> */
> DOMRequest seekUp();
>
> /*
> Tell FM seek down, the next frequency will be returned as result of
> request, in the mean time,
> if frequency is changed, onfreqchanged will be triggered.
> */
> DOMRequest seekDown();

> /* Cancel seek action */
> DOMRequest cancelSeek();

Why not DOMRequest could be SeekRequest with a .cancel() method?

> /* FM media API */
> DOMString getFmURI();

As Henri, I'm not sure what that is...

Cheers,
--
Mounir

[Hernan Rodriguez Colmeiro]

On Tue, May 29, 2012 at 2:28 PM, Mounir Lamouri <mou...@lamouri.fr> wrote:
>>   /* Fired when antenna is plugged */
>>   attribute Function onantennaavailable;
>>
>>   /* Fired when antenna is unplugged */
>>   attribute Function onantennaunavailable;
>
> Do we have phones nowadays that allow you to plug/unplug an antenna? I'm
> not sure I understand why we are showing that.
>

On most phones, the headphones act as the antenna for the FM Radio, so
if it's not connected the radio doesn't work. The UI at least needs to
know the status of the antenna to warn the user.

Hernán

[Philipp von Weitershausen]

On Thu, May 24, 2012 at 7:47 AM, Pin Zhang <zhang...@gmail.com> wrote:
>> > Based on these features, here are the api descriptions:
>> > interface FM : EventTarget
>> > {
>> >  /* Indicate if FM is on */
>> >  readonly attribute boolean isOn;
>>
>> Other APIs such as the Wifi API use `enabled`
>

> Is this a convention?

Implicitly, yes, since other APIs use "enabled". I do not know whether
there's an explicit convention.

>> >  /* Fired when antenna is plugged */
>> >  attribute Function onantennaavailable;
>> >
>> >  /* Fired when antenna is unplugged */
>> >  attribute Function onantennaunavailable;
>>
>> Could collapse these into a single "antennavailablechange" or just
>> "antennachange" event.
>

> There are only two different statuses for antenna, i think this is more convenient.

I think 2 separate events is more *in*convenient. Consider writing the
UI for the FM application. In my experience, it often looks something
like this:

navigator.mozFM.onantennachange = function onantennachange() {
var cssClass = navigator.mozFM.isAntennaAvailable ?
"antenna-available" : "antenna-unavailable";
document.getElementById("antennaStatus").className = cssClass;
//potentially show notification symbol, etc.
};

This short example may not demonstrate it too clearly, but my point is
that one often has the same logic for a number of events, so you end
up registering the same function for the same event handler after all.
That's why objects with lots of possible states (e.g. XHR,
TelephonyCall, etc.) have "catch all" events (readystatechange,
statechange, etc.) in addition to individual event handlers.

>> >  /* Current frequncy will be returned as result of request */
>> >  DOMRequest getFreq();
>>
>> Why can't this be a
>>
>>   readonly double frequency;
>

> It will fail to get or set frequency when FM HW is off, and the action to set frequency could be stucked if the FM is seeking station.

First off, I'm proposing to keep this a readonly getter, so
setFrequency() would still be used for setting the frequency. And when
the HW is off, make it 0 or null. Same when it's seeking, perhaps. Or
just don't update until the seeking has finished. I'm wary of exposing
leaky abstractions or shortcomings of our own hardware layer to the
WebAPI.

>> ? Simply fetch the freuqency and make it available under this member
>> before each time we fire a "frequencychange" event.
>>
>> >  /*
>> >   onsuccess will be triggered if frequency is set successfully.
>> >   The frequency may not be the value passed, for example: the freq is
>> > out of the range, app should listen on the "onfreqchanged" to get the
>> > right frequency.
>> >   */
>> >  DOMRequest setFreq(in long freq);
>>
>> Same point as above: spell out words fully. Also, shouldn't frequency
>> be a double? I guess not if you're specifying the frequency in kHz. In
>> any case, the unit has to be documented and be part of the spec.
>> Initial value / value when the radio is off could simply be `null` (in
>> that case you need to specify it as a `jsval`).
>

> I think most of the FM chip take integer as input,

That's not very good reason to do the same in a WebAPI. A WebAPI
should not only NOT be device specific, it should also not be platform
specific. Remember, we want others to support these APIs, too.

[Philipp von Weitershausen]

(My initial reply didn't make it to the list for some reason. Resending.)

On Thu, May 24, 2012 at 7:47 AM, Pin Zhang <zhang...@gmail.com> wrote:
>> > Based on these features, here are the api descriptions:
>> > interface FM : EventTarget
>> > {
>> > /* Indicate if FM is on */
>> > readonly attribute boolean isOn;
>>
>> Other APIs such as the Wifi API use `enabled`
>

> Is this a convention?

Implicitly, yes, since other APIs use "enabled". I do not know whether
there's an explicit convention.

>> > /* Fired when antenna is plugged */
>> > attribute Function onantennaavailable;
>> >
>> > /* Fired when antenna is unplugged */
>> > attribute Function onantennaunavailable;
>>
>> Could collapse these into a single "antennavailablechange" or just
>> "antennachange" event.
>

> There are only two different statuses for antenna, i think this is more convenient.

I think 2 separate events is more *in*convenient. Consider writing the
UI for the FM application. In my experience, it often looks something
like this:

navigator.mozFM.onantennachange = function onantennachange() {
var cssClass = navigator.mozFM.isAntennaAvailable ?
"antenna-available" : "antenna-unavailable";
document.getElementById("antennaStatus").className = cssClass;
//potentially show notification symbol, etc.
};

This short example may not demonstrate it too clearly, but my point is
that one often has the same logic for a number of events, so you end
up registering the same function for the same event handler after all.
That's why objects with lots of possible states (e.g. XHR,
TelephonyCall, etc.) have "catch all" events (readystatechange,
statechange, etc.) in addition to individual event handlers.

>> > /* Current frequncy will be returned as result of request */
>> > DOMRequest getFreq();
>>
>> Why can't this be a
>>
>> readonly double frequency;
>

> It will fail to get or set frequency when FM HW is off, and the action to set frequency could be stucked if the FM is seeking station.

First off, I'm proposing to keep this a readonly getter, so
setFrequency() would still be used for setting the frequency. And when
the HW is off, make it 0 or null. Same when it's seeking, perhaps. Or
just don't update until the seeking has finished. I'm wary of exposing
leaky abstractions or shortcomings of our own hardware layer to the
WebAPI.

>> ? Simply fetch the freuqency and make it available under this member
>> before each time we fire a "frequencychange" event.
>>
>> > /*
>> > onsuccess will be triggered if frequency is set successfully.
>> > The frequency may not be the value passed, for example: the freq is
>> > out of the range, app should listen on the "onfreqchanged" to get the
>> > right frequency.
>> > */
>> > DOMRequest setFreq(in long freq);
>>
>> Same point as above: spell out words fully. Also, shouldn't frequency
>> be a double? I guess not if you're specifying the frequency in kHz. In
>> any case, the unit has to be documented and be part of the spec.
>> Initial value / value when the radio is off could simply be `null` (in
>> that case you need to specify it as a `jsval`).
>

[Philipp von Weitershausen]

(Resending to the correct list address.)

On Thu, May 24, 2012 at 7:58 AM, Pin Zhang <zhang...@gmail.com> wrote:
> Will we define a separate API for media streams?

I imagine much of that can be tacked onto the WebRTC stuff.

[Chris Jones]

I haven't followed this discussion 100%, but have you considered defining the FM API as a MediaStream subtype? That would match more closely what we're doing for microphone, camera, and other local device streams.

Cheers,
Chris

----- Original Message -----
> From: "Pin Zhang" <zhang...@gmail.com>
> To: mozilla-d...@lists.mozilla.org
> Sent: Monday, May 21, 2012 7:43:00 AM
> Subject: WebFM API proposals
>
> For a FM app[1], i think these features are required:
> 1) Display the availability of the device
> 2) Indicator of FM device status, e.g. on or off
> 3) Notify user if the antenna is plugged or unplugged
> 4) Manually change the radio frequency
> 5) Display the current frequency
> 6) Display the range of radio frequencies
> 7) Location selection, e.g. be able to change the range of
> frequencies based on the location
> 8) Auto scan available radio program, up and down
> 9) Cancel radio program seeking
> 10) Record the sound of FM
>

> No.7 will not be frequently used feature, and usually, there are only
> three options for FM band[2]:
> - 87500KHZ~108000KHZ (Europe and Africa)
> - 88000KHZ~108000KHZ (America)
> - 76000KHZ~90000KHZ (Japan)
> So, define the FM band in the Settings API would be more appropriate.

>
> Based on these features, here are the api descriptions:
> interface FM : EventTarget
> {
> /* Indicate if FM is on */
> readonly attribute boolean isOn;
>

> /* Indicate if antenna is available */
> readonly attribute boolean isAntennaAvailable;
>

> /* Fired when antenna is plugged */
> attribute Function onantennaavailable;
>
> /* Fired when antenna is unplugged */
> attribute Function onantennaunavailable;
>

> /* Fired when FM HW is power on */
> attribute Function onpoweron;
>
> /* Fired when FM HW is power off */
> attribute Function onpoweroff;
>

> /*
> Fired when FM frequency is changed. The current frequency will be
> returned as the freq of event object.
> */
> attribute Function onfreqchanged;
>

> /* Turn on the FM, onsuccess will be triggered if FM is turned on.
> */
> DOMRequest on();
>
> /* Turn off the FM */
> DOMRequest off();
>

> /* Current frequncy will be returned as result of request */
> DOMRequest getFreq();
>

> /*
> onsuccess will be triggered if frequency is set successfully.
> The frequency may not be the value passed, for example: the freq
> is
> out of the range, app should listen on the "onfreqchanged" to get the
> right frequency.
> */
> DOMRequest setFreq(in long freq);
>

> /*
> Tell FM seek up, the next frequency will be returned as result of
> request, in the mean time,
> if frequency is changed, onfreqchanged will be triggered.
> */
> DOMRequest seekUp();
>
> /*

> Tell FM seek down, the next frequency will be returned as result
> of

> request, in the mean time,
> if frequency is changed, onfreqchanged will be triggered.
> */
> DOMRequest seekDown();
>
> /* Cancel seek action */
> DOMRequest cancelSeek();
>

> /* FM media API */
> DOMString getFmURI();
> }
>

> Here are some examples:
> // Add frequency changed event listener
> window.navigator.fm.onfreqchanged = function(event) {
> var freq = event.freq;
> // Update UI element
> updateUIFreq(freq);
> };
>
> // get frequency
> var request = window.navigator.fm.getFreq();
> request.onsuccess = function() {
> // update UI element
> updateUIFreq(request.result);
> };
>
> request.onerror = function() {
> // display alarm
> displayAlarm("Failed to get frequency.");
> };
>
> Most of the functions are asynchronous and return a DOMRequest
> object,
> because any of the function call may fail, for example: it will fail
> to get or set frequency if FM HW is power off.
>
> For the RDS (Radio Data System)[3], I think it's not the top priority
> feature, we could define another interface for RDS after we finished
> the WebFM API.
>
> Any comments and suggestions are welcomed.
>
> [1]: https://bugzilla.mozilla.org/show_bug.cgi?id=749053
> [2]: http://en.wikipedia.org/wiki/FM_broadcast_band
> [3]: http://en.wikipedia.org/wiki/Radio_Data_System

[pzhang]

On 05/30/2012 01:28 AM, Mounir Lamouri wrote:
> On 05/21/2012 04:43 PM, Pin Zhang wrote:

>> Based on these features, here are the api descriptions:
>> interface FM : EventTarget
>> {
>> /* Indicate if FM is on */
>> readonly attribute boolean isOn;

> Is this related to |onpoweron| and |onpoweroff|.

yes, we need an attribute to get the current power status of FM device.

>
>> /* Indicate if antenna is available */
>> readonly attribute boolean isAntennaAvailable;
>>
>> /* Fired when antenna is plugged */
>> attribute Function onantennaavailable;
>>
>> /* Fired when antenna is unplugged */
>> attribute Function onantennaunavailable;

> Do we have phones nowadays that allow you to plug/unplug an antenna? I'm
> not sure I understand why we are showing that.

As Hernan replied, most of the phone use the headphone as the antenna
for FM device.

>
>> /* Fired when FM HW is power on */
>> attribute Function onpoweron;
>>
>> /* Fired when FM HW is power off */
>> attribute Function onpoweroff;

> Couldn't that be handled by the Settings API?

If we defined this in Settings API, the end user have to open settings
to turn on the FM, and then open the FM app to select channel, and back
to settings app to turn off the FM, it is not a good experience.

>> /* Cancel seek action */
>> DOMRequest cancelSeek();

> Why not DOMRequest could be SeekRequest with a .cancel() method?

To me, the SeekRequest.cancel() means to stop the request which may
still be waiting for response, the "cancelSeek" means to tell FM device
to cancel the seeking action, the concepts are not quite the same.

>
>> /* FM media API */
>> DOMString getFmURI();

> As Henri, I'm not sure what that is...

It is like the navigator.mozCamera.getCameraURI, we can get the media
stream uri for FM device, and set it as the source of an audio element,
so the FM app will be able to record the sound and draw images of the
sound etc.
>
> Cheers,
> --
> Mounir

[Pin Zhang]

Hi, Philipp, thanks for your comments, i will update the IDL

[Pin Zhang]

Hi, Philipp, thanks for your comments, i will update the IDL

On Wednesday, May 30, 2012 1:46:30 AM UTC+8, Hernan Rodriguez Colmeiro wrote:

On Wednesday, May 30, 2012 1:46:30 AM UTC+8, Hernan Rodriguez Colmeiro wrote:

[pzhang]

There is an interface for media stream:

/* FM media API */
DOMString getFmURI()

Is this what you want?

Howerver, Philipp and Gervase think that this interface should be
defined outside the API, may be in the webRTC.

-----
Pin Zhang<http://firefox.com.cn/>

>> Based on these features, here are the api descriptions:
>> interface FM : EventTarget
>> {
>> /* Indicate if FM is on */
>> readonly attribute boolean isOn;
>>

>> /* Indicate if antenna is available */
>> readonly attribute boolean isAntennaAvailable;
>>

>> /* Fired when antenna is plugged */
>> attribute Function onantennaavailable;
>>
>> /* Fired when antenna is unplugged */
>> attribute Function onantennaunavailable;
>>

>> /* Fired when FM HW is power on */
>> attribute Function onpoweron;
>>
>> /* Fired when FM HW is power off */
>> attribute Function onpoweroff;
>>

>> /* Cancel seek action */
>> DOMRequest cancelSeek();
>>

>> /* FM media API */
>> DOMString getFmURI();
>> }
>>

[Chris Jones]

----- Original Message -----
> From: "pzhang" <pzh...@mozilla.com>
> To: "Chris Jones" <cjo...@mozilla.com>
> Cc: mozilla-d...@lists.mozilla.org
> Sent: Tuesday, May 29, 2012 8:29:47 PM
> Subject: Re: WebFM API proposals
>
> There is an interface for media stream:
> /* FM media API */
> DOMString getFmURI() Is this what you want?
>

This was just a hack made for the camera prototype. That's not how the "real" MediaStreams API works: it allocates actual objects.

> Howerver, Philipp and Gervase think that this interface should be
> defined outside the API, may be in the webRTC.
>

I'm not sure whether a radio interface has any usefulness apart from the playback stream. If so, maybe the API here should *be* that stream, the controls etc. for the content of the stream.

Cheers,
Chris

>
> -----
> Pin Zhang

[Lars Knudsen]

Hi Chris,

I would agree.

Having a specific separate FM API also seems a bit odd to me. Surely, if
we want to support different "mono-directional audio sources using
antennas", it would make sense to

1. put it under something media related (I might agree with you on the
MediaStream subtye - have to dig a bit and make some protos to try it out)
2. consider OTHER similar sources, e.g. satellite radio, encrypted radio,
...even walkie-talkies and internet radio could be considered.

- Lars

PS It seems that there are MANY specific APIs coming from Mozilla at the
moment - almost as if the web standards have to suffer from some product
being rushed through :-s

[Mounir Lamouri]

On 05/29/2012 07:46 PM, Hernan Rodriguez Colmeiro wrote:
> On Tue, May 29, 2012 at 2:28 PM, Mounir Lamouri <mou...@lamouri.fr> wrote:

>>> /* Fired when antenna is plugged */
>>> attribute Function onantennaavailable;
>>>
>>> /* Fired when antenna is unplugged */
>>> attribute Function onantennaunavailable;
>>

>> Do we have phones nowadays that allow you to plug/unplug an antenna? I'm
>> not sure I understand why we are showing that.
>
> On most phones, the headphones act as the antenna for the FM Radio, so
> if it's not connected the radio doesn't work. The UI at least needs to
> know the status of the antenna to warn the user.

When you say that, you only mean that most phones requires you to have
head phones plugged to be able to run radio, right? How is that related
to an antenna?

--
Mounir

[Mounir Lamouri]

On 05/30/2012 05:03 AM, pzhang wrote:
>>> /* Indicate if antenna is available */
>>> readonly attribute boolean isAntennaAvailable;
>>>

>>> /* Fired when antenna is plugged */
>>> attribute Function onantennaavailable;
>>>
>>> /* Fired when antenna is unplugged */
>>> attribute Function onantennaunavailable;
>> Do we have phones nowadays that allow you to plug/unplug an antenna? I'm
>> not sure I understand why we are showing that.

> As Hernan replied, most of the phone use the headphone as the antenna
> for FM device.

I'm not sure how a headphone can be considered as an antenna, really.
Needing headphones being plugged and needing an antenna are two
different things AFAICT.

>>> /* Fired when FM HW is power on */
>>> attribute Function onpoweron;
>>>
>>> /* Fired when FM HW is power off */
>>> attribute Function onpoweroff;

>> Couldn't that be handled by the Settings API?
> If we defined this in Settings API, the end user have to open settings
> to turn on the FM, and then open the FM app to select channel, and back
> to settings app to turn off the FM, it is not a good experience.

Using the Settings API doesn't mean using the Settings app...

>>> /* Cancel seek action */
>>> DOMRequest cancelSeek();

>> Why not DOMRequest could be SeekRequest with a .cancel() method?
> To me, the SeekRequest.cancel() means to stop the request which may
> still be waiting for response, the "cancelSeek" means to tell FM device
> to cancel the seeking action, the concepts are not quite the same.

And the request is to seek, right? I don't see how that is different.

Cheers,
--
Mounir

[Lars Knudsen]

On Wed, May 30, 2012 at 3:06 PM, Mounir Lamouri <mou...@lamouri.fr> wrote:

> On 05/30/2012 05:03 AM, pzhang wrote:
> >>> /* Indicate if antenna is available */
> >>> readonly attribute boolean isAntennaAvailable;
> >>>
> >>> /* Fired when antenna is plugged */
> >>> attribute Function onantennaavailable;
> >>>
> >>> /* Fired when antenna is unplugged */
> >>> attribute Function onantennaunavailable;
> >> Do we have phones nowadays that allow you to plug/unplug an antenna? I'm
> >> not sure I understand why we are showing that.
> > As Hernan replied, most of the phone use the headphone as the antenna
> > for FM device.
>
> I'm not sure how a headphone can be considered as an antenna, really.
> Needing headphones being plugged and needing an antenna are two
> different things AFAICT.
>

The wire acts as an antenna - a few devices can receive radio without this
because of some built in antenna.

BTW: Should the AM radio API be a separate one if it's introduced? (I know
I am trolling a bit here - I just think it would be a good idea to take a
step back and look at many different cases to make the API solid and future
proof)

>
> >>> /* Fired when FM HW is power on */
> >>> attribute Function onpoweron;
> >>>
> >>> /* Fired when FM HW is power off */
> >>> attribute Function onpoweroff;
> >> Couldn't that be handled by the Settings API?
> > If we defined this in Settings API, the end user have to open settings
> > to turn on the FM, and then open the FM app to select channel, and back
> > to settings app to turn off the FM, it is not a good experience.
>
> Using the Settings API doesn't mean using the Settings app...
>
> >>> /* Cancel seek action */
> >>> DOMRequest cancelSeek();
> >> Why not DOMRequest could be SeekRequest with a .cancel() method?
> > To me, the SeekRequest.cancel() means to stop the request which may
> > still be waiting for response, the "cancelSeek" means to tell FM device
> > to cancel the seeking action, the concepts are not quite the same.
>
> And the request is to seek, right? I don't see how that is different.
>
> Cheers,
> --
> Mounir