WebFM API

概要

WebFM API は、端末の FM ラジオへのアクセスを提供します。これは、ラジオの ON/OFF とラジオ局の切り替え、周波数のチューニングができます。この API は、FMRadio オブジェクトの navigator.mozFMRadio プロパティを通じて利用できます。

ラジオの ON/OFF を切り替える

基本的に、ラジオは FMRadio.enable() メソッドで ON に切り替え、FMRadio.disable() メソッドで OFF に切り替えます。

ラジオを ON にする前に、アンテナが使用可能か確認することが賢明です (アンテナ無しでは端末に搭載されたラジオが信号を受信できません)。この情報は、FMRadio.antennaAvailable プロパティ経由で利用可能です。モバイル端末上では、ヘッドフォンケーブルがアンテナとして使用されます。このケーブルは抜き差し可能なため、アンテナの利用可能状態が変化するたびに WebFM API が antennaavailablechange イベントを発行します。

ラジオを ON にするには、ラジオの周波数を指定する必要があります。この周波数 (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(frequency);
} else {
  alert("ヘッドフォンを接続する必要があります");
}

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

周波数の切り替え

周波数の切り替えは、手動または自動でできます。いかなる場合も、端末のラジオに受信される現在のラジオ周波数は、常に FMRadio.frequency プロパティで利用可能です。このプロパティは、MHz 単位の周波数を表す数値です。

周波数の手動設定

FMRadio.setFrequency() メソッドは、受信する新しい周波数を設定するために使用されます。しかし、設定できる値には制限があります。このメソッドは、メソッド呼び出しの成功またはエラーを扱う DOMRequest オブジェクトを返します。周波数は、次の要件を満たさなければなりません:

• 周波数は、FMRadio.frequencyLowerBound および FMRadio.frequencyUpperBound で定義された範囲内でなければなりません。範囲外の周波数が設定されると、エラーが返されます。
• 周波数は、FMRadio.channelWidth の値を基準にしてステップされます。このステップ値を外れた場合、適切に周波数の誤差が丸められます。例えば、100MHz が正しい周波数で、channelWidth の値に 0.2 が設定されていた場合、100.15 の周波数を設定しようとすると、100.2 に丸められた結果が返されます。

var change = radio.setFrequency(frequency);

change.onerror = function () {
  var min = radio.frequencyLowerBound;
  var max = radio.frequencyUpperBound;
  console.warn('周波数は次の範囲内でなければなりません: [' + min + ',' + max + ']');
}

change.onsuccess = function () {
  console.log('周波数に次の値を設定しました: ' + radio.frequency);
}

周波数の自動探索

WebFM API は、ラジオチャンネルを自動的にシークする便利な手段を提供しています。結論から先に言うと、FMRadio.seekUp() (現在よりも高い周波数のラジオチャンネルを見つけるために使用) および FMRadio.seekDown() メソッドを使用します。前者は現在より高い周波数のラジオチャンネルを見つけるため、後者は低い周波数のラジオチャンネルを見つけるために使用します。これらのメソッドは、各メソッド呼び出しの成功またはエラーを扱う DOMRequest オブジェクトを返します。

両方のメソッドは、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
• Gaia の FM ラジオアプリ