認識 Media API 概念

透過 Google Meet Media API，您的應用程式可以加入 Google Meet會議，並使用即時媒體串流。

用戶端會使用 WebRTC 與 Meet 伺服器通訊。我們提供的參考用戶端 (C++、TypeScript) 示範了建議做法，建議您直接以這些用戶端為基礎進行建構。

不過，您也可以建構完全自訂的 WebRTC 用戶端，並遵守 Meet Media API 的技術規定。

本頁面列出成功進行 Meet Media API 工作階段所需的重要 WebRTC 概念。

Offer-answer 信號

WebRTC 是點對點 (P2P) 架構，同層級裝置會互相傳送信號來進行通訊。如要開始工作階段，發起端對等互連裝置會將 SDP 提議傳送至遠端對等互連裝置。這項優惠包含下列重要細節：

音訊和影片的媒體說明

媒體說明會指出在 P2P 工作階段期間傳達的內容。描述類型有三種：音訊、影片和資料。

如要指出 n 音訊串流，提供者會在方案中加入 n 音訊媒體說明。影片也是如此。不過，最多只會有一項資料媒體說明。

通行方向

每個音訊或視訊說明都會描述個別的安全即時傳輸通訊協定 (SRTP) 串流，並受 RFC 3711 管轄。這些是雙向的，可讓兩個對等互連裝置透過相同連線傳送及接收媒體。

因此，每個媒體說明 (在提案和回覆中) 都包含三種屬性之一，說明應如何使用串流：

• sendonly：只傳送來自提供者的媒體。遠端對等互連裝置不會透過這個串流傳送媒體。

• recvonly：僅接收來自遠端對等互連裝置的媒體。提供內容的對等互連裝置不會透過這個串流傳送媒體。

• sendrecv：兩部對等互連裝置都可以在這個串流中傳送及接收資料。

轉碼器

每個媒體說明也會指定對等互連支援的轉碼器。如果是 Meet Media API，除非用戶端支援技術需求中指定的編解碼器 (至少)，否則會遭到拒絕。

DTLS 握手

SRTP 串流會先在對等互連裝置之間進行資料包傳輸層安全標準 (「DTLS」，RFC 9147) 握手，確保安全無虞。傳統上，DTLS 是用戶端對伺服器的通訊協定；在信號傳輸過程中，一個對等互連裝置會同意做為伺服器，另一個則做為對等互連裝置。

由於每個 SRTP 串流可能都有專屬的 DTLS 連線，因此每個媒體說明都會指定三種屬性之一，指出對等互連裝置在 DTLS 握手期間的角色：

• a=setup:actpass：提供的對等互連裝置會延後選擇，等待遠端對等互連裝置做出選擇。

• a=setup:active：這個對等互連裝置會做為用戶端。

• a=setup:passive：這個對等互連會做為伺服器。

應用程式媒體說明

資料管道 (RFC 8831) 是串流控制傳輸通訊協定 (「SCTP」，RFC 9260) 的抽象概念。

如要在初始信號階段開啟資料通道，提議必須包含應用程式媒體說明。與音訊和影片說明不同，應用程式說明不會指定方向或轉碼器。

ICE 候選人

對等互連的互動連線建立 (「ICE」，RFC 8445) 候選項目是遠端對等互連可用來建立連線的路線清單。

兩個對等互連裝置清單的笛卡兒乘積 (又稱候選配對) 代表兩個對等互連裝置之間的潛在路徑。這些配對會經過測試，以判斷最佳路徑。

透過 Meet REST API 發出信號

使用 Meet REST API 執行這項提議/回應信號傳輸。應用程式會將 SDP 提案提供給 connectActiveConference() 方法，並收到 SDP 回覆。

下列程式碼範例說明如何呼叫這個方法：

import com.google.api.core.ApiFuture;
import com.google.apps.meet.v2beta.ConnectActiveConferenceRequest;
import com.google.apps.meet.v2beta.ConnectActiveConferenceResponse;
import com.google.apps.meet.v2beta.SpaceName;
import com.google.apps.meet.v2beta.SpacesServiceClient;

public class AsyncConnectActiveConference {

