این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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: یک تراک شرح را به‌روزرسانی کنید. هنگام به‌روزرسانی یک تراک شرح، می‌توانید وضعیت پیش‌نویس آهنگ را تغییر دهید، یک فایل شرح جدید برای آهنگ یا هر دو آپلود کنید.
delete: یک تراک شرح مشخص شده را حذف کنید. الآن امتحانش کن .
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` 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` - فرمت آهنگ شرح پشتیبانی نمی شود.