libwebrtc ペーサー¶

PacingController::SetPacingRates()¶

PacingController に「パケットの送信ペース（ターゲットビットレート）」を第一引数で指示するためのメソッド。

また第二引数で「パディングパケットの送信レート」を指定することもでき、これが 0 より大きい場合には、 送信ペースに余裕がある場合は、パディングパケットが常に送信されることになる。

PacingController の各処理では、ここで指示された送信ペースが厳守されることになる。 ペース調整は、イメージとしては 経過時間 * 送信ペース - これまでの送信量 = バジェット として、そのバジェットに収まる分だけのパケット送信を許可する形となっている。 この式を見て分かる通り、基本的には「時間経過分だけバジェットが増えて、パケット送信分だけ減る（かつ、プラスの場合にだけ送信できる）」という単純なもの。 なお、実際のコードでは「バジェット（＝ 余裕分）」ではなく「 dept （= 不足分）」として実装されているが、符号の向きが異なるだけで、意味するところはどちらもほぼ同じ。

ただし、いくつか例外もある:

• （デフォルトでは）音声パケットは、送信ペース管理の対象外（常にすぐ送信可能、また、送信分もバジェットから引かれない）
• キューが詰まっている場合には、要素が延々と増えていくことを防止するために、送信ペースを（指示されたものよりも）増加させる
  • 詳細は PacingController::MaybeUpdateMediaRateDueToLongQueue() を参照
• PacingController::SetSendBurstInterval() によってバースト送信が許可されている場合には、一時的に送信ペースを超過することがある
  • ただし、これによって消費されるバジェットの合計が増える訳ではない

なお、本メソッドの呼び出し側に関しては「 PacingController の利用側クラスや呼び出しタイミング」節を参照。

PacingController::EnqueuePacket()¶

送信対象の RTP パケット（ RtpPacketToSend ）を受け取り、それをキューに追加するメソッド。 キューイングされたパケットは PacingController::ProcessPackets() の呼び出し時に、 （ペース調整を満たしたタイミングで）実際に送信される。

メソッドの処理の流れは以下の通り:

1. BitRateProber::OnIncomingPacket() を呼び出して、プローバに送信対象パケットのサイズを教える
   • プローブ関連処理の詳細は「 BitrateProber クラスの詳細」の節を参照
2. キューが空だった場合には、現在時刻を基点にして、バジェットを再計算する:
   • 処理としては UpdateBudgetWithElapsedTime(UpdateTimeAndGetElapsed(現在時刻)); が呼ばれるイメージ:
     • UpdateTimeAndGetElapsed() で、最終処理時刻を現在時刻に設定（返り値が前回の処理時刻からの経過時間）
     • UpdateBudgetWithElapsedTime() で、経過時間を元に送信バジェットを更新する
   • この二つのメソッドの組み合わせは PacingController 内の色々なところで登場する頻出パターン
   • それぞれのメソッドの詳細については、後続のサブセクションを参照
3. キュー（ PacingController::PacketQueue の実装クラス）に RTP パケットを追加
4. キューの要素が増えたので PacingController::MaybeUpdateMediaRateDueToLongQueue() を呼び出して、必要なら送信ペースを増加する（キュー詰まり解消用）

なおユーザが直接生成した RTP パケットだけではなく、 PacingController::ProcessPackets() 呼び出し時に生成される 以下のパケットも、一度キューを経由して送信され、ペース調整の対象となる:

• FEC 用のパケット
• プローブ用のパディングパケット

PacingController::ProcessPackets()¶

キューに格納されているパケット群を PacingController::SetPacingRates() で指定されたペース制約を満たす範囲で送信するメソッド。 その他に、キープアライブやプローブ用のパディングパケットの送信を行なったりもする。

処理の流れ:

1. PacingController::ShouldSendKeepalive() を呼び出して、キープアライブ用のパディングパケットの送信が必要かどうかを判定する
   • PacingController::ShouldSendKeepalive() は大まかには「500ms 以上パケットが送信されていない場合」に、キープアライブが必要と判定する
   • 必要と判定されたら、ペイロードサイズが 1 のパディングパケットが送信される（この場合は PacingController::EnqueuePacket() は経由しない）
2. PacingController::Pause() 呼び出しによって、送信処理が一時停止中になっている場合には、ここで終了
3. PacingController::NextSendTime() で、パケットの次回送信時刻を取得する
   • もし現在時刻が送信時刻に到達していない場合（i.e., 送信バジェット枯渇中）には、ここで終了
