ログの型定義¶

ここではログの型について説明します。型の表記は TypeScript で記述します。

基本的な型¶

// JSON 値を表します。
// 仕様は RFC 8259 に従います。
type JSONValue =
  | null
  | boolean
  | number
  | string
  | JSONValue[]
  | { [key: string]: JSONValue | undefined };

// UnixTime
// 例: 1704067199
type UnixTime = number;

// RFC3339 UTC (マイクロ秒)
// 例: 2023-12-31T23:59:59.999999Z
type Timestamp = string;

// ストリームの種別
type Role = "sendrecv" | "sendonly" | "recvonly";

// サイマルキャストで視聴する映像の種類
type SimulcastRid = "r0" | "r1" | "r2";

// 音声の設定
type Audio =
  | boolean
  | {
      codec_type?: AudioCodecType;
      bit_rate?: number;
      opus_params?: OpusParams;
    };

type OpusParams = {
  channels?: number;
  maxplaybackrate?: number;
  minptime?: number;
  ptime?: number;
  stereo?: boolean;
  sprop_stereo?: boolean;
  useinbandfec?: boolean;
  usedtx?: boolean;
};

// 映像の設定
type Video =
  | boolean
  | {
      codec_type?: VideoCodecType;
      bit_rate?: number;
      // 利用するには sora.conf で signaling_vp9_params = true を設定する必要があります
      vp9_params?: VP9Params;
      // 利用するには sora.conf で signaling_av1_params = true を設定する必要があります
      av1_params?: AV1Params;
      // 利用するには sora.conf で signaling_h264_params = true を設定する必要があります
      h264_params?: H264Params;
      // 利用するには sora.conf で signaling_h265_params = true を設定する必要があります
      h265_params?: H265Params;
    };

type VP9Params = {
  // 0..3
  profile_id?: number;
};

type AV1Params = {
  // 0..2
  profile?: number;
};

type H264Params = {
  profile_level_id?: string;
  // sora.conf で h264_b_frame = true を設定する必要があります
  b_frame?: boolean;
};

type H265Params = {
  level_id?: number;
  // sora.conf で h265_b_frame = true を設定する必要があります
  b_frame?: boolean;
};

// 音声コーデックの種類
type AudioCodecType = "OPUS";

// 映像コーデックの種類
type VideoCodecType = "VP9" | "VP8" | "AV1" | "H264" | "H265";

// DataChannel の方向
type Direction = "sendrecv" | "sendonly" | "recvonly";

type DataChannelMessagingHeaderFieldType = "sender_connection_id";

type DataChannelMessagingHeaderField = {
  type: DataChannelMessagingHeaderFieldType;
  // * length は "type": "offer" 時の data_channels にのみ含まれる
  // * length は"type": "connect" 時には指定できない
  // * length は認証成功時の払い出し時には指定できない
  length?: number;
};

// DataChannels
type DataChannel = {
  label: string;
  direction: Direction;
  ordered?: boolean;
  max_packet_life_time?: number;
  max_retransmits?: number;
  protocol?: string;
  compress?: boolean;
  header?: DataChannelMessagingHeaderField[];
};

type TurnTransportType = "udp" | "tcp";

type ForwardingFilterRuleField = "connection_id" | "client_id" | "kind";

type ForwardingFilterRuleOperator = "is_in" | "is_not_in";

type ForwardingFilterRuleKindValue = "audio" | "video";

type ForwardingFilterRule = {
  field: ForwardingFilterRuleField;
  operator: ForwardingFilterRuleOperator;
  values: [string];
};

type ForwardingFilterAction = "block" | "allow";

type ForwardingFilter = {
  version?: string;
  metadata?: JSONValue;
  name?: string;
  priority?: number;
  action?: ForwardingFilterAction;
  rules: [[ForwardingFilterRule]];
};

type SoraClientType =
  | "Sora JavaScript SDK"
  | "Sora iOS SDK"
  | "Sora Android SDK"
  | "Sora Unity SDK"
  | "Sora C++ SDK"
  | "Sora Python SDK"
  | "Sora C SDK"
  | "OBS-Studio-WHIP"
  | "OBS-Studio-WHEP";

// SoraClient
type SoraClient = {
  environment?: string;
  raw?: string;
  type?: SoraClientType;
  version?: string;
  commit_short?: string;
  libwebrtc?: string;
};

