mozilla

Revision 360554 of FMRadio

  • Revision slug: DOM/WebFM
  • Revision title: WebFM
  • Revision id: 360554
  • Created:
  • Creator: jlebar
  • Is current revision? No
  • Comment

Revision Content

The WebFM API provides access to the device FM radio. This interface lets you turn the FM radio on and off and tune it to different stations.

Entry point

if (navigator.mozFMRadio)
  navigator.mozFM.enable();

API

interface FM : EventTarget {
   readonly attribute boolean enabled;
   readonly attribute boolean antennaAvailable;
   readonly attribute double frequency;
   readonly attribute double frequencyUpperBound;
   readonly attribute double frequencyLowerBound;
   readonly attribute double channelWidth;

   attribute Function onantennaavailablechange;
   attribute Function onfrequencychange;
   attribute Function onenabled;
   attribute Function ondisabled;

   DOMRequest enable(double frequency);
   DOMRequest disable();
   DOMRequest setFrequency(double frequency);
   DOMRequest seekUp();
   DOMRequest seekDown();
   DOMRequest cancelSeek();
}

Attributes

enabled
Indicates whether the radio is playing
antennaAvailable
Indicate if an antenna is plugged and available
frequency
Current radio frequency.
frequencyUpperBound
Maximum frequency up to which the seek method searches for radio stations
frequencyLowerBound
Minimum frequency down to which the seek method searches for radio stations
channelWidth
The channel width of the ranges of frequency, in MHz. Usually, the value is one of: 0.05, 0.1 (default) or 0.2.
When a frequency is assigned, it will be rounded to the closest frequency given the channelWidth. For example, if 100Mz is a valid frequency and the channelWidth is 0.2, 100.2, 99.8 will be valid frequencies, but 100.15 will be rounded to 100.2.

Methods

enable(frequency)
Turns on the radio on the given frequency. This function throws if called with no argument. Returns a DOMRequest for the success or error of the operation.
disable()
Turns the radio off. Returns a DOMRequest which success indicates that the radio has properly been disabled
setFrenquecy(frequency)
Asynchronously changes the radio frequency. The value has to be between frequencyLowerBound and frequencyUpperBound. Trying to set outside the bounds results in an error.
Returns a DOMRequest which success indicates the frequency has properly been changed.
seekUp()
Asks the radio to find a new frequency (greater than the current one). If one is successfully found, a frequencychange event is fired. Returns a DOMRequest which success indicates that the search has started.
seekDown()
Same as above, but searching in frequencies lower than the current one.
cancelSeek()
Cancels the radio seek if one was happening. Returns a DOMRequest which success indicates that the frequency search has been cancelled.

Events

enabled
Triggered when the radio has been turned on
disabled
Triggered when the radio has been turned off
antennaavailablechange
Triggered when an antenna is plugged or unplugged
frequencychange
Triggered whenever the radio frequency is changed

See also

Gaia radio app

Revision Source

<p>The WebFM API provides access to the device FM radio. This interface lets you turn the FM radio on and off and tune it to different stations.</p>
<h2 id="Syntax" name="Syntax">Entry point</h2>
<pre class="eval">
<span class="nx">if (navigator.mozFMRadio)
  navigator</span><span class="p">.</span><span class="nx">mozFM.enable()</span>;
</pre>
<h2 id="API">API</h2>
<pre>
interface FM : EventTarget {
&nbsp; &nbsp;readonly attribute boolean enabled;
&nbsp; &nbsp;readonly attribute boolean antennaAvailable;
&nbsp; &nbsp;readonly attribute double frequency;
   readonly attribute double frequencyUpperBound;
   readonly attribute double frequencyLowerBound;
   readonly attribute double channelWidth;

&nbsp; &nbsp;attribute Function onantennaavailablechange;
&nbsp; &nbsp;attribute Function onfrequencychange;
&nbsp; &nbsp;attribute Function onenabled;
&nbsp; &nbsp;attribute Function ondisabled;

&nbsp; &nbsp;DOMRequest enable(double frequency);
&nbsp; &nbsp;DOMRequest disable();
&nbsp; &nbsp;DOMRequest setFrequency(double frequency);
&nbsp; &nbsp;DOMRequest seekUp();
&nbsp; &nbsp;DOMRequest seekDown();
&nbsp; &nbsp;DOMRequest cancelSeek();
}</pre>
<h3 id="Attributes">Attributes</h3>
<dl>
  <dt>
    enabled</dt>
  <dd>
    Indicates whether the radio is playing</dd>
  <dt>
    antennaAvailable</dt>
  <dd>
    Indicate if an antenna is plugged and available</dd>
  <dt>
    frequency</dt>
  <dd>
    Current radio frequency.</dd>
  <dt>
    frequencyUpperBound</dt>
  <dd>
    Maximum frequency up to which the <code>seek</code> method searches for radio stations</dd>
  <dt>
    frequencyLowerBound</dt>
  <dd>
    Minimum frequency down to which the <code>seek</code> method searches for radio stations</dd>
  <dt>
    channelWidth</dt>
  <dd>
    The channel width of the ranges of frequency, in MHz. Usually, the value is one of: <code>0.05</code>, <code>0.1</code> (default) or <code>0.2</code>.</dd>
  <dd>
    When a frequency is assigned, it will be rounded to the closest frequency given the channelWidth. For example, if 100Mz is a valid frequency and the channelWidth is 0.2, 100.2, 99.8 will be valid frequencies, but 100.15 will be rounded to 100.2.</dd>
</dl>
<h3 id="Methods">Methods</h3>
<dl>
  <dt>
    enable(frequency)</dt>
  <dd>
    Turns on the radio on the given frequency. This function throws if called with no argument. Returns a DOMRequest for the success or error of the operation.</dd>
  <dt>
    disable()</dt>
  <dd>
    Turns the radio off. Returns a DOMRequest which success indicates that the radio has properly been disabled</dd>
  <dt>
    setFrenquecy(frequency)</dt>
  <dd>
    Asynchronously changes the radio frequency. The value has to be between <code>frequencyLowerBound</code> and <code>frequencyUpperBound</code>. Trying to set outside the bounds results in an error.</dd>
  <dd>
    Returns a DOMRequest which success indicates the frequency has properly been changed.</dd>
  <dt>
    seekUp()</dt>
  <dd>
    Asks the radio to find a new frequency (greater than the current one). If one is successfully found, a <code>frequencychange</code> event is fired. Returns a DOMRequest which success indicates that the search has started.</dd>
  <dt>
    seekDown()</dt>
  <dd>
    Same as above, but searching in frequencies lower than the current one.</dd>
  <dt>
    cancelSeek()</dt>
  <dd>
    Cancels the radio seek if one was happening. Returns a DOMRequest which success indicates that the frequency search has been cancelled.</dd>
</dl>
<h3 id="Events">Events</h3>
<dl>
  <dt>
    enabled</dt>
  <dd>
    Triggered when the radio has been turned on</dd>
  <dt>
    disabled</dt>
  <dd>
    Triggered when the radio has been turned off</dd>
  <dt>
    antennaavailablechange</dt>
  <dd>
    Triggered when an antenna is plugged or unplugged</dd>
  <dt>
    frequencychange</dt>
  <dd>
    Triggered whenever the radio frequency is changed</dd>
</dl>
<h2 id="See_also">See also</h2>
<p><a href="https://github.com/mozilla-b2g/gaia/tree/master/apps/fm" title="https://github.com/mozilla-b2g/gaia/tree/master/apps/fm">Gaia radio app</a></p>
Revert to this revision