ยินดีต้อนรับสู่ศูนย์นักพัฒนาซอฟต์แวร์ Google Home ซึ่งเป็นจุดหมายใหม่เกี่ยวกับวิธีพัฒนาการดําเนินการสําหรับบ้านอัจฉริยะ หมายเหตุ: คุณจะสร้างการดําเนินการต่างๆ ต่อไปในคอนโซลการดําเนินการ

แบบแผน SmartStream CameraStream

action.devices.traits.CameraStream - ลักษณะนี้ครอบคลุมวิธีการควบคุมกระแสกล้องของอุปกรณ์

ลักษณะนี้เป็นของอุปกรณ์ที่สามารถสตรีมวิดีโอฟีดไปยัง Smart Display, อุปกรณ์ที่พร้อมใช้งาน Chromecast หรือสมาร์ทโฟน กล้องเหล่านี้คือกล้องวงจรปิดหรือกล้องสําหรับทารก แต่ลักษณะการใช้งานนี้ใช้กับอุปกรณ์ที่ซับซ้อนมากขึ้นซึ่งมีกล้องติดตั้งอยู่ด้วย (เช่น อุปกรณ์การประชุมทางวิดีโอหรือหุ่นยนต์เครื่องดูดฝุ่นที่มีกล้องอยู่)

แอตทริบิวต์ของอุปกรณ์

อุปกรณ์ที่มีลักษณะเฉพาะนี้อาจรายงานแอตทริบิวต์ต่อไปนี้เป็นส่วนหนึ่งของการดําเนินการ SYNC หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการ Intent ของ SYNC โปรดดูการดําเนินการ Intent

แอตทริบิวต์ Type คำอธิบาย
cameraStreamSupportedProtocols อาร์เรย์

ต้องระบุ

ประเภทสื่อที่รองรับสําหรับสตรีมกล้อง เรียงตามค่ากําหนด โดยปกติแล้วจะมีการส่งคําขอโปรโตคอลแรกในอาร์เรย์นี้ที่ใช้ร่วมกับแพลตฟอร์มเป้าหมายได้

[item, ...] สตริง

ประเภทสื่อ

ค่าที่รองรับ:

hls
สตรีมมิงแบบสดของ HTTP
dash
การสตรีมที่ปรับเปลี่ยนได้แบบไดนามิกผ่าน HTTP
smooth_stream
สตรีมมิงได้อย่างราบรื่น
progressive_mp4
MP4 แบบโปรเกรสซีฟ (ใช้สําหรับคลิปเป็นส่วนใหญ่)
webrtc
WebRTC
cameraStreamNeedAuthToken บูลีน

ต้องระบุ

ระบุโทเค็นการตรวจสอบสิทธิ์ผ่าน cameraStreamAuthToken สําหรับแพลตฟอร์มเป้าหมายเพื่อสตรีมฟีดกล้อง

ตัวอย่าง

กล้องที่มีโปรโตคอลหลายแบบรองรับโดยไม่ต้องใช้โทเค็นการตรวจสอบสิทธิ์

{
  "cameraStreamSupportedProtocols": [
    "webrtc",
    "hls",
    "dash",
    "smooth_stream",
    "progressive_mp4"
  ],
  "cameraStreamNeedAuthToken": false
}

กล้องที่รองรับโปรโตคอลเดี่ยวต้องใช้โทเค็นการตรวจสอบสิทธิ์

{
  "cameraStreamSupportedProtocols": [
    "hls"
  ],
  "cameraStreamNeedAuthToken": true
}

โปรโตคอลสตรีมมิงที่รองรับ

ลักษณะเฉพาะนี้สนับสนุนโปรโตคอลสตรีมมิงต่อไปนี้

อุปกรณ์ STATES

ไม่มี

อุปกรณ์ COMMANDS

อุปกรณ์ที่มีลักษณะเฉพาะนี้อาจตอบสนองต่อคําสั่งต่อไปนี้ในฐานะส่วนหนึ่งของการดําเนินการ EXECUTE หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการ Intent ของ EXECUTE โปรดดูการดําเนินการ Intent

