דף זה תורגם על ידי Cloud Translation API.

Captions

הערה: ב-5 באוגוסט 2022, הצוות של YouTube הכריז על השינוי באופן שבו המזהים של הכתוביות נוצרים, ובמסגרת השינוי הזה אנחנו משייכים מזהי כתוביות חדשים לכל טראקים של כתוביות. פרטים נוספים זמינים בהיסטוריית גרסאות ה-API.

משאב caption מייצג טראק כתוביות ב-YouTube. רצועת כתוביות משויכת לסרטון YouTube אחד בדיוק.

שיטות

ה-API תומך בשיטות הבאות עבור משאבי captions:

list: אחזר רשימה של רצועות כתוביות המשויכות לסרטון ספציפי. לתשומת ליבך, תגובת ה-API לא מכילה את הכתוביות בפועל, ושהשיטה captions.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` התג של המשאב הזה.
`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` השם של רצועת הכתוביות. השם נועד להיות גלוי למשתמש כאפשרות במהלך ההפעלה.
`snippet.audioTrackType`	`string` הסוג של טראק האודיו שמשויך לטראק של הכתוביות. הערכים החוקיים לנכס הזה הם: `commentary` – טראק הכתוביות תואם לטראק אודיו חלופי שכולל פרשנות, כמו פרשנות בספרייה. `descriptive` – טראק הכתוביות תואם לטראק אודיו חלופי שכולל אודיו תיאורי נוסף. `primary` – טראק האודיו תואם לטראק הראשי של הסרטון, שהוא טראק האודיו שמשויך בדרך כלל לסרטון. `unknown` – זהו ערך ברירת המחדל.
`snippet.isCC`	`boolean` מציין אם הטראק כולל כתוביות סגורות לחירשים ולכבדי שמיעה. ערך ברירת המחדל הוא `false`.
`snippet.isLarge`	`boolean` מציין אם טראק הכתוביות משתמש בטקסט גדול ללקויי ראייה. ערך ברירת המחדל הוא `false`.
`snippet.isEasyReader`	`boolean` מציין אם שפת הכתוביות היא 'קורא קל', כלומר היא מיועדת לרמה שלישית עבור אנשים שלומדים שפה. ערך ברירת המחדל הוא `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` – אין תמיכה בפורמט של רצועת הכתוביות.