非標準
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

This API is available on Firefox or Firefox OS for installed or higher privileged applications.

摘要

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();
  }
})

注意:透過裝置上的可用 normal 音訊通道,即可輸出音訊。

切換不同頻率

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

手動切換

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

  • 頻率必須落在 FMRadio.frequencyLowerBoundFMRadio.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 組函式在到達 frequencyLowerBoundfrequencyUpperBound 的值之後,均將再次循環較高/較低頻率。一旦找到新頻道,就會更改目前頻率並發出 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');
});

規格

尚無任何規格。

另可參閱

文件標籤與貢獻者

此頁面的貢獻者: MashKao
最近更新: MashKao,