action.devices.commands.GetCameraStream

พารามิเตอร์

พารามิเตอร์ Type คำอธิบาย
StreamToChromecast บูลีน

ต้องระบุ

การสตรีมในอุปกรณ์ Chromecast จะเล่นไหม

SupportedStreamProtocols อาร์เรย์

ต้องระบุ

ประเภทสื่อ/รูปแบบที่รองรับโดยปลายทางที่ต้องการ

[item, ...] สตริง

ประเภทสื่อ

ค่าที่รองรับ:

hls
สตรีมมิงแบบสดของ HTTP
dash
การสตรีมที่ปรับเปลี่ยนได้แบบไดนามิกผ่าน HTTP
smooth_stream
สตรีมมิงได้อย่างราบรื่น
progressive_mp4
MP4 แบบโปรเกรสซีฟ (ใช้สําหรับคลิปเป็นส่วนใหญ่)
webrtc
WebRTC

ผลลัพธ์

ผลลัพธ์ Type คำอธิบาย
cameraStreamAuthToken สตริง

โทเค็นการตรวจสอบสิทธิ์สําหรับผู้รับที่ระบุเพื่อให้สิทธิ์เข้าถึงสตรีม หาก cameraStreamNeedAuthToken เป็นจริงและไม่ได้ระบุค่านี้ ระบบจะใช้ข้อมูลรับรอง OAuth ของผู้ใช้เป็นโทเค็นการตรวจสอบสิทธิ์

cameraStreamProtocol สตริง

ต้องระบุ

รูปแบบสื่อที่ URL ของสตรีมชี้ไป ซึ่งควรเป็นหนึ่งในโปรโตคอลที่แสดงในพารามิเตอร์คําสั่ง SupportedStreamProtocols

ค่าที่รองรับ:

hls
สตรีมมิงแบบสดของ HTTP
dash
Dynamic Adaptive Streaming over HTTP
smooth_stream
สตรีมมิงได้อย่างราบรื่น
progressive_mp4
MP4 แบบโปรเกรสซีฟ (ใช้สําหรับคลิปเป็นส่วนใหญ่)
webrtc
WebRTC

ผลลัพธ์ที่ไม่ใช่ WebRTC

ผลลัพธ์ Type คำอธิบาย
cameraStreamAccessUrl สตริง

ต้องระบุ

ปลายทาง URL สําหรับการเรียกข้อมูลสตรีมแบบเรียลไทม์ในรูปแบบที่ cameraStreamProtocol ระบุ

cameraStreamReceiverAppId สตริง

รหัสเครื่องรับการแคสต์เพื่อประมวลผลสตรีมกล้องเมื่อพารามิเตอร์ StreamToChromecast เป็น "จริง" ระบบจะใช้รีซีฟเวอร์เริ่มต้นหากไม่ได้ระบุไว้

ผลลัพธ์ของ WebRTC

ผลลัพธ์ Type คำอธิบาย
cameraStreamSignalingUrl สตริง

ต้องระบุ

ปลายทาง URL สําหรับการเรียกข้อมูลและแลกเปลี่ยนโปรโตคอลคําอธิบายเซสชัน (SDP) ของกล้องและไคลเอ็นต์ ไคลเอ็นต์ควรแสดงผล URL ส่งสัญญาณซึ่งใช้ cameraStreamAuthToken เป็นโทเค็นการตรวจสอบสิทธิ์ในส่วนหัวของคําขอ

cameraStreamOffer สตริง

โปรโตคอลคําอธิบายเซสชัน (SDP)

cameraStreamIceServers สตริง