4. UpdateTimeAndGetElapsed(次回送信時刻) を呼び出して、「前回の処理実施時刻」から「次回送信時刻」までの経過時間を取得する
   • NOTE: バジェットに余裕がある場合には、次回送信時刻は、現在時刻よりも前になることがある
   • 経過時刻が 0 秒以上なら PacingController::UpdateBudgetWithElapsedTime() を呼び出して、バジェットを更新する（経過時間分だけ送れる量が増える）
5. プローブ中の場合には BitrateProber::RecommendedMinProbeSize() を呼び出して「プローブに必要な送信データサイズ」を取得する
6. 以降で、キュー内のパケットの送信ループ処理に入る
   • 各イテレーションの冒頭では PacingController::GetPendingPacket() によって、次に送信するパケットがキューから取り出される
   • ただし、送信バジェットが枯渇している場合などは、キューに要素が存在しても null が返されることがある（詳細は後述）
   • 「次に送信するパケットがあるかどうか」で処理が分岐する
7. [送信パケットがない場合] 必要に応じて、プローブ用のパディングパケットをキューに追加する
   1. PacingController::PaddingToAdd() でパディングパケットのサイズを計算する
      • パディングパケットの送信が不要な場合には 0 が返され、ここで送信ループを抜ける
   2. PacingController::PacketSender::GeneratePadding() で上記のサイズのパディングパケットを生成する
   3. PacingController::EnqueuePacket() を呼び出して、パディングパケットをキューに追加する
   4. 送信ループの次のイテレーションに進む
8. [送信パケットがある場合] RTP パケットを実際に送信する
   1. PacingController::PacketSender::SendPacket() を呼び出して、パケットを送信する
   2. FEC パケットがある場合には PacingController::PacketSender::FetchFec() で取得して、キューに追加する
   3. PacingController::OnPacketSent() メソッドを呼び出して、（主に）以下を行う
      • 最終送信時刻の更新
      • PacingController::UpdateBudgetWithSentData() を呼び出してバジェットを更新（送信分だけバジェットを減らす）
   4. ループ内で送信したパケットのサイズ合計を更新する
   5. プローブ中の場合には、その合計サイズが「プローブに必要な送信データサイズ」を超過しているかどうかをチェックする
      • 超過している場合には、ここでループを抜ける
      • プローブ中の場合は、一度に送信するデータサイズが、少な過ぎても多過ぎても良くない
   6. PacingController::NextSendTime() を呼び出して、パケットの次回送信時刻を取得する
      • 次回送信時刻が「現在時刻を超えている（バジェットが枯渇した）」かつ「プローブ中ではない」場合には、ここでループを抜ける
   7. UpdateBudgetWithElapsedTime(UpdateTimeAndGetElapsed(次回送信時刻)) を呼び出して、次のイテレーションに備えてバジェットを更新する
9. 送信ループを抜けた後は、プローブ中なら BitRateProber::ProbeSent() を呼び出して、今回送信したデータサイズ合計を BitrateProber に伝える
10. 最後に PacingController::MaybeUpdateMediaRateDueToLongQueue() を呼び出して、以降の送信ペースの調整を行う

PacingController::NextSendTime()¶

パケットの次の送信時刻を決定するためのメソッド。

バジェットが枯渇している場合には、それが回復する予定時刻を返す。 反対にバジェットに余裕がある場合には、現在より前の時刻が返されることがある。

決定の際の流れは以下の通り:

1. PacingController::Pause() が呼ばれており、一時停止中なら「次のキープアライブ時刻」を返す
   • 「次のキープアライブ時刻」は 最後の送信時刻 + 500ms
2. プローブ中の場合には BitrateProber::NextProbeTime() に次回時刻の決定を委譲する
3. 送信キューの先頭が音声パケットの場合には、そのパケットをキューに追加した時刻（つまり過去）を返す
   • 音声パケットは、デフォルトではペース調整の対象外なので、即座に送信される
   • 音声パケットがペース調整の対象に含まれる構成の場合には、この部分の処理はスキップされる
