シグナリングの型定義¶

この章ではシグナリングの型について説明します。シグナリングの仕様についてはシグナリングを参照ください。

型の表記は TypeScript で記述します。

基本的なデータ型¶

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

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

// サイマルキャストで配信する映像の種類
type SimulcastRid = 'r0' | 'r1' | 'r2'

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

type LyraParams = {
  version?: string
  bitrate?: number
}

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
      vp9_params?: VP9Params
      av1_params?: AV1Params
      h264_params?: H264Params
    }

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

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

type H264Params = {
  profile_level_id?: string
}

// 音声コーデックの種類
type AudioCodecType = 'OPUS' | 'LYRA'

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

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

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

type ForwardingFilterRuleField = 'connection_id' | 'client_id' | 'kind'

type ForwardingFilterRuleOperator = 'is_in' | 'is_not_in'

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

type ForwardingFilterAction = 'block' | 'allow'

type ForwardingFilter = {
  action: ForwardingFilterAction
  rules: [[ForwardingFilterRule]]
}

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

シグナリング¶

シグナリングは「クライアントからサーバー (Sora) に送信される」メッセージと「サーバー (Sora) からクライアントに送信される」メッセージに分かれます。

クライアントからサーバーに送信されるメッセージ¶

connect
answer
candidate
re-answer
pong
- WebSocket 経路利用時のみ
disconnect
stats
- DataChannel 経路利用時のみ

Server からクライアントに送信されるメッセージ¶

offer
re-offer
ping
- WebSocket 経路利用時のみ
push
notify
req-stats
- DataChannel 経路利用時のみ

完全な型定義¶

// シグナリング
type Signaling = ClientToServer | ServerToClient

// クライアントからサーバーに送信されるメッセージ
type ClientToServer =
  | SignalingConnectMessage
  | SignalingAnswerMessage
  | SignalingCandidateMessage
  | SignalingReAnswerToServerMessage
  | SignalingPongMessage
  | SignalingDisconnectMessage

// サーバーからクライアントに送信されるメッセージ
type ServerToClient =
  | SignalingRedirectMessage
  | SignalingOfferMessage
  | SignalingReOfferToClientMessage
  | SignalingPingMessage
  | SignalingPushMessage
  | SignalingNotifyMessage
  | SignalingSwitchedMessage

// type: "connect"
type SignalingConnectMessage = {
  type: 'connect'
  role: Role
  channel_id: string
  client_id?: string
  bundle_id?: string
  metadata?: JSONValue
  signaling_notify_metadata?: JSONValue
  multistream?: boolean
  spotlight?: boolean
  spotlight_number?: number
  data_channel_signaling?: boolean
  ignore_disconnect_websocket?: boolean
  data_channels?: DataChannel[]
  simulcast?: boolean
  simulcast_rid?: SimulcastRid
  spotlight_focus_rid?: SimulcastRid | 'none'
  spotlight_unfocus_rid?: SimulcastRid | 'none'
  audio?: Audio
  video?: Video
  // type: redirect で戻されて再度 type: connect で接続するときに有効にする
  redirect?: boolean
  forwarding_filter?: ForwardingFilter
  audio_streaming_language_code?: string
  e2ee?: boolean
  sdp?: string
  sora_client?: SoraClient
  environment?: string
  libwebrtc?: string
}

type Mid = {
  auido?: string
  video?: string
}

// type: "redirect"
type SignalingRedirectMessage = {
  type: 'redirect'
  location: string
}

// type: "offer"
type SignalingOfferMessage = {
  type: 'offer'
  sdp: string
  multistream: boolean
  simulcast: boolean
  spotlight: boolean
  client_id: string
  bundle_id: string
  connection_id: string
  metadata?: JSONValue
  config?: JSONValue
  encodings?: RTCRtpEncodingParameters[]
  mid?: Mid
  data_channels?: DataChannel[]
}

// type: "answer"
type SignalingAnswerMessage = {
  type: 'answer'
  sdp: string
}

// type: "candidate"
type SignalingCandidateMessage = {
  type: 'candidate'
  candidate: string
}

// type: "re-offer"
// サーバーからクライアントに送信される
type SignalingReOfferToClientMessage = {
  type: 're-offer'
  sdp: string
}

// type: "re-answer"
// クライアントからサーバーに送信される
type SignalingReAnswerToServerMessage = {
  type: 're-answer'
  sdp: string
}

// type: "ping"
type SignalingPingMessage = {
  type: 'ping'
  stats?: boolean
}

