WebFM API

摘要

WebFM API 可存取裝置的 FM 收音機，進而開/關收音機並切換電台。另可透過 navigator.mozFMRadio 屬性 (為 FMRadio 物件) 而存取此 API。

開/關收音機

FMRadio.enable() 函式可開啟收音機；FMRadio.disable() 函式則是關閉收音機。

在開啟收音機之前，應先檢查裝置是否具備天線 (若無天線，內建的收音機當然也收不到訊號)。透過 FMRadio.antennaAvailable 屬性即可獲得天線資訊。行動裝置往往將耳機纜線作為收音機天線。由於使用者可隨時插入/拔除耳機，因此每次只要天線狀態改變，WebFM API 均將發出 antennaavailablechange 事件。

開啟收音機就必須要有可聆聽的頻道。而頻率 (以 MHz 為單位) 將以數字形式傳送至 FMRadio.enable() 函式。

// The frequency of the radio station
// to listen express in MHz
var frequency = 99.1;
var radio = navigator.mozFMRadio;

if (radio.antennaAvailable) {
  radio.enable(frenquency);
} else {
  alert("You need to plug your headphone");
}

radio.addEventListener('antennaavailablechange', function () {
  if (radio.antennaAvailable) {
    radio.enable(frenquency);
  } else {
    radio.disable();
  }
})

切換不同頻率

使用者可手動或讓裝置自動切換頻率。不論是手動或自動，均將透過 FMRadio.frequency 屬性存取目前的收音機頻率。該屬性則以 MHz 呈現頻率。

手動切換

必須以 FMRadio.setFrequency() 函式設定新的頻率，但所能設定的值有某些限制。此函式將回傳 DOMRequest 物件，以處理函式呼叫的成功或錯誤狀態。而頻率必須滿足下列要求：

• 頻率必須落在 FMRadio.frequencyLowerBound 與 FMRadio.frequencyUpperBound 所定義的範圍中。若頻率在此範圍之外，就會產生錯誤。
• 頻率必須根據 FMRadio.channelWidth 的值而變化，否則亦將四捨五入。舉例來說，若 100 Mz 為有效頻率，且 channelWidth 為 0.2 時，則 100.2 與 99.8 將成為有效頻率。但若是 100.15 將四捨五入為 100.2。

var change = radio.setFrequency(frequency);

change.onerror = function () {
  var min = radio.frequencyLowerBound;
  var max = radio.frequencyUpperBound;
  console.warn('The frequency must be within the range [' + min + ',' + max + ']');
}

change.onsuccess = function () {
  console.log('The frequency has been set to ' + radio.frequency);
}

自動搜尋

WebFM API 亦可自動搜尋收音機頻道。我們使用 FMRadio.seekUp() 與 FMRadio.seekDown() 函式。前者將從目前頻道再尋找更高的頻率；後者反之。此 2 組函式均將回傳 DOMRequest 物件，以處理函式呼叫的成功或錯誤狀態。

WebFM API 亦可自動搜尋收音機頻道。我們使用 FMRadio.seekUp() 與 FMRadio.seekDown() 函式。前者將從目前頻道再尋找更高的頻率；後者反之。此 2 組函式均將回傳 DOMRequest 物件，以處理函式呼叫的成功或錯誤狀態。

且此 2 組函式在到達 frequencyLowerBound 或 frequencyUpperBound 的值之後，均將再次循環較高/較低頻率。一旦找到新頻道，就會更改目前頻率並發出 frequencychange 事件。

此 2 組函式並無法同時搜尋，也就是無法同時往上並往下搜尋頻率，否則將發生錯誤。而呼叫 FMRadio.cancelSeek() 函式即可停止搜尋頻率。此函式亦將回傳 DOMRequest 物件。

var radio   = navigator.mozFMRadio;
var seeking = false;
var UP      = document.querySelector("button.up");
var DOWN    = document.querySelector("button.down");

// When the frequency change, the seek
// functions automatically stop to seek.
radio.onfrequencychange = function () {
  seeking = false;
}

function seek(direction) {
  var cancel, search;

  // If the radio is already seeking
  // we will cancel the current search.
  if (seeking) {
    var cancel = radio.cancelSeek();
    cancel.onsuccess = function () {
      seeking = false;

      // Once the radio no longer seek,
      // we can try to seek as expected
      seek(direction);
    }

  // Let's seek up
  } else if (direction === 'up') {
    // Just to be sure that the radio is turned on
    if (!radio.enabled) {
      radio.enable(radio.frequencyLowerBound);
    }
    search = radio.seekUp();

  // Let's seek up
  } else if (direction === 'down' {
    // Just to be sure that the radio is turned on
    if (!radio.enabled) {
      radio.enable(radio.frequencyUpperBound);
    }
    search = radio.seekDown();
  }

  if (search) {
    search.onsuccess = function () {
      // Ok, we are seeking now.
      seeking = true;
    };
    search.onerror = function () {
      // Something goes wrong... ok, let's try again.
      seek(direction);
    }
  }
}

UP.addEventListener('click', function () {
  seek('up');
});

DOWN.addEventListener('click', function () {
  seek('down');
});

規格

尚無任何規格。

另可參閱

• FMRadio
• Gaïa 上的 FM App