シグナリングの型定義

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

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

基本的なデータ型

JSON 値

type JSONType =
  | null
  | boolean
  | number
  | string
  | JSONType[]
  | { [prop: string]: JSONType | undefined };

JSON 値を表します。 仕様は RFC 8259 に従います。

シグナリング

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

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

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

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

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

    • connect

    • answer

    • candidate

    • update

    • pong

    • disconnect

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

    • offer

    • update

    • ping

    • push

    • notify

type: connect

type SignalingConnectMessage = {
  type: "connect";
  role: Role;
  channel_id: string;
  client_id?: string;
  metadata?: JSONType;
  signaling_notify_metadata?: JSONType;
  multistream?: boolean;
  spotlight?: Spotlight;
  spotlight_number?: number;
  simulcast?: boolean;
  simulcast_rid?: SimulcastRid;
  audio?: boolean;
  video?: boolean;
  sdp?: string;
  sora_client?: string;
  environment?: string;
  libwebrtc?: string;
  e2ee?: boolean;
};

ストリームの種別

type Role =
  | "sendrecv"
  | "sendonly"
  | "recvonly"
  | "upstream"
  | "downstream";

サイマルキャストで配信する映像の種類

type SimulcastRid = "r0" | "r1" | "r2";

スポットライト

spotlight_legacy が有効かどうかによって boolean または number どちらかを使用します。
詳しくは スポットライト機能スポットライトレガシー機能 を参照してください。
type Spotlight = boolean | number;

音声

type AudioCodecType = "OPUS";

type Audio =
  | boolean
  | {
      codec_type?: AudioCodecType;
      bit_rate?: number;
      opus_params?: {
        channels?: number;
        clock_rate?: number;
        maxplaybackrate?: number;
        minptime?: number;
        ptime?: number;
        stereo?: boolean;
        sprop_stereo?: boolean;
        useinbandfec?: boolean;
        usedtx?: boolean;
      };
    };

映像

type VideoCodecType =
  | "VP9"
  | "VP8"
  | "AV1"
  | "H264"
  | "H265";

type Video =
  | boolean
  | {
      codec_type?: VideoCodecType;
      bit_rate?: number;
    };

type: offer

type SignalingOfferMessage = {
  type: "offer";
  sdp: string;
  client_id: string;
  connection_id: string;
  metadata?: JSONType;
  config?: JSONType;
  encodings?: RTCRtpEncodingParameters[];
};

type: answer

type SignalingAnswerMessage = {
  type: "answer";
  sdp: string;
};

type: candidate

type SignalingCandidateMessage = {
  type: "candidate";
  candidate: string;
};

type: update (サーバ -> クライアント)

type SignalingUpdateToClientMessage = {
  type: "update";
  sdp: string;
};

type: update (クライアント -> サーバ)

type SignalingUpdateToServerMessage = {
  type: "update";
  sdp: string;
};

type: ping

type SignalingPingMessage = {
  type: "ping";
  stats: boolean;
};

type: pong

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

push

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

notify

type SignalingNotifyMessage =
  | SignalingNotifyConnectionCreated
  | SignalingNotifyConnectionUpdated
  | SignalingNotifyConnectionDestroyed
  | SignalingNotifySpotlightChanged
  | SignalingNotifySpotlightFocused
  | SignalingNotifySpotlightUnfocused
  | SignalingNotifyNetworkStatus;

接続中のクライアントの情報

type SignalingNotifyMetadata = {
  client_id?: string;
  connection_id?: string;
  authn_metadata?: JSONType;
  authz_metadata?: JSONType;
  metadata?: JSONType;
};

connection.created

signaling_notify_metadata_ext が有効かどうかによって metadata_list または data どちらに値がセットされます。

type SignalingNotifyConnectionCreated = {
  type: "notify";
  event_type: "connection.created";
  role: Role;
  client_id?: string;
  connection_id?: string;
  audio?: boolean;
  video?: boolean;
  authn_metadata?: JSONType;
  authz_metadata?: JSONType;
  metadata?: JSONType;
  metadata_list?: SignalingNotifyMetadata[];
  data?: SignalingNotifyMetadata[];
  minutes: number;
  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;
  channel_upstream_connections: number;
  channel_downstream_connections: number;
  turn_transport_type: "udp" | "tcp";
};

connection.updated

// "connection.updated"
type SignalingNotifyConnectionUpdated = {
  type: "notify";
  event_type: "connection.updated";
  role: Role;
  client_id?: string;
  connection_id?: string;
  audio?: boolean;
  video?: boolean;
  minutes: number;
  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;
  channel_upstream_connections: number;
  channel_downstream_connections: number;
  turn_transport_type: "udp" | "tcp";
};

