WebLiveHub 技術インサイト

チェックリスト

• 一度 relay を強制： 一時的に iceTransportPolicy: 'relay' で TURN 経路を確認。
• relay candidate を確認： candidate 文字列をログし、typ relay を探す。
• 認証方式を混ぜない： static user/pass と期限付き（TURN REST）を混在させない。
• 時刻ズレ： 期限付き credential は時計ずれで失敗しやすい。
• WebView だけ失敗する場合： 診断として TURN over TCP/TLS も試す。

擬似コード：relay 強制 + candidate type のログ（標準 WebRTC API）

// PSEUDO-CODE (not WLSDK)
const pc = new RTCPeerConnection({
  iceServers: [
    {
      urls: 'turn:turn.example.com:3478',
      username: '<USERNAME>',
      credential: '<CREDENTIAL>',
    },
  ],
  iceTransportPolicy: 'relay',
});

pc.onicecandidate = (e) => {
  if (!e.candidate) return;
  const c = e.candidate.candidate;
  if (c.includes(' typ relay ')) console.log('relay', c);
};

プロダクトにライブ配信を埋め込むなら、まずは 統合ガイド（PHP SDK） の最小構成から。開発者アクセスが必要なら SDK を申請。

チェックリスト

• candidate を全部ログ： host だけか、srflx/relay も出ているか確認。
• UDP egress： STUN が通らない環境でもエラーにならずに “出ない” ことがあります。
• TURN をコントロールに： relay は出るが srflx が出ないなら STUN 経路が怪しい。
• 最小 repro： 本番と同じ環境で candidate 収集だけをする最小ページを用意。

擬似コード：ICE candidate の種類をログ（標準 WebRTC API）

// PSEUDO-CODE (not WLSDK)
pc.onicecandidate = (e) => {
  if (!e.candidate) return;
  const c = e.candidate.candidate;
  if (c.includes(' typ host ')) console.log('host', c);
  if (c.includes(' typ srflx ')) console.log('srflx', c);
  if (c.includes(' typ relay ')) console.log('relay', c);
};

埋め込み配信の baseline を整えるなら、まずは 統合ガイド（PHP SDK） の最小構成から。開発者アクセスが必要なら SDK を申請。

チェックリスト

• SDP を両方保存： 失敗ケースの offer/answer を丸ごと保存。
• fingerprint を確認： a=fingerprint と a=setup の整合性を見る。
• SDP 書き換えに注意： signaling 層や proxy が必要な行を落とすことがあります。
• 相互運用： WHIP/FFmpeg/SFU 等を噛ませる場合、DTLS-SRTP（SDES ではない）を再確認。
• 変数を減らす： まずは audio だけなど m-line を最小にして再現。

擬似コード：offer/answer SDP をダンプ（標準 WebRTC API）

// PSEUDO-CODE (not WLSDK)
function dump(label, desc) {
  console.log(label, desc.type);
  console.log(desc.sdp);
}

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
dump('local', pc.localDescription);

// signaling 経由で `answer` を受け取った後
await pc.setRemoteDescription(answer);
dump('remote', pc.remoteDescription);

統合の baseline を保つなら、まずは 統合ガイド（PHP SDK）。開発者アクセスが必要なら SDK を申請。

チェックリスト

• ユーザー操作の後に再生： click 後に再生、muted と音量も確認。
• デバイス列挙： enumerateDevices() で audiooutput を確認。
• setSinkId の有無： 環境によって未実装のため、存在チェック必須。
• devicechange： Bluetooth/有線の切替をハンドリング。
• 最小再現： remote track + <audio> だけで確認。

擬似コード：出力デバイス列挙 + setSinkId（対応時）

// PSEUDO-CODE (not WLSDK)
async function listAudioOutputs() {
  const devices = await navigator.mediaDevices.enumerateDevices();
  return devices.filter((d) => d.kind === 'audiooutput');
}

async function setOutput(audioEl, deviceId) {
  if (typeof audioEl.setSinkId !== 'function') {
    console.warn('setSinkId is not supported');
    return;
  }
  await audioEl.setSinkId(deviceId);
}

プロダクトにライブ配信を埋め込むなら、まずは 統合ガイド（PHP SDK） の最小構成から。開発者アクセスが必要なら SDK を申請。

チェックリスト

