Captions

หมายเหตุ: เมื่อวันที่ 13 มีนาคม 2024 YouTube ได้ประกาศว่าจะเลิกใช้งานพารามิเตอร์ sync สำหรับปลายทาง API ของ captions.insert และ captions.update การซิงค์คำบรรยายอัตโนมัติจะยังคงใช้งานได้ใน YouTube Creator Studio ดูรายละเอียดเพิ่มเติมได้ที่ประวัติการแก้ไข API

ทรัพยากร caption แสดงถึงแทร็กคำบรรยายแทนเสียงของ YouTube แทร็กคำบรรยายจะเชื่อมโยงกับวิดีโอ YouTube เพียงรายการเดียว

เมธอด

API รองรับวิธีการต่อไปนี้สำหรับทรัพยากร captions

list
ดึงข้อมูลรายการแทร็กคำบรรยายที่เชื่อมโยงกับวิดีโอที่ระบุ โปรดทราบว่าการตอบกลับของ API ไม่มีคำบรรยายจริง และเมธอด captions.download ช่วยให้ดึงข้อมูลแทร็กคำบรรยายได้ ลองใช้เลย
แทรก
อัปโหลดแทร็กคำบรรยายแทนเสียง ลองใช้เลย
update
อัปเดตแทร็กคำบรรยายแทนเสียง เมื่ออัปเดตแทร็กคำบรรยายแทนเสียง คุณจะเปลี่ยนสถานะฉบับร่างของแทร็ก อัปโหลดไฟล์คำบรรยายแทนเสียงใหม่สำหรับแทร็ก หรือทั้ง 2 อย่างก็ได้ ลองใช้เลย
download
ดาวน์โหลดแทร็กคำบรรยายแทนเสียง ระบบจะเปลี่ยนแทร็กคำบรรยายแทนเสียงกลับเป็นรูปแบบเดิม เว้นแต่คำขอจะระบุค่าสำหรับพารามิเตอร์ tfmt และเปลี่ยนกลับเป็นภาษาต้นฉบับ เว้นแต่คำขอจะระบุค่าสำหรับพารามิเตอร์ tlang ลองใช้เลย
ลบ
ลบแทร็กคำบรรยายแทนเสียงที่ระบุ ลองใช้เลย

การนําเสนอทรัพยากร

โครงสร้าง JSON ต่อไปนี้แสดงรูปแบบของทรัพยากร captions

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

พร็อพเพอร์ตี้

ตารางต่อไปนี้จะกำหนดพร็อพเพอร์ตี้ที่ปรากฏในทรัพยากรนี้

พร็อพเพอร์ตี้
kind string
ระบุประเภทของทรัพยากร API ค่าจะเป็น youtube#caption
etag etag
Etag ของทรัพยากรนี้
id string
รหัสที่ YouTube ใช้เพื่อระบุแทร็กคำบรรยายแทนเสียงที่ไม่ซ้ำกัน
snippet object
ออบเจ็กต์ snippet มีรายละเอียดพื้นฐานเกี่ยวกับคำบรรยาย
snippet.videoId string
รหัสที่ YouTube ใช้เพื่อระบุวิดีโอที่เชื่อมโยงกับแทร็กคำบรรยายแทนเสียงโดยไม่ซ้ำกัน
snippet.lastUpdated datetime
วันที่และเวลาที่อัปเดตแทร็กคำบรรยายแทนเสียงครั้งล่าสุด ค่าที่ระบุอยู่ในรูปแบบ ISO 8601
snippet.trackKind string
ประเภทของแทร็กคำบรรยายแทนเสียง

ค่าที่ใช้ได้สำหรับพร็อพเพอร์ตี้นี้มีดังนี้
  • ASR – แทร็กคำบรรยายที่สร้างขึ้นโดยใช้การจดจำคำพูดอัตโนมัติ
  • forced – แทร็กคำบรรยายที่เล่นเมื่อไม่มีการเลือกแทร็กอื่นในโปรแกรมเล่น เช่น วิดีโอที่แสดงมนุษย์ต่างดาวพูดภาษามนุษย์ต่างดาวอาจมีแทร็กคำบรรยายที่บังคับให้แสดงเฉพาะคำบรรยายสำหรับภาษามนุษย์ต่างดาว
  • standard – แทร็กคำบรรยายแทนเสียงปกติ นี่คือค่าเริ่มต้น