  public static void main(String[] args) throws Exception {
    asyncConnectActiveConference();
  }

  public static void asyncConnectActiveConference() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SpacesServiceClient spacesServiceClient = SpacesServiceClient.create()) {
      ConnectActiveConferenceRequest request =
          ConnectActiveConferenceRequest.newBuilder()
              .setName(SpaceName.of("[SPACE]").toString())
              .setOffer("offer105650780")
              .build();
      ApiFuture<ConnectActiveConferenceResponse> future =
          spacesServiceClient.connectActiveConferenceCallable().futureCall(request);
      // Do something.
      ConnectActiveConferenceResponse response = future.get();
    }
  }
}

using Google.Apps.Meet.V2Beta;
using System.Threading.Tasks;

public sealed partial class GeneratedSpacesServiceClientSnippets
{
    /// <summary>Snippet for ConnectActiveConferenceAsync</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public async Task ConnectActiveConferenceAsync()
    {
        // Create client
        SpacesServiceClient spacesServiceClient = await SpacesServiceClient.CreateAsync();
        // Initialize request argument(s)
        string name = "spaces/[SPACE]";
        // Make the request
        ConnectActiveConferenceResponse response = await spacesServiceClient.ConnectActiveConferenceAsync(name);
    }
}

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Resource name of the space.
 *  Format: spaces/{spaceId}
 */
// const name = 'abc123'
/**
 *  Required. WebRTC SDP (Session Description Protocol) offer from the client.
 *  The format is defined by RFC
 *  8866 (https://www.rfc-editor.org/rfc/rfc8866) with mandatory keys defined
 *  by RFC 8829 (https://www.rfc-editor.org/rfc/rfc8829). This is the standard
 *  SDP format generated by a peer connection's createOffer() and
 *  createAnswer() methods.
 */
// const offer = 'abc123'

// Imports the Meet library
const {SpacesServiceClient} = require('@google-apps/meet').v2beta;

// Instantiates a client
const meetClient = new SpacesServiceClient();

async function callConnectActiveConference() {
  // Construct request
  const request = {
    name,
    offer,
  };

  // Run request
  const response = await meetClient.connectActiveConference(request);
  console.log(response);
}

callConnectActiveConference();

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.apps import meet_v2beta


async def sample_connect_active_conference():
    # Create a client
    client = meet_v2beta.SpacesServiceAsyncClient()

    # Initialize request argument(s)
    request = meet_v2beta.ConnectActiveConferenceRequest(
        name="name_value",
        offer="offer_value",
    )

    # Make the request
    response = await client.connect_active_conference(request=request)

    # Handle the response
    print(response)

連結流程範例

以下是附有音訊媒體說明的方案：

遠端對等互連裝置會傳回包含相同媒體說明行數的 SDP 回覆。每一行都指出遠端對等互連裝置透過 SRTP 串流傳回給提供用戶端的媒體 (如有)。遠端對等互連裝置也可以將媒體說明項目設為 recvonly，拒絕接收提案者提供的特定串流。

對於 Meet Media API，用戶端一律會傳送 SDP 提案來啟動連線。Meet 絕不會是發起者。

這項行為是由參考用戶端 (C++、TypeScript) 在內部管理，但自訂用戶端的開發人員可以使用 WebRTC 的 PeerConnectionInterface 生成提案。

如要連結至 Meet Meet，優惠必須符合特定規定：

1. 用戶端一律必須在 DTLS 交握中擔任用戶端，因此提案中的每個媒體說明都必須指定 a=setup:actpass 或 a=setup:active。

2. 每個媒體說明行都必須支援該媒體類型適用的必要轉碼器：

   • 音訊： Opus
   • 影片： VP8、VP9、AV1