• 状態をログ： renegotiation 周辺の signalingState/connectionState/iceConnectionState を保存。
• SDP の m-line 順を diff： 成功/失敗それぞれの SDP を保存し、m= セクション順序を比較。
• transceiver を安定化： audio/video transceiver は固定順で一度だけ作成し、replaceTrack() を優先。
• offer を直列化： 複数の negotiationneeded で offer が同時進行しないよう gate を置く。
• Perfect Negotiation： polite/impolite + ignoreOffer で offer collision を一貫処理。

擬似コード：Perfect Negotiation（標準 WebRTC API）

let makingOffer = false;
let ignoreOffer = false;
const polite = true;

pc.onnegotiationneeded = async () => {
  try {
    makingOffer = true;
    await pc.setLocalDescription();
    sendSignal({ description: pc.localDescription });
  } finally {
    makingOffer = false;
  }
};

onSignal(async ({ description, candidate }) => {
  if (description) {
    const offerCollision =
      description.type === 'offer' &&
      (makingOffer || pc.signalingState !== 'stable');

    ignoreOffer = !polite && offerCollision;
    if (ignoreOffer) return;

    await pc.setRemoteDescription(description);

    if (description.type === 'offer') {
      await pc.setLocalDescription();
      sendSignal({ description: pc.localDescription });
    }
  } else if (candidate) {
    try {
      await pc.addIceCandidate(candidate);
    } catch (e) {
      if (!ignoreOffer) throw e;
    }
  }
});

プロダクトにライブ配信を埋め込むなら、まずは 統合ガイド（PHP SDK） の最小構成から。開発者アクセスが必要なら SDK を申請。

チェックリスト

• 小さく始める： 16–64KB chunk から開始。
• 送信を gate： dc.bufferedAmount と bufferedamountlow で制御。
• 状態確認： dc.readyState === 'open' の時だけ送信。
• 受信側メモリ： 逐次処理し、巨大データを RAM に溜め込まない。

擬似コード：bufferedAmount backpressure（標準 WebRTC API）

const CHUNK = 64 * 1024;
async function sendFile(dc, buf) {
  dc.bufferedAmountLowThreshold = 1024 * 1024;

  for (let i = 0; i < buf.byteLength; i += CHUNK) {
    while (dc.bufferedAmount > dc.bufferedAmountLowThreshold) {
      await once(dc, 'bufferedamountlow');
    }
    dc.send(buf.slice(i, i + CHUNK));
  }
}

function once(dc, evt) {
  return new Promise((r) =>
    dc.addEventListener(evt, () => r(), { once: true })
  );
}

埋め込み配信の baseline を作るなら、まずは 統合ガイド（PHP SDK）。開発者アクセスが必要なら SDK を申請。

症状：track はあるがデコードできない

「Chrome では動くのに Safari/iOS で黒い」「PC は OK だが一部 Android で NG」などの形で現れます。接続自体は確立していても、ネゴシエーションされた H.264 プロファイルを decoder が拒否している可能性があります。

チェックリスト

• SDP を保存： うまくいくケース／失敗するケースそれぞれの offer と answer を保存。
• H.264 の payload type を特定： a=rtpmap:<pt> H264/90000 を探して <pt> を控える。
• fmtp を比較： a=fmtp:<pt> ... の profile-level-id / packetization-mode / level-asymmetry-allowed を比較。
• プロファイルを合わせる： encoder を制御できるなら、プラットフォーム間で互換のある H.264 プロファイルに揃える（A/B として VP8 等に切替えて、原因が codec negotiation か確認するのも有効）。
• fmtp を壊さない： SDP を書き換える proxy/SFU/signaling 層が、H.264 パラメータを削除・改変していることがあります。

プロダクトにライブ配信を埋め込むなら、再現手順を最小化して観測可能にするのが近道です。まずは 統合ガイド（PHP SDK） の最小構成から始め、差分が見える状態になってから複雑さを足してください。開発者アクセスが必要なら SDK を申請。

症状：track はあるがフレームが来ない

ontrack は発火するのに、video が黒いまま、ということがあります。これは RTP が実際には流れていない（またはネットワーク上で到達できない候補経路を選んでいる）ケースで起きます。

チェックリスト

