I have received a lot of comments, thank you guys! Based on the
feedbacks, I made some changes:
- renamed "isOn" to "enabled", just like other APIs
- collapsed "onpoweron" and "onpoweroff" into "onpowerchanged", here
is the sample code:
/navigator.fm.onpowerchanged = function() {
var enabled = navigator.fm.enabled;
// change the style of switch element
document.getElementById('switch').className = enabled ?
"switch-on" : "switch-off";
};/
- collapsed "onantennaavailable" and "onantennaunavailable" into
"onantennachanged", here is the sample code:
/navigator.fm.onantennachanged = function() {
if (navigator.fm.antennaAvailable) {
// warn user
showWarnMessage("Check the antenna please.");
} else {
hideWarnMessage();
}
};/
- added the readonly attribute "frequency", here is the sample code:
navigator.fm.onfrequencychanged = function() {
var frequency = navigator.fm.frequency;
// Update the UI element
updateUIFrequency(navigator.fm.frequency);
};
- changed the type of frequency to double, and the unit is MHZ
- removed the interface "getFmURI". It is probably to be implemented
as a subtype of MediaStream[4], it is not necessary to keep this.
here is the updated IDL:
interface FM : EventTarget
{
/* Indicate if FM is power on or off */
readonly attribute boolean enabled;
/* Indicate if antenna is available or not */
readonly attribute boolean antennaAvailable;
/* Current frequency, the unit is MHZ. The value will be 0 or the
last frequency if FM is not enabled. */
readonly attribute double frequency;
/* Fired when the power status of FM HW is changed */
attribute Function onpowerchanged;
/* Fired when the state of antenna is changed */
attribute Function onantennachanged;
/* Fired when FM frequency is changed. */
attribute Function onfrequencychanged;
/* Power on/off the FM device, onpowerchanged will be fired
accordingly */
DOMRequest setEnabled(in bool enabled);
/*
onsuccess will be triggered if frequency is set successfully.
The frequency may not be the value passed, for example: the frequency
is out of the range, app should listen on the "onfreqchanged" to get
the right frequency.
*/
DOMRequest setFrequency(in double frequency);
/*
Tell FM to seek up, if frequency is changed, onfrequencychanged will
be triggered.
*/
DOMRequest seekUp();
/*
Tell FM to seek down, if frequency is changed, onfrequencychanged
will be triggered.
*/
DOMRequest seekDown();
/* Cancel seek action */
DOMRequest cancelSeek();
}
There are still some concerns:
- Should this API cover AM/HD/DAB etc.? (McCormac & Lars)
Maybe we should consider the AM, though i haven't seen any AM app
on mobile phone, there is some chips support both FM and AM.
- Should the interfaces related to power be defined in setttings API
? (Mounir)
Other APIs like wifi, they also have setEnabled interface, it is
a kind of conversion as Philipp said.
- How about the SeekRequest.cancel() instead of cancelSeek() ? (Mounir)
Let's start a new thread from here. Any comments or suggestions are
welcomed!
[4]:
http://dev.w3.org/2011/webrtc/editor/getusermedia.html
On Monday, May 21, 2012 10:43:00 PM UTC+8, 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
>
> 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