3. 如要接收音訊，優惠必須包含 3 個僅供接收的音訊媒體說明。方法是在對等連線物件上設定收發器。

   C++

   // ...
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   for (int i = 0; i < 3; ++i) {
     webrtc::RtpTransceiverInit audio_init;
     audio_init.direction = webrtc::RtpTransceiverDirection::kRecvOnly;
     audio_init.stream_ids = {absl::StrCat("audio_stream_", i)};
   
     webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::RtpTransceiverInterface>>
       audio_result = peer_connection->AddTransceiver(
         cricket::MediaType::MEDIA_TYPE_AUDIO, audio_init);
   
     if (!audio_result.ok()) {
       return absl::InternalError(absl::StrCat("Failed to add audio transceiver: ",
                                               audio_result.error().message()));
     }
   }
   

   JavaScript

   pc = new RTCPeerConnection();
   
   // Configure client to receive audio from Meet servers.
   pc.addTransceiver('audio', {'direction':'recvonly'});
   pc.addTransceiver('audio', {'direction':'recvonly'});
   pc.addTransceiver('audio', {'direction':'recvonly'});
   

4. 如要接收影片，方案必須包含 1 到 3 個僅供接收的影片媒體說明。方法是在對等連線物件上設定收發器。

   C++

   // ...
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   for (uint32_t i = 0; i < configurations.receiving_video_stream_count; ++i) {
     webrtc::RtpTransceiverInit video_init;
     video_init.direction = webrtc::RtpTransceiverDirection::kRecvOnly;
     video_init.stream_ids = {absl::StrCat("video_stream_", i)};
   
     webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::RtpTransceiverInterface>>
         video_result = peer_connection->AddTransceiver(
           cricket::MediaType::MEDIA_TYPE_VIDEO, video_init);
   
     if (!video_result.ok()) {
       return absl::InternalError(absl::StrCat("Failed to add video transceiver: ",
                                               video_result.error().message()));
     }
   }
   

   JavaScript

   pc = new RTCPeerConnection();
   
   // Configure client to receive video from Meet servers.
   pc.addTransceiver('video', {'direction':'recvonly'});
   pc.addTransceiver('video', {'direction':'recvonly'});
   pc.addTransceiver('video', {'direction':'recvonly'});
   

5. 方案一律須包含資料管道。至少應一律開啟 session-control 和 media-stats 管道。所有資料管道都必須為 ordered。

   C++

   // ...
   // All data channels must be ordered.
   constexpr webrtc::DataChannelInit kDataChannelConfig = {.ordered = true};
   
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   // Signal session-control data channel.
   webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::DataChannelInterface>>
     session_create_result = peer_connection->CreateDataChannelOrError(
       "session-control", &kDataChannelConfig);
   
   if (!session_create_result.ok()) {
     return absl::InternalError(absl::StrCat("Failed to create data channel ",
                                             data_channel_label, ": ",
                                             session_create_result.error().message()));
   }
   
   // Signal media-stats data channel.
   webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::DataChannelInterface>>
     stats_create_result = peer_connection->CreateDataChannelOrError(
       "media-stats", &kDataChannelConfig);
   
   if (!stats_create_result.ok()) {
     return absl::InternalError(absl::StrCat("Failed to create data channel ",
                                             data_channel_label, ": ",
                                             stats_create_result.error().message()));
   }
   

   JavaScript

   // ...
   pc = new RTCPeerConnection();
   
   // All data channels must be ordered.
   const dataChannelConfig = {
     ordered: true,
   };
   
   // Signal session-control data channel.
   sessionControlChannel = pc.createDataChannel('session-control', dataChannelConfig);
   sessionControlChannel.onopen = () => console.log("data channel is now open");
   sessionControlChannel.onclose = () => console.log("data channel is now closed");
   sessionControlChannel.onmessage = async (e) => {
     console.log("data channel message", e.data);
   };
   
   // Signal media-stats data channel.
   mediaStatsChannel = pc.createDataChannel('media-stats', dataChannelConfig);
   mediaStatsChannel.onopen = () => console.log("data channel is now open");
   mediaStatsChannel.onclose = () => console.log("data channel is now closed");
   mediaStatsChannel.onmessage = async (e) => {
     console.log("data channel message", e.data);
   };
   

SDP 提議和回覆範例

以下是有效的 SDP 提議和相符 SDP 回覆的完整範例。這項提案會透過音訊和單一視訊串流，與 Meet Media API 工作階段進行交涉。

請注意，有三項音訊媒體說明、一項影片媒體說明，以及必要的應用程式媒體說明。

相關主題

• 開始使用