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.