• ICE 状態を確認： iceConnectionState をログし、connected/completed になった瞬間の状態を保存。
• 選択された candidate pair を確認： Firefox では about:webrtc で選ばれた local/remote candidate を確認。
• 候補に .local があるか： これは mDNS host candidate の可能性があります。LAN/AP 構成によっては mDNS が解決できず「接続したのにメディアが来ない」状態になります。
• ホットスポットで A/B： ホットスポットは OK、社内 Wi‑Fi は NG なら、ほぼネットワーク経路 / 名前解決 / firewall の問題です。
• テストで relay-only： WebRTC 層を制御できるなら、一時的に relay-only（iceTransportPolicy: 'relay'）にして TURN relay 経路で症状が消えるか確認。

プロダクトにライブ配信を埋め込むなら、再現可能な baseline を維持するのが最優先です。まずは 統合ガイド（PHP SDK） の最小構成から始め、観測できるようになってから段階的に拡張してください。開発者アクセスが必要なら SDK を申請。

統合ガイドに明記されている内容

統合ガイドでは、プレイヤーが対応する言語コードとして en, ja, zh-Hant, zh-Hans, vi を列挙しています。lang を指定しない場合、WLSDK は実行環境の言語を読み取り、利用できない場合は en にフォールバックします。

例：プレイヤーUIを日本語に固定する

<?php
echo WLSDK::iframe([
  'hostLabel' => 'connect',
  'streamer'  => '<STREAMER_USER_ID>',
  'lang'      => 'ja',
]);
?>

詳細は 統合ガイド → “Multi-language integration (optional)”。開発者アクセスが必要な場合は SDK を申請 してください。

ダッシュボードは最初に読み込みすぎやすい

ページで多数のライブビューを一度に描画すると、ロード時点で複数のプレイヤーを同時に初期化してしまいがちです。大半が画面外なら、最初から全部を初期化する必要はありません。

統合ガイドの “Multiple Iframes Lazy Loading” パターンを使う

統合ガイドには WLSDK::lazyIframe() を使った複数 iframe の例があります。呼び出しは最小限にして、明確に記載されているパラメータだけを渡してください。

<!-- ループ内 -->
<?php foreach ($activeStreamers as $streamerId): ?>
  <div class="stream-wrapper">
    <?php
      echo WLSDK::lazyIframe([
        'hostLabel' => 'connect',
        'streamer'  => $streamerId,
      ]);
    ?>
  </div>
<?php endforeach; ?>

詳細は 統合ガイド → “Multiple Iframes Lazy Loading”。

「簡単」に見えて後で壊れる

ブラウザ側だけで録画すると、運用で次が起きやすいです。

• シーク不可: WebM が duration/seek テーブル無しで出力されることがある。
• データ消失: タブクラッシュ/リロードで RAM 上のバッファが消える。
• VFR: 負荷でフレーム落ち → 音声と映像がずれる。

堅牢な解決策: サーバー側で録画/合成

サーバー側で合成・録画すれば CPU/ネットワークを制御しやすく、運用の再現性も上がります。SDK を検討している場合は、申請 の際に録画要件（保存先/フォーマット/保持期間など）を共有し、対応範囲を確認してください。

症状: 映像が固まる

ネットワークが切替わると IP が変わります。既存の UDP パスが無効になり、映像が止まることがあります。

対策: ICE Restart

iceConnectionState を監視し、disconnected / failed になったら ICE Restart を実行します。

pc.createOffer({ iceRestart: true })

これで 4G 側の新しい候補を集め直して、メディアトラックを維持したまま復旧できます。

埋め込み配信を運用するなら、再接続は自分の状態管理（ICE restart + UI）として設計するのが安全です。まずは 統合ガイド の最小構成をベースに、要件に合わせて拡張してください。

症状とクイックチェック

ICE Connection Failed / candidate gathering 停滞は、ほぼネットワーク経路（firewall/NAT）か TURN 設定の問題です。

最低限の設定

• STUN/TURN: TURN を必ず用意（STUN のみは危険）。
• UDP 3478: 標準ポート。ただし企業網で UDP が塞がれていることも多い。
• TCP 443 フォールバック: UDP がダメでも通りやすい TURNS を用意する。

Symmetric NAT は P2P の敵

Symmetric NAT では直結が失敗しがちです。TURN 経由リレー を前提に設計しましょう。

TURN の運用が負担なら、マネージド TURN の利用を検討してください。選定時（または SDK を申請 する時）に、どのネットワーク要素が含まれるか／制限は何かを確認しておくと安心です。

実用的な方法：バックエンドで embed を生成する