// RTCRtpCodecParameters
// https://www.w3.org/TR/webrtc/#dom-rtcrtpcodecparameters
type SimulcastCodec = {
  // payloadType や channels は省略
  mimeType: string;
  clockRate: number;
  sdpFmtpLine?: string;
};

// RTCRtpEncodingParameters
// https://w3c.github.io/webrtc-pc/#dom-rtcrtpencodingparameters
type SimulcastEncoding = {
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpcodingparameters-rid
  rid: SimulcastRid;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-active
  active?: boolean;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxframerate
  maxFramerate?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxbitrate
  maxBitrate?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-scaleresolutiondownby
  scaleResolutionDownBy?: number;
  // https://www.w3.org/TR/webrtc/#dom-rtcrtpcodec
  codec?: SimulcastCodec;
  // https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-scaleresolutiondownto
  // @ts-ignore: RTCResolutionRestriction は typed で未定義のため型チェックを無視(型定義が追加され次第 ts-ignore を削除)
  scaleResolutionDownTo?: RTCResolutionRestriction;
  // https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-adaptiveptime
  adaptivePtime?: boolean;
  // https://www.w3.org/TR/webrtc-svc/#dom-rtcrtpencodingparameters-scalabilitymode
  scalabilityMode?: string;
};

型定義¶

ウェブフックログ¶

// Base32 化した UUIDv4
type WebhookID = string;

// ウェブフック URL で HTTP または HTTPS
type WebhookURL = string;

// 認証ウェブフックログ
type AuthWebhookLog = {
  id: WebhookID;
  timestamp: Timestamp;

  req: AuthWebhookRequest;
  res: AuthWebhookAcceptResponse;

  // ウェブフック URL
  url?: WebhookURL;

  // WebSocket のコピーした HTTP ヘッダー
  copy_headers?: string[];
};

// 認証ウェブフックエラーログ
type AuthWebhookErrorLog = {
  id: WebhookID;
  timestamp: Timestamp;

  req: AuthWebhookRequest;

  // ウェブフック URL
  url: WebhookURL;

  // エラー理由
  reason: string;

  // WebSocket シグナリングの HTTP ヘッダーのコピー
  copy_headers?: string[];
};

// セッションウェブフックログ
type SessionWebhookLog = {
  id: WebhookID;
  timestamp: Timestamp;

  req: SessionWebhookRequest;

  res?: SessionWebhookResponse;

  // ウェブフック URL
  url?: WebhookURL;
};

// セッションウェブフックエラーログ
type SessionWebhookErrorLog = {
  id: WebhookID;
  timestamp: Timestamp;

  req: SessionWebhookRequest;

  // ウェブフック URL
  url?: WebhookURL;

  // エラー理由
  reason: string;
};

// イベントウェブフックログ
type EventWebhookLog = EventWebhookRequest;

// イベントウェブフックエラーログ
type EventWebhookErrorLog = EventWebhookRequest;

// 統計ウェブフックログ
type StatsWebhookLog = StatsWebhookConnectionRtcRequest;

// 統計ウェブフックエラーログ
type StatsWebhookErrorLog = StatsWebhookConnectionRtcRequest;

その他のログ¶

// JSON Lines 形式ではないログは定義していません。

// RTC 統計ログ
type RtcStatsLog = {
  id: WebhookID;
  timestamp: Timestamp;

  node_name: string;
  label: string;
  version: string;

  type: string;

  role: string;
  channel_id: string;
  group_id: string;
  session_id: string;
  client_id: string;
  bundle_id: string;
  connection_id: string;

  simulcast: boolean;
  spotlight: boolean;

  rtc_timestamp: DOMHighResTimeStamp;
  rtc_type: RTCStatsType;
  rtc_id: string;
  // https://www.w3.org/TR/webrtc/#dom-rtcstatsreport
  rtc_data: Record<string, object>;

  copy_headers?: string[];

  log_written: boolean;
};

// 接続ウェブフックログ
type ConnectionLog = {
  id: WebhookID;
  timestamp: Timestamp;
};

// シグナリングウェブフックログ
type SignalingLog = {
  id: WebhookID;
  timestamp: Timestamp;
};

// シグナリングウェブフックエラーログ
type SignalingErrorLog = {
  id: WebhookID;
  timestamp: Timestamp;
};

// API ログ
type ApiLog = {
  id: WebhookID;
  timestamp: Timestamp;

  // 操作
  operation: string;

  // JSON データ
  json: string;
};