แสดงเซิร์ฟเวอร์การเชื่อมต่อเชิงโต้ตอบ (ICE) ที่ใช้สตริง JSON ที่เข้ารหัสพร้อมคําอธิบาย RTCIceServer หากคุณไม่ระบุเซิร์ฟเวอร์ STUN (Session Traversal Utilities for NAT) แพลตฟอร์มจะมีค่าเริ่มต้นเป็นเซิร์ฟเวอร์ STUN สาธารณะของ Google ต้องใช้เซิร์ฟเวอร์ TURN (การส่งผ่านโดยใช้รีเลย์รอบๆ NAT) เฉพาะเมื่อคุณรับประกันไม่ได้ว่า IP / ผู้สมัคร ICE ที่ระบุจะสามารถเข้าถึงได้แบบสาธารณะ (เช่น ผ่านเซิร์ฟเวอร์สื่อ, ผู้สมัคร ICE สาธารณะที่เป็นโฮสต์, ตัวเลือก ICE ส่งต่อ เป็นต้น)

ตัวอย่าง

แสดงกล้องประตูหน้า (ตัวรับการแคสต์เริ่มต้น)

{
  "cameraStreamAccessUrl": "https://fluffysheep.com/baaaaa.mp4",
  "cameraStreamProtocol": "progressive_mp4"
}

แสดงกล้องประตูหน้า (ตัวรับการแคสต์ที่กําหนดเอง)

{
  "cameraStreamAccessUrl": "https://fluffysheep.com/baaaaa.mp4",
  "cameraStreamReceiverAppId": "1g2f89213hg",
  "cameraStreamAuthToken": "12657342190192783",
  "cameraStreamProtocol": "progressive_mp4"
}

แสดงกล้องประตูหน้า (สตรีม WebRTC)

{
  "cameraStreamIceServers": "[{\"urls\": \"stun:stun.l.partner.com:19302\"},{\"urls\":\"turn:192.158.29.39:3478?transport=udp\",\"credential\": \"JZEOEt2V3Qb0y27GRntt2u2PAYA=\",\"username\": \"28224511:1379330808\"},{\"urls\": \"turn:192.158.29.39:3478?transport=tcp\",\"credential\": \"JZEOEt2V3Qb0y27GRntt2u2PAYA=\",\"username\": \"28224511:1379330808\"}]",
  "cameraStreamSignalingUrl": "https://example.com/signaling/answer",
  "cameraStreamOffer": "o=- 4611731400430051336 2 IN IP4 127.0.0.1...",
  "cameraStreamProtocol": "webrtc"
}

อุปกรณ์ ERRORS

ดูรายการข้อผิดพลาดและข้อยกเว้นทั้งหมด

ข้อกําหนดโปรโตคอล WebRTC

ประโยชน์ของการใช้ WebRTC คือเวลาในการตอบสนองต่ําและการสื่อสารทางเดียว WebRTC จะใช้เมธอด POST ที่มีเนื้อความ POST และการตอบสนองในรูปแบบ JSON

ปัจจุบัน WebRTC รองรับ Smart Display ของ Google Nest และ Chromecast ที่มีอุปกรณ์ Google TV

ส่วนนี้จะอธิบายถึงข้อกําหนดเมื่อใช้โปรโตคอลสตรีม WebRTC

ประเภทข้อมูล พารามิเตอร์/คําจํากัดความ
ส่วนหัวของคําขอสัญญาณ

ส่วนหัวควรเป็นไปตามข้อกําหนดเหล่านี้

  • การตรวจสอบสิทธิ์: ส่วนหัวการตรวจสอบสิทธิ์ควรใช้โทเค็นการตรวจสอบสิทธิ์จากค่าการแสดงผล GetCameraStream สําหรับ cameraStreamAuthToken ที่มีประเภทโทเค็นเป็น Bearer
  • ประเภทเนื้อหา: application/json
พารามิเตอร์คําขอสัญญาณ

