พบกับแนวคิดของ Media API

Google Meet Media API ช่วยให้แอปเข้าร่วมการประชุม Google Meet และใช้สตรีมสื่อแบบเรียลไทม์ได้

ไคลเอ็นต์ใช้ WebRTC เพื่อสื่อสารกับเซิร์ฟเวอร์ Meet โปรแกรมรับส่งอีเมลอ้างอิงที่มีให้ (C++, TypeScript) แสดงแนวทางปฏิบัติที่แนะนำ และเราขอแนะนำให้คุณสร้างจากโปรแกรมรับส่งอีเมลดังกล่าวโดยตรง

อย่างไรก็ตาม คุณยังสร้างไคลเอ็นต์ WebRTC ที่ปรับแต่งเองทั้งหมดซึ่งเป็นไปตามข้อกำหนดทางเทคนิคของ Meet Media API ได้ด้วย

หน้านี้ระบุแนวคิดหลักของ WebRTC ที่จำเป็นสำหรับเซสชัน Meet Media API ที่ประสบความสำเร็จ

สัญญาณของข้อเสนอที่ตอบ

WebRTC เป็นเฟรมเวิร์กแบบ Peer-to-Peer (P2P) ซึ่งผู้ใช้จะสื่อสารกันโดยการส่งสัญญาณให้กัน หากต้องการเริ่มเซสชัน เพียร์ที่เริ่มต้นจะส่งข้อเสนอ SDP ไปยังเพียร์ระยะไกล ข้อเสนอนี้ประกอบด้วยรายละเอียดสำคัญต่อไปนี้

คำอธิบายสื่อสำหรับเสียงและวิดีโอ

คำอธิบายสื่อจะระบุสิ่งที่สื่อสารระหว่างเซสชัน P2P คำอธิบายมี 3 ประเภท ได้แก่ เสียง วิดีโอ และข้อมูล

หากต้องการระบุสตรีมเสียง n ผู้เสนอต้องใส่nคำอธิบายสื่อเสียงในข้อเสนอ เช่นเดียวกับวิดีโอ อย่างไรก็ตาม จะมีการอธิบายสื่อข้อมูลเพียงรายการเดียวเท่านั้น

ทิศทาง

คำอธิบายเสียงหรือวิดีโอแต่ละรายการจะอธิบายสตรีม Secure Real-time Transport Protocol (SRTP) แต่ละรายการ ซึ่งควบคุมโดย RFC 3711 ซึ่งเป็นแบบ 2 ทิศทาง ซึ่งช่วยให้ผู้ใช้ 2 คนส่งและรับสื่อผ่านการเชื่อมต่อเดียวกันได้

ด้วยเหตุนี้ คําอธิบายสื่อแต่ละรายการ (ทั้งในข้อเสนอและคําตอบ) จึงมีแอตทริบิวต์อย่างใดอย่างหนึ่งต่อไปนี้ซึ่งอธิบายวิธีใช้สตรีม

• sendonly: ส่งเฉพาะสื่อจากคู่ค้าที่เสนอ บุคคลที่ปลายทางจะไม่ส่งสื่อในสตรีมนี้

• recvonly: รับเฉพาะสื่อจากคู่สนทนาระยะไกล พาร์ทเนอร์ที่เสนอราคาจะไม่ส่งสื่อในสตรีมนี้

• sendrecv: ทั้ง 2 ฝ่ายสามารถส่งและรับในสตรีมนี้ได้

ตัวแปลงรหัส

คำอธิบายสื่อแต่ละรายการจะระบุตัวแปลงรหัสที่คู่สนทนารองรับด้วย ในกรณีของ Meet Media API ระบบจะปฏิเสธข้อเสนอของลูกค้า เว้นแต่ว่าข้อเสนอจะรองรับ (อย่างน้อย) ตัวแปลงรหัสที่ระบุไว้ในข้อกำหนดทางเทคนิค

แฮนด์เชค DTLS