4. 「輻輳発生中」ないし「まだ PacingController::EnqueuePacket() が一度も呼び出されていない」場合には「次のキープアライブ時刻」を返す
   • 「輻輳発生中」かどうかは PacingController::SetCongested() によって、外部から PacingController に伝えられる
   • 輻輳時には、音声パケットやキープアライブ用パディングパケットを除いて、パケット送信は抑制される
5. キューに要素がある場合には、
   1. 負債 / 送信ペース で負債が解消するまで（= 次にパケットが送信可能になるまで）に掛かる時間を求める

      • 「負債」は、バジェットを超過して送信したパケットの合計サイズ（超過しておらずバジェットに余裕がある場合には負数になる）

   2. その時間分を「最後の送信時刻」に加算し、それを次回の送信時刻とする
6. キューが空の場合には、
   • 「 PacingController::SetPacingRates() でパディングパケットの送信レートが指定されている」場合は、そのレートに合わせて次回の送信時刻を決定する
   • それ以外の場合には、「次のキープアライブ時刻」を次回送信時刻とする

PacingController::PaddingToAdd()¶

プローブやその他の目的で使用するパディングパケットのサイズを決定するメソッド。

決定方法:

• 送信キューが空ではないなら、パディングサイズは 0 （パディングではなく実際のパケットを送るべきなので）
• 輻輳中ならパディングサイズは 0 （ネットワークに負荷をかけたくない）
• PacingController::EnqueuePacket() が一度も呼び出されていないなら、パディングサイズは 0 （パディングパケットを生成しても、適切なタイムスタンプを振ることができない）
• プローブ中の場合には プローブに必要なバイト数 - これまでに送信したバイト数 をパディングサイズとする

• PacingController::SetPacingRates() で「パディングパケットの送信レート」が指定されている場合には レート * 5ms を返す

  -ただし、パディング用のバジェットに余裕がある場合のみ

PacingController::MaybeUpdateMediaRateDueToLongQueue()¶

送信キューへの操作（要素追加や削除）があった場合に呼び出されるメソッド。

SetPacingRates() で指定された送信ペース（ターゲットビットレート）に対して、 EnqueuePacket() で追加されるペースが多過ぎると、キューが詰まって延々と要素数が増えてしまう。 それに対処するために、送信ペースの調整（増加）を行うのがこのメソッドの役割。

処理の流れ:

1. 最初に送信ペースを PacingController::SetPacingRates() で指定された値にリセットする
2. キューにあるパケットの「サイズ合計」を求める
   • もし 0 ならここで終了（指定された送信ペースをそのまま使う）
3. キュー内の各要素の平均滞在時間（エンキューされてから、実際に送信されるまでの平均時間）を求める
4. 「キューが空になるまでの期待時間」を 2 秒 - 平均滞在時間 で求める（0 以下になる場合には 1ms にする）
   • 「2 秒」の部分は PacingController::SetQueueTimeLimit() で変更できる
   • 「キューが空になるまでの期待時間」は、「キュー内の最後のパケットの遅延を 2 秒以下にするために使える残り時間」とも言える
5. サイズ合計 / キューが空になるまでの期待時間 で、その期待時間を達成するために必要な送信ペースを求める
   • 求めた送信ペースが PacingController::SetPacingRates() よりも大きい場合には、（指定のペースではなく）そちらを採用する

PacingController::UpdateTimeAndGetElapsed()¶

基本的には「現在時刻」を引数にとって、それと「最終処理時刻」との差分（経過時間）を計算して返すメソッド。

処理の流れ:

1. 「最終処理時刻」よりも前の時刻が「現在時刻」として指定された場合には、このメソッドは 0 秒を経過時間として返す
   • 「現在時刻」には PacingController::NextSendTime() が返した時刻が渡ってくることがあるため、過去の時刻になることもある
2. 現在時刻 - 最終処理時刻 で経過時間を求める
3. もし経過時刻が 2 秒を超えている場合には、2 秒に丸める
4. 「最終処理時刻」を「現在時刻」の値で更新して、経過時間を呼び出し元に返す

PacingController::UpdateBudgetWithElapsedTime() および PacingController::UpdateBudgetWithSentData()¶

バジェットの増減を行うための単純なメソッド群:

• PacingController::UpdateBudgetWithElapsedTime() は経過時間を引数に取り 経過時間 * 送信ペース の分だけバジェットを増やす
• PacingController::UpdateBudgetWithSentData() は送信したパケットサイズを引数に取り、その分だけバジェットを減らす