snippet.language string
ภาษาของแทร็กคำบรรยายแทนเสียง ค่าพร็อพเพอร์ตี้คือแท็กภาษา BCP-47
snippet.name string
ชื่อแทร็กคำบรรยายแทนเสียง ชื่อนี้มีไว้เพื่อให้ผู้ใช้เห็นเป็นตัวเลือกระหว่างการเล่น ชื่อมีความยาวได้สูงสุด 150 อักขระ
snippet.audioTrackType string
ประเภทของแทร็กเสียงที่เชื่อมโยงกับแทร็กคำบรรยายแทนเสียง

ค่าที่ใช้ได้สำหรับพร็อพเพอร์ตี้นี้มีดังนี้
  • commentary – แทร็กคำบรรยายแทนเสียงสอดคล้องกับแทร็กเสียงสำรองที่มีคําบรรยาย เช่น คําบรรยายของไดเรกทอรี
  • descriptive – แทร็กคำบรรยายแทนเสียงสอดคล้องกับแทร็กเสียงสำรองที่มีเสียงบรรยายเพิ่มเติม
  • primary – แทร็กคำบรรยายแทนเสียงจะสอดคล้องกับแทร็กเสียงหลักของวิดีโอ ซึ่งเป็นแทร็กเสียงที่เชื่อมโยงกับวิดีโอตามปกติ
  • unknown – ค่าเริ่มต้น
snippet.isCC boolean
ระบุว่าแทร็กมีคำบรรยายแทนเสียงสำหรับคนหูหนวกหรือมีปัญหาในการได้ยินหรือไม่ ค่าเริ่มต้นคือ false
snippet.isLarge boolean
ระบุว่าแทร็กคำบรรยายแทนเสียงใช้ข้อความขนาดใหญ่สำหรับผู้ที่มีความบกพร่องทางสายตาหรือไม่ ค่าเริ่มต้นคือ false
snippet.isEasyReader boolean
บ่งบอกว่าแทร็กคำบรรยายมีการจัดรูปแบบสำหรับ "ผู้อ่านง่าย" หรือไม่ ซึ่งหมายความว่ามีระดับเป็นชั้นประถมศึกษาปีที่ 3 สําหรับผู้เรียนภาษา ค่าเริ่มต้นคือ false
snippet.isDraft boolean
ระบุว่าแทร็กคำบรรยายแทนเสียงเป็นฉบับร่างหรือไม่ หากค่าคือ true แทร็กจะไม่แสดงแบบสาธารณะ ค่าเริ่มต้นคือ false
snippet.isAutoSynced boolean
ระบุว่า YouTube ซิงค์แทร็กคำบรรยายแทนเสียงกับแทร็กเสียงในวิดีโอหรือไม่ ค่าจะเป็น true หากมีการขอการซิงค์อย่างชัดเจนเมื่ออัปโหลดแทร็กคำบรรยายแทนเสียง ตัวอย่างเช่น เมื่อเรียกใช้เมธอด captions.insert หรือ captions.update คุณสามารถตั้งค่าพารามิเตอร์ sync เป็น true เพื่อสั่งให้ YouTube ซิงค์แทร็กที่อัปโหลดกับวิดีโอ หากค่าคือ false แสดงว่า YouTube จะใช้รหัสเวลาในแทร็กคำบรรยายแทนเสียงที่อัปโหลดเพื่อกำหนดเวลาในการแสดงคำบรรยายแทนเสียง
snippet.status string
สถานะของแทร็กคำบรรยายแทนเสียง

ค่าที่ใช้ได้สำหรับพร็อพเพอร์ตี้นี้มีดังนี้
  • failed
  • serving
  • syncing
snippet.failureReason string
สาเหตุที่ YouTube ประมวลผลแทร็กคำบรรยายแทนเสียงไม่สำเร็จ พร็อพเพอร์ตี้นี้จะแสดงก็ต่อเมื่อค่าของพร็อพเพอร์ตี้ state เป็น failed

ค่าที่ถูกต้องสำหรับพร็อพเพอร์ตี้นี้ ได้แก่
  • processingFailed – YouTube ประมวลผลแทร็กคำบรรยายวิดีโอที่อัปโหลดไม่สำเร็จ
  • unknownFormat – ระบบไม่รู้จักรูปแบบของแทร็กคำบรรยาย
  • unsupportedFormat – ระบบไม่รองรับรูปแบบของแทร็กคำบรรยายแทนเสียง