フロントエンドに player URL や認証情報を埋め込むのは避けましょう。バックエンドで embed HTML を生成して、ログイン済みユーザーに返す構成にすると、秘密情報をサーバー側に閉じ込めつつ、アクセス制御も一箇所で管理できます。

<?php
// WebLiveHub SDK class
require_once __DIR__ . '/vendor/autoload.php';
use WebLiveHub\SDK\WLSDK;

// SDK configuration
WLSDK::setup([
    'hb_endpoint' => getenv('WL_HOSTED_BACKEND_URL') ?: '<HOSTED_BACKEND_ENDPOINT>',
    'user_id' => '<AUTH_USER_ID>',
    'password' => '<AUTH_PASSWORD>'
]);
?>

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <?php echo WLSDK::script(); ?>
</head>
<body>
  <?php
    echo WLSDK::iframe([
      'hostLabel' => 'connect',
      'streamer'  => '<STREAMER_USER_ID>',
      'attrs' => [ 'id' => 'stream-container', 'class' => 'wlh-stream', 'style' => 'border-radius:6px;' ]
    ]);
  ?>
</body>
</html>

SDK は <iframe> の embed を出力します。attrs で標準の HTML 属性を渡し、Autoplay/権限周りはターゲットブラウザ（特に iOS/Safari）で必ず動作確認してください。

SDK を使う理由

• バックエンド起点: 長期の認証情報をサーバーに置いたまま、ログインユーザーにだけ embed を返せます。
• 堅実な baseline: 統合ガイド（setup → script → iframe）を土台にして、必要な要件を追加できます。

👉 SDK を申請

最初に baseline を揃えると、切り分けが速くなる

「映らない/音が出ない」は環境要因が多いです。まず条件を揃えてからデバッグしましょう。

ブラウザ/端末

• まず Chrome/Edge で検証（次に Safari/iOS）。
• カメラ/マイク権限とデバイスの存在を確認。
• シークレットで拡張の影響を除外。

配信/ネットワーク

• HTTPS 必須（ローカルは localhost 可）。
• 社内ネットワークが UDP を制限することがあるため、モバイル回線で比較。

再生

• Autoplay 制限を前提に、クリックで開始。
• 出力デバイス/ミュート/音量を確認。

次：統合ガイド（PHP SDK） の最小構成で検証。必要なら SDK を申請。

媒体 → 接続 → 再生 の順で切り分ける

闇雲に試すのではなく、状態を観測できる形にします。

1) 媒体

• 権限は許可されているか？
• 別端末で再現するか（ハード/ドライバ要因の除外）。

2) 接続

• 社内ネットワークで不安定なら、モバイル回線で比較。

3) 再生

• クリック開始で Autoplay 制限を回避。
• 出力デバイスの取り違え（Bluetooth 等）を確認。

一度で十分な診断情報

• Chrome：chrome://webrtc-internals の export/スクショ。
• 発生時刻、ブラウザ/OS、ネットワーク。

次：統合ガイド（PHP SDK） と照合して baseline を作ります。

「Chrome はOK、iPhone はNG」が起きやすい理由

iOS は権限と foreground/background が厳しめです。テスト手順を固定化しましょう。

おすすめ手順

• 開始は必ずユーザークリックに紐付ける。
• バックグラウンド→復帰で回復できるか確認。
• 同条件で 3 回繰り返す（断続的な不具合検出）。

報告に必要な情報

• iPhone 機種、iOS/Safari バージョン
• Bluetooth 使用有無
• 低電力モード

次：統合ガイド（PHP SDK） の最小構成で iOS baseline を作ります。

「カクつく」を数値に分解する

原因は loss/jitter/bitrate/端末負荷などの組み合わせです。

見るべき 5 指標

• Packet loss
• Jitter
• Bitrate
• Frames dropped / decode time
• End-to-end latency

取得方法

• Chrome：chrome://webrtc-internals。
• 同条件で 3 回測って比較。

次：統合ガイド（PHP SDK） 完了後、品質 baseline を作ります。

SPA の落とし穴：画面は変わっても処理は残る

イベント/timer を片付けないと、二重接続やメモリ増加の原因になります。

基本ルール

• mount で登録
• unmount で解除（removeEventListener/clearInterval/リソース解放）
• 再接続は状態管理で多重実行を防ぐ

追加で見るイベント

• visibilitychange
• pagehide

次：統合ガイド（PHP SDK） と照合し、初期化とクリーンアップを対にします。