BitrateProber::CreateProbeCluster()¶

新しいクラスターを生成するためのメソッド。

処理の流れは以下の通り:

• 古いクラスターがキューに残っている場合には削除
  • 作成から五秒以上経過しているクラスターは、古いと判定される
• 引数で指定された以下の情報をもとに、新しいクラスターを生成する:
  • ターゲット送信ビットレート
  • プローブ用のパケット送信回数
  • プローブ用に送信するパケットサイズの合計
    • この値は ターゲット送信ビットレート * プローブ期間（デフォルトでは 15ms） によって算出される
• 生成したクラスターをキューの末尾に追加
• BitrateProber の状態を kInactive にする
  • 次の BitrateProber::OnIncomingPacket() 呼び出しによってプローブが開始される
  • 既に kActive の場合には何もしない）

BitrateProber::OnIncomingPacket()¶

• PacingController::EnqueuePacket() の中で、追加対象パケットのサイズを引数として、呼び出されるメソッド
• 「現在が kInactive 」かつ「クラスターキューが空ではない」かつ「パケットサイズが十分に大きい場合」に kActive 状態に遷移する
  • 「パケットサイズが十分に大きい場合」== 「パケットサイズが min(200, RecommendedMinProbeSize()) 以上」

BitrateProber::RecommendedMinProbeSize()¶

• 一度に送信するプローブ用のデータサイズの推奨（最低）値を返すメソッド
  • 送信量がこれより少ないとプローブの結果の信頼度が下がるので、不足分は（ PacingController によって）パディングパケットで補填される
• 計算式: 2 * ターゲット送信ビットレート * 1ms

BitrateProber::NextProbeTime()¶

• プローブ用のパケット送信を次に行うべき時刻を返すメソッド
• 状態が kActive ではない場合には Timestamp::PlusInfinity() が返される
• kActive （かつクラスターキューが空ではない）場合には BitrateProber::CalculateNextProbeTime() によって事前に計算されていた、次回プローブ時刻、を返す

private なメソッドである BitrateProber::CalculateNextProbeTime() は BitrateProber::ProbeSent() の中で呼び出され、 以下のようにして次回プローブ時刻を決定する:

• 計算式: クラスターでの送信開始時刻 + (クラスターで送信済みのサイズ合計 / ターゲットビットレート)
  • 「送信開始時刻」はクラスターの生成時刻とは異なり、初めて実際にパケットが送信された時刻
• クラスター生成時に指定されたターゲットビットレート通りの送信ペースになるように設定された単純な式
• ターゲットビットレートに対して「送信量が多い場合には未来の時刻」になり、逆に「送信量が少ない場合には過去の時刻」になる

BitrateProber::ProbeSent()¶

PacingController::ProcessPackets() の中で「実際に送信された合計パケットサイズ」を引数に取り呼び出されるメソッド。

処理の流れは以下の通り（キュー内の先頭のクラスターに対して適用される）:

• このクラスターでのパケット送信が初の場合には「送信開始時刻」を現在時刻に設定する
• 「送信済みバイト数合計」に、今回の送信分を加算する
• 「プローブ（用のデータ送信）回数」をインクリメントする
• BitrateProber::CalculateNextProbeTime() を呼び出して、次のプローブ時刻を決定する
• 以下の両方の条件を満たす場合には、プローブ処理を終えたものと判断し、クラスターをキューから除去する:
  • 「送信済みバイト数合計」が BitrateProber::CreateProbeCluster() で指定された規定値を超過した
  • 「プローブ回数」が BitrateProber::CreateProbeCluster() で指定された規定値を超過した
• クラスターキューが空になった場合には、 BitrateProber の状態を kSuspended に遷移する

BitrateProber::CurrentCluster()¶

現在のプローブ処理を行なっているクラスターを返すメソッド。

基本的にはキューの先頭要素を返すだけだが、細々とした条件や処理がある。

• BitrateProber の状態が kActive ではない場合には null を返す（クラスター生成直後は kInactive である可能性がある）
• 「次のプローブ時刻（cf. BitrateProber::CalculateNextProbeTime() ）」が現在時刻に対して 10ms よりも前の場合には「そのクラスターには深刻な遅延が発生している」と判断する:
  • そのクラスターはキューから除去して、次のクラスターを返す
  • キューが空の場合には、状態を kSuspended に遷移した上で null を返す