Captions

הערה: ב-13 במרץ 2024, YouTube הודיעה שהיא תפסיק להשתמש בפרמטר sync בנקודות הקצה של ה-API‏ captions.insert ו-captions.update. הסנכרון האוטומטי של הכתוביות עדיין זמין ב-YouTube Studio. למידע נוסף, אפשר לעיין בהיסטוריית הגרסאות של ה-API.

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

Methods

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

list
אחזור רשימה של רצועות כתוביות שמשויכות לסרטון מסוים. חשוב לזכור שתגובת ה-API לא מכילה את הכתוביות בפועל, ושהשימוש ב-method‏ captions.download מאפשר לאחזר רצועת כתוביות. רוצים לנסות?
insert
מעלים רצועת כתוביות. כדאי לנסות עכשיו.
עדכון
עדכון של רצועת כתוביות. כשמעדכנים טראק של כתוביות, אפשר לשנות את סטטוס הטיוטה שלו, להעלות קובץ כתוביות חדש לטראק או לבצע את שתי הפעולות האלה. רוצים לנסות?
הורדה
מורידים רצועת כתוביות. טראק הכתוביות מוחזר לפורמט המקורי שלו, אלא אם בבקשה צוין ערך לפרמטר 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
מציין אם רצועת הכתוביות מוגדרת ל'קריאה קלה', כלומר ברמת כיתה ג' ללימוד שפה. ערך ברירת המחדל הוא 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 – אין תמיכה בפורמט של טראק הכתוביות.