connection.destroyed

type SignalingNotifyConnectionDestroyed = {
  type: "notify";
  event_type: "connection.destroyed";
  role: Role;
  client_id?: string;
  connection_id?: string;
  audio?: boolean;
  video?: boolean;
  minutes: number;
  authn_metadata?: JSONType;
  authz_metadata?: JSONType;
  metadata?: JSONType;
  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;
  channel_upstream_connections: number;
  channel_downstream_connections: number;
  turn_transport_type: "udp" | "tcp";
};

spotlight.changed

type SignalingNotifySpotlightChanged = {
  type: "notify";
  event_type: "spotlight.changed";
  client_id: string | null;
  connection_id: string | null;
  spotlight_id: string;
  fixed?: boolean;
  audio: boolean;
  video: boolean;
};

spotlight.focused

type SignalingNotifySpotlightFocused = {
  type: "notify";
  event_type: "spotlight.focused";
  client_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;
  connection_id: string;
  audio: boolean;
  video: boolean;
  fixed: boolean;
};

network.status

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

disconnect

type SignalingDisconnectMessage = {
  type: "disconnect";
};

完全な型定義

type JSONType =
  | null
  | boolean
  | number
  | string
  | JSONType[]
  | { [prop: string]: JSONType | undefined };

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

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

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

// type: "connect"
type SignalingConnectMessage = {
  type: "connect";
  role: Role;
  channel_id: string;
  client_id?: string;
  metadata?: JSONType;
  signaling_notify_metadata?: JSONType;
  multistream?: boolean;
  spotlight?: Spotlight;
  spotlight_number?: number;
  simulcast?: boolean;
  simulcast_rid?: SimulcastRid;
  audio?: boolean;
  video?: boolean;
  sdp?: string;
  sora_client?: string;
  environment?: string;
  libwebrtc?: string;
  e2ee?: boolean;
};

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

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

// スポットライト
type Spotlight = boolean | number;

type AudioCodecType = "OPUS";

// 音声
type Audio =
  | boolean
  | {
      codec_type?: AudioCodecType;
      bit_rate?: number;
      opus_params?: {
        channels?: number;
        clock_rate?: number;
        maxplaybackrate?: number;
        minptime?: number;
        ptime?: number;
        stereo?: boolean;
        sprop_stereo?: boolean;
        useinbandfec?: boolean;
        usedtx?: boolean;
      };
    };

type VideoCodecType =
  | "VP9"
  | "VP8"
  | "AV1"
  | "H264"
  | "H265";

// 映像
type Video =
  | boolean
  | {
      codec_type?: VideoCodecType;
      bit_rate?: number;
    };

// type: "offer"
type SignalingOfferMessage = {
  type: "offer";
  sdp: string;
  client_id: string;
  connection_id: string;
  metadata?: JSONType;
  config?: JSONType;
  encodings?: RTCRtpEncodingParameters[];
};

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

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

// type: "update"
// サーバーからクライアントに送信される
type SignalingUpdateToClientMessage = {
  type: "update";
  sdp: string;
};

// type: "update"
// クライアントからサーバーに送信される
type SignalingUpdateToServerMessage = {
  type: "update";
  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
  | SignalingNotifySpotlightChanged
  | SignalingNotifySpotlightFocused
  | SignalingNotifySpotlightUnfocused
  | SignalingNotifyNetworkStatus;

type SignalingNotifyMetadata = {
  client_id?: string;
  connection_id?: string;
  authn_metadata?: JSONType;
  authz_metadata?: JSONType;
  metadata?: JSONType;
};

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

// "connection.updated"
type SignalingNotifyConnectionUpdated = {
  type: "notify";
  event_type: "connection.updated";
  role: Role;
  client_id?: string;
  connection_id?: string;
  audio?: boolean;
  video?: boolean;
  minutes: number;
  channel_connections: number;
  channel_sendrecv_connections: number;
  channel_sendonly_connections: number;
  channel_recvonly_connections: number;
  channel_upstream_connections: number;
  channel_downstream_connections: number;
  turn_transport_type: "udp" | "tcp";
};

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

// "spotlight.changed"
type SignalingNotifySpotlightChanged = {
  type: "notify";
  event_type: "spotlight.changed";
  client_id: string | null;
  connection_id: string | null;
  spotlight_id: string;
  fixed?: boolean;
  audio: boolean;
  video: boolean;
};

// "spotlight.focused"
type SignalingNotifySpotlightFocused = {
  type: "notify";
  event_type: "spotlight.focused";
  client_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;
  connection_id: string;
  audio: boolean;
  video: boolean;
  fixed: boolean;
};

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

// type: "disconnect"
type SignalingDisconnectMessage = {
  type: "disconnect";
};