คําขออาจมีพารามิเตอร์ต่อไปนี้

  • action: สตริง ค่าที่ถูกต้องคือ
    • offer: เสนอข้อความ SDP จากผู้ให้บริการ
    • answer: ตอบข้อความ SDP จากผู้ให้บริการ
    • end: ปิดเซสชันปัจจุบัน
  • deviceId: สตริง รหัสอุปกรณ์ตามที่รายงานในคําขอ SYNC หรือ EXECUTE
  • sdp: สตริง มีข้อความโปรโตคอลคําอธิบายเซสชันสําหรับการเชื่อมต่อเพียร์ เนื้อหาจะอิงตามค่าของพารามิเตอร์ action หาก action คือ "end" พารามิเตอร์นี้อาจว่างเปล่า
พารามิเตอร์การตอบกลับสัญญาณ

การตอบสนองอาจมีพารามิเตอร์ต่อไปนี้

  • action: สตริง ค่าการตอบกลับต้องเป็นประเภท answer
  • sdp: สตริง ข้อความ SDP สําหรับคําตอบที่ตอบกลับ

ข้อกําหนดและคําแนะนําสําหรับ WebRTC

  • ปัจจุบัน Google รองรับการสื่อสารแบบทางเดียว (ครึ่งหนึ่ง)
  • คุณต้องสนับสนุนการรวมกลุ่มอีเมล และ rtcp-mux
  • คุณต้องใช้ (D)TLS 1.2 ขึ้นไป
  • ไม่รองรับ Trickle ICE ต้องรวบรวมผู้สมัคร ICE ทั้งหมดก่อนการส่ง SDP
  • ขอแนะนําอย่างยิ่งให้คุณระบุผู้สมัคร ICE จาก UDP/IPv4, TCP/IPv4, UDP/IPv6 และ TCP/IPv6 เพื่อเพิ่มโอกาสที่การเชื่อมต่อจะสําเร็จ

ความละเอียดวิดีโอที่รองรับ:

  • ขั้นต่ํา: 480p
  • สูงสุด: 1080p

ตัวแปลงรหัสวิดีโอที่สนับสนุนมีดังนี้

  • VP8
  • H.264

ตัวแปลงรหัสเสียงที่รองรับมีดังนี้

  • Opus (ตัวแปลงรหัสที่ต้องการ)
  • G.711/PCMU
  • G.722

กลไกการแชร์ทรัพยากรข้ามโดเมน

Cross-Origin Resource Sharing (CORS) เป็นกลไกที่ใช้ส่วนหัว HTTP เพิ่มเติมในการบอกให้เบราว์เซอร์อนุญาตให้เว็บแอปพลิเคชันที่ทํางานในต้นทางเดียวเข้าถึงทรัพยากรที่เลือกไว้จากต้นทางอื่นได้ เซิร์ฟเวอร์ที่โฮสต์ cameraStreamSignalingUrl ควรตอบกลับด้วยส่วนหัวต่อไปนี้

Access-Control-Allow-Origin: https://www.gstatic.com

ตัวอย่างคําขอและการตอบกลับสัญญาณ

ตัวอย่างต่อไปนี้แสดงคําขอที่ Google ส่งไปยังบริการส่งสัญญาณและการตอบสนองที่สอดคล้องกันไปยัง Google

คําขอ
Header:

Authentication: Bearer <cameraStreamAuthToken>
Content-Type: application/json

POST body:

// When camera offer SDP is provided in the execution response, Google provides an answer SDP.
{
  "action": "answer",
  "deviceId": "123",
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// When camera offer SDP is not provided in execution response, Google generates and provides an offer SDP.
{
  "action": "offer",
  "deviceId": "123",
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// Close the current stream session.
{
  "action": "end"
  "deviceId": "123"
}

คําตอบ
// Response to accept the answer SDP in the request.
Response Code : 200
{}

// Response to provide the answer SDP from the service provider.
Response Code : 200
{
  // When the camera offer SDP is not provided in the execution response,
  // Google provides the answer SDP via the signaling response.
  "action": "answer"
  "sdp": "o=- 4611731400430051336 2 IN IP4 127.0.0.1..."
}

// Response to close current session.
Response Code : 200
{}