Captions

توجه: در تاریخ ۱۳ مارس ۲۰۲۴، YouTube اعلام کرد که پارامتر sync را برای captions.insert و نقاط پایانی API captions.update منسوخ می‌کند. همگام‌سازی خودکار زیرنویس ناشنوایان همچنان در «استودیوِ محتواساز YouTube» دردسترس است. برای جزئیات بیشتر، سابقه ویرایش میانای برنامه‌سازی کاربردی را ببینید.

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

روش‌ها

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

فهرست
فهرستی از قطعه‌های زیرنویس ناشنوایان مرتبط با یک ویدیو مشخص را بازیابی کنید. توجه داشته باشید که پاسخ 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
نوع منبع میانای برنامه‌سازی کاربردی را مشخص می‌کند. مقدار 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
نام قطعه زیرنویس ناشنوایان. این نام قرار است به‌عنوان گزینه‌ای درطول بازپخش برای کاربر قابل‌مشاهده باشد. حداکثر طول نام پشتیبانی‌شده ۱۵۰ نویسه است.
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 – قالب قطعه زیرنویس ناشنوایان پشتیبانی نمی‌شود.