Captions

توجه: در 13 مارس 2024، YouTube اعلام کرد که پارامتر sync را برای نقاط انتهایی API captions.insert و captions.update منسوخ می‌کند. همگام‌سازی خودکار زیرنویس‌ها همچنان در YouTube Creator Studio در دسترس است. برای جزئیات بیشتر به تاریخچه ویرایش API مراجعه کنید.

یک منبع caption یک تراک شرح YouTube را نشان می دهد. یک تراک شرح دقیقاً با یک ویدیوی YouTube مرتبط است.

روش ها

API از روش‌های زیر برای منابع captions پشتیبانی می‌کند:

list
فهرستی از تراک‌های شرح مرتبط با یک ویدیوی مشخص را بازیابی کنید. توجه داشته باشید که پاسخ API شامل زیرنویس‌های واقعی نیست و روش captions.download توانایی بازیابی یک تراک شرح را فراهم می‌کند. اکنون آن را امتحان کنید .
insert
یک تراک شرح بارگذاری کنید. اکنون آن را امتحان کنید .
update
یک تراک شرح را به‌روزرسانی کنید. هنگام به‌روزرسانی یک تراک شرح، می‌توانید وضعیت پیش‌نویس آهنگ را تغییر دهید، یک فایل شرح جدید برای آهنگ یا هر دو آپلود کنید. اکنون آن را امتحان کنید .
download
دانلود یک تراک شرح. تراک عنوان به فرمت اصلی خود برگردانده می شود مگر اینکه درخواست مقداری برای پارامتر tfmt و به زبان اصلی آن مشخص کند مگر اینکه درخواست مقداری برای پارامتر tlang مشخص کند. اکنون آن را امتحان کنید .
delete
یک تراک شرح مشخص شده را حذف کنید. اکنون آن را امتحان کنید .

نمایندگی منابع

ساختار 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
دلیل شکست یوتیوب در پردازش تراک شرح. این ویژگی تنها در صورتی وجود دارد که ارزش ویژگی state failed باشد.

مقادیر معتبر برای این ویژگی عبارتند از:
  • processingFailed – یوتیوب نتوانست آهنگ شرح آپلود شده را پردازش کند.
  • unknownFormat – فرمت تراک شرح شناسایی نشد.
  • unsupportedFormat - فرمت آهنگ شرح پشتیبانی نمی شود.