// type: "pong"
type SignalingPongMessage = {
  type: 'pong'
  stats?: RTCStatsReport[]
}

// type: "push"
type SignalingPushMessage = {
  type: 'push'
  data: Record<string, unknown>
}

// type: "notify"
type SignalingNotifyMessage =
  | SignalingNotifyConnectionCreated
  | SignalingNotifyConnectionUpdated
  | SignalingNotifyConnectionDestroyed
  | SignalingNotifySpotlightFocused
  | SignalingNotifySpotlightUnfocused
  | SignalingNotifyRecordingStarted
  | SignalingNotifyRecordingStopped
  | SignalingNotifyNetworkStatus

// 接続中のクライアントの情報
type SignalingNotifyMetadata = {
  client_id?: string
  bundle_id?: string
  connection_id?: string
  authn_metadata?: JSONValue
  authz_metadata?: JSONValue
  metadata?: JSONValue
}

// "connection.created",
type SignalingNotifyConnectionCreated = {
  type: 'notify'
  event_type: 'connection.created'
  role: Role
  session_id?: string
  client_id?: string
  bundle_id?: string
  connection_id?: string
  audio?: boolean
  video?: boolean
  authn_metadata?: JSONValue
  authz_metadata?: JSONValue
  metadata?: JSONValue
  data?: SignalingNotifyMetadata[]
  minutes: number
  channel_connections: number
  channel_sendrecv_connections: number
  channel_sendonly_connections: number
  channel_recvonly_connections: number
  turn_transport_type: 'udp' | 'tcp'
}

// "connection.updated"
type SignalingNotifyConnectionUpdated = {
  type: 'notify'
  event_type: 'connection.updated'
  role: Role
  session_id?: string
  client_id?: string
  bundle_id?: string
  connection_id?: string
  audio?: boolean
  video?: boolean
  authn_metadata?: JSONValue
  authz_metadata?: JSONValue
  metadata?: JSONValue
  minutes: number
  channel_connections: number
  channel_sendrecv_connections: number
  channel_sendonly_connections: number
  channel_recvonly_connections: number
  turn_transport_type: 'udp' | 'tcp'
}

// "connection.destroyed"
type SignalingNotifyConnectionDestroyed = {
  type: 'notify'
  event_type: 'connection.destroyed'
  role: Role
  session_id?: string
  client_id?: string
  bundle_id?: string
  connection_id?: string
  audio?: boolean
  video?: boolean
  minutes: number
  authn_metadata?: JSONValue
  authz_metadata?: JSONValue
  metadata?: JSONValue
  channel_connections: number
  channel_sendrecv_connections: number
  channel_sendonly_connections: number
  channel_recvonly_connections: number
  turn_transport_type: 'udp' | 'tcp'
}

// "spotlight.focused"
type SignalingNotifySpotlightFocused = {
  type: 'notify'
  event_type: 'spotlight.focused'
  client_id: string | null
  bundle_id: string | null
  connection_id: string
  audio: boolean
  video: boolean
  fixed: boolean
}

// "spotlight.unfocused"
type SignalingNotifySpotlightUnfocused = {
  type: 'notify'
  event_type: 'spotlight.unfocused'
  client_id: string | null
  bundle_id: string | null
  connection_id: string
  audio: boolean
  video: boolean
  fixed: boolean
}

// "recording.started"
type SignalingNotifyRecordingStarted = {
  type: 'notify'
  event_type: 'recording.started'
  client_id: string | null
  bundle_id: string | null
  connection_id: string
}

// "recording.stopped"
type SignalingNotifyRecordingStopped = {
  type: 'notify'
  event_type: 'recording.stopped'
  client_id: string | null
  bundle_id: string | null
  connection_id: string
}

// "network.status"
type SignalingNotifyNetworkStatus = {
  type: 'notify'
  event_type: 'network.status'
  unstable_level: 0 | 1 | 2 | 3
}

// type: "disconnect"
type SignalingDisconnectMessage = {
  type: 'disconnect'
  reason: string
}

// type: "stats"
// サーバーからクライアントに送信される
type DataChannelStatsToClientMessage = {
  type: 'stats'
}

// type: "stats"
// クライアントからサーバーに送信される
type DataChannelStatsToServerMessage = {
  type: 'stats'
  reports: RTCStatsReport[]
}

// type: "switched"
type SignalingSwitchedMessage = {
  type: 'switched'
  ignore_disconnect_websocket: boolean
}