สตรีม SRTP ได้รับการรักษาความปลอดภัยโดยการจับมือ Datagram Transport Layer Security ("DTLS", RFC 9147) ครั้งแรกระหว่างคู่สนทนา DTLS เป็นโปรโตคอลแบบไคลเอ็นต์ต่อเซิร์ฟเวอร์ดั้งเดิม โดยระหว่างขั้นตอนการส่งสัญญาณ หนึ่งพาร์ทเนอร์จะตกลงที่จะทำหน้าที่เป็นเซิร์ฟเวอร์ ส่วนอีกพาร์ทเนอร์จะทำหน้าที่เป็นพาร์ทเนอร์

เนื่องจากสตรีม SRTP แต่ละรายการอาจมีการเชื่อมต่อ DTLS โดยเฉพาะ คำอธิบายสื่อแต่ละรายการจึงระบุแอตทริบิวต์อย่างใดอย่างหนึ่งต่อไปนี้เพื่อระบุบทบาทของคู่สนทนาในการแฮนด์เชค DTLS

• a=setup:actpass: บุคคลที่เสนอจะยอมรับตัวเลือกของบุคคลที่แชร์จากระยะไกล

• a=setup:active: ทำหน้าที่เป็นไคลเอ็นต์

• a=setup:passive: ทำหน้าที่เป็นเซิร์ฟเวอร์

คำอธิบายสื่อของแอปพลิเคชัน

แชแนลข้อมูล (RFC 8831) เป็นภาพรวมของ Stream Control Transmission Protocol ("SCTP", RFC 9260)

หากต้องการเปิดช่องทางข้อมูลในช่วงการส่งสัญญาณเริ่มต้น ข้อเสนอต้องมีคำอธิบายสื่อแอปพลิเคชัน คำอธิบายแอปพลิเคชันจะไม่ระบุทิศทางหรือตัวแปลงรหัส ต่างจากคำอธิบายเสียงและวิดีโอ

ผู้สมัคร ICE

ตัวเลือกการสร้างการเชื่อมต่อแบบอินเทอร์แอกทีฟ ("ICE", RFC 8445) ของคู่สนทนาคือรายการเส้นทางที่คู่สนทนาระยะไกลอาจใช้เพื่อสร้างการเชื่อมต่อ

ผลคูณคาร์ทีเซียนของรายการของพาร์ทเนอร์ 2 ราย ซึ่งเรียกว่าคู่ผู้สมัคร จะแสดงเส้นทางที่เป็นไปได้ระหว่างพาร์ทเนอร์ 2 ราย ระบบจะทดสอบคู่เหล่านี้เพื่อหาเส้นทางที่ดีที่สุด

ส่งสัญญาณผ่าน 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) แต่นักพัฒนาซอฟต์แวร์ไคลเอ็นต์ที่กําหนดเองสามารถใช้ PeerConnectionInterface ของ WebRTC เพื่อสร้างข้อเสนอได้

ข้อเสนอต้องเป็นไปตามข้อกำหนดต่อไปนี้จึงจะเชื่อมต่อกับ Meet ได้

1. ไคลเอ็นต์ต้องทำหน้าที่เป็นไคลเอ็นต์ในการแฮนด์เชค DTLS เสมอ ดังนั้นคำอธิบายสื่อทุกรายการในข้อเสนอต้องระบุ a=setup:actpass หรือ a=setup:active

2. บรรทัดคำอธิบายสื่อแต่ละบรรทัดต้องรองรับตัวแปลงรหัสที่จำเป็นทั้งหมดสำหรับประเภทสื่อนั้นๆ ดังนี้

   • เสียง: Opus
   • วิดีโอ: VP8, VP9, AV1

3. หากต้องการรับเสียง ข้อเสนอต้องมีคำอธิบายสื่อเสียงแบบรับอย่างเดียว 3 รายการ ซึ่งทำได้โดยการตั้งค่าตัวรับส่งสัญญาณในออบเจ็กต์การเชื่อมต่อแบบ Peer

   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 รายการ ซึ่งทำได้โดยการตั้งค่าตัวรับส่งสัญญาณในออบเจ็กต์การเชื่อมต่อแบบ Peer

   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 ที่มีเสียงและสตรีมวิดีโอเดียว

โปรดทราบว่ามีคำอธิบายสื่อเสียง 3 รายการ คำอธิบายสื่อวิดีโอ 1 รายการ และคำอธิบายสื่อแอปพลิเคชันที่จําเป็น

หัวข้อที่เกี่ยวข้อง

• เริ่มต้นใช้งาน