Captions

Hinweis: Am 13. März 2024 hat YouTube Folgendes angekündigt: wird der Parameter sync für die captions.insert und captions.update API-Endpunkte. In YouTube Creator Studio ist die automatische Synchronisierung von Untertiteln weiterhin verfügbar. Weitere Informationen finden Sie in der API-Überarbeitungsverlauf für erhalten Sie weitere Informationen.

Eine caption-Ressource steht für einen YouTube-Untertiteltrack. Ein Untertiteltrack ist genau einem YouTube-Video zugeordnet.

Methoden

Die API unterstützt die folgenden Methoden für captions-Ressourcen:

list

Ruft eine Liste der Untertiteltracks ab, die einem bestimmten Video zugeordnet sind. Beachten Sie, dass die API-Antwort nicht die eigentlichen Untertitel enthält und dass die captions.download-Methode die Möglichkeit bietet, einen Untertiteltrack abzurufen. Jetzt testen

insert

Untertitel hochladen

Update

Untertiteltrack aktualisieren Wenn du einen Untertiteltrack aktualisierst, kannst du den Entwurfsstatus des Tracks ändern, eine neue Untertiteldatei für den Track hochladen oder beides.

Delete

Bestimmten Untertiteltrack löschen Hier kannst du die Funktion ausprobieren.

herunterladen

Untertiteltrack herunterladen Der Untertiteltrack wird in seinem ursprünglichen Format zurückgegeben, es sei denn, in der Anfrage wird ein Wert für den Parameter tfmt und in der Originalsprache angegeben, es sei denn, in der Anfrage wird ein Wert für den Parameter tlang angegeben.

Ressourcendarstellung

Die folgende JSON-Struktur zeigt das Format einer captions-Ressource:

{
  "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
  }
}

Attribute

In der folgenden Tabelle werden die Attribute definiert, die in dieser Ressource angezeigt werden:

Attribute
kind	string Identifiziert den Typ der API-Ressource. Der Wert ist youtube#caption.
etag	etag Das ETag dieser Ressource.
id	string Die ID, die YouTube zur eindeutigen Identifizierung des Untertiteltracks verwendet.
snippet	object Das Objekt snippet enthält grundlegende Details zum Untertitel.
snippet.videoId	string Die ID, die YouTube verwendet, um das mit dem Untertiteltrack verknüpfte Video eindeutig zu identifizieren.
snippet.lastUpdated	datetime Datum und Uhrzeit der letzten Aktualisierung des Untertiteltracks Der Wert wird im ISO 8601-Format angegeben.
snippet.trackKind	string Der Typ des Untertiteltracks. Gültige Werte für diese Eigenschaft sind: ASR: Ein Untertiteltrack, der mithilfe der automatischen Spracherkennung erstellt wurde. forced: Ein Untertiteltrack, der abgespielt wird, wenn kein anderer Track im Player ausgewählt ist. Ein Beispiel: In einem Video, in dem Aliens in einer außerirdischen Sprache sprechen, kann es sein, dass in einem Untertiteltrack nur Untertitel für diese Sprache angezeigt werden. standard – ein regulärer Untertiteltrack. „Immer“ ist der Standardwert.
snippet.language	string Die Sprache des Untertiteltracks. Der Attributwert ist ein BCP-47-Sprachtag.
snippet.name	string Der Name des Untertiteltracks. Der Name soll Nutzern während der Wiedergabe als Option angezeigt werden. Der Name darf maximal 150 Zeichen lang sein.
snippet.audioTrackType	string Der Typ des Audiotracks, der mit dem Untertiteltrack verknüpft ist. Gültige Werte für diese Eigenschaft sind: commentary – Der Untertiteltrack entspricht einem alternativen Audiotrack mit Kommentaren, z. B. einem Kommentar zum Verzeichnis. descriptive: Der Untertiteltrack entspricht einem alternativen Audiotrack, der zusätzliche beschreibende Audioinhalte enthält. primary: Der Untertiteltrack entspricht dem primären Audiotrack des Videos, also dem Audiotrack, der normalerweise zum Video gehört. unknown: Dies ist der Standardwert.
snippet.isCC	boolean Gibt an, ob der Titel Untertitel für gehörlose und schwerhörige Nutzer enthält. Der Standardwert ist false.
snippet.isLarge	boolean Gibt an, ob der Untertiteltrack großen Text für Sehbehinderte verwendet. Der Standardwert ist false.
snippet.isEasyReader	boolean Gibt an, ob der Untertiteltrack für einfachen Lesemodus formatiert ist, d. h. für Lernende der dritten Klasse. Der Standardwert ist false.
snippet.isDraft	boolean Gibt an, ob der Untertiteltrack ein Entwurf ist. Lautet der Wert true, ist der Titel nicht öffentlich sichtbar. Der Standardwert ist false.
snippet.isAutoSynced	boolean Gibt an, ob YouTube den Untertiteltrack mit dem Audiotrack im Video synchronisiert hat. Der Wert ist true, wenn beim Hochladen des Untertiteltracks explizit eine Synchronisierung angefordert wurde. Wenn du beispielsweise die Methoden captions.insert oder captions.update aufrufst, kannst du den Parameter sync auf true setzen, um YouTube anzuweisen, den hochgeladenen Titel mit dem Video zu synchronisieren. Wenn der Wert false ist, verwendet YouTube die Zeitcodes im hochgeladenen Untertiteltrack, um zu bestimmen, wann Untertitel angezeigt werden sollen.
snippet.status	string Der Status des Untertiteltracks. Gültige Werte für diese Property: failed serving syncing
snippet.failureReason	string Der Grund, warum YouTube den Untertiteltrack nicht verarbeiten konnte. Diese Eigenschaft ist nur vorhanden, wenn der Wert der Eigenschaft state failed ist. Gültige Werte für diese Eigenschaft sind: processingFailed: Der hochgeladene Untertiteltrack konnte von YouTube nicht verarbeitet werden. unknownFormat: Das Format des Untertiteltracks wurde nicht erkannt. unsupportedFormat: Das Format des Untertiteltracks wird nicht unterstützt.