Captions

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

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

วิธีการ

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

list
เรียกข้อมูลรายการแทร็กคำบรรยายที่เชื่อมโยงกับวิดีโอที่ระบุ โปรดทราบว่าการตอบกลับของ API ไม่มีคำบรรยายจริงและเมธอด captions.download มอบความสามารถในการเรียกแทร็กคำบรรยาย ลองเลย
แทรก
อัปโหลดแทร็กคำบรรยายวิดีโอ
อัปเดต
อัปเดตแทร็กคำบรรยายวิดีโอ เมื่ออัปเดตแทร็กคำบรรยายวิดีโอ คุณสามารถเปลี่ยนสถานะฉบับร่างของแทร็ก อัปโหลดไฟล์คำบรรยายวิดีโอใหม่สำหรับแทร็ก หรือทั้ง 2 แทร็กได้
ลบ
ลบแทร็กคำบรรยายวิดีโอที่ระบุไว้ ลองใช้เลย
ดาวน์โหลด
ดาวน์โหลดแทร็กคำบรรยายวิดีโอ แทร็กคำบรรยายจะส่งกลับมาในรูปแบบดั้งเดิม เว้นแต่คำขอจะระบุค่าสำหรับพารามิเตอร์ 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 – ไม่รองรับรูปแบบของแทร็กคำบรรยาย