Captions

Hinweis:Am 13. März 2024 hat YouTube angekündigt, den Parameter sync für die API-Endpunkte captions.insert und captions.update einzustellen. Die automatische Synchronisierung von Untertiteln ist weiterhin in YouTube Studio verfügbar. Weitere Informationen finden Sie im Überarbeitungsverlauf der API.

Eine caption-Ressource stellt eine YouTube-Untertitelspur dar. Ein Untertiteltrack ist genau einem YouTube-Video zugeordnet.

Methoden

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

list
Liste der Untertiteltracks abrufen, die mit einem bestimmten Video verknüpft sind Die API-Antwort enthält nicht die eigentlichen Untertitel. Mit der captions.download-Methode kannst du einen Untertiteltrack abrufen. Jetzt testen
insert
Lade einen Untertiteltrack hoch. Hier kannst du die Funktion ausprobieren.
aktualisieren
Untertiteltrack aktualisieren Wenn du einen Untertiteltrack aktualisierst, kannst du den Status des Tracks als Entwurf ändern, eine neue Untertiteldatei für den Track hochladen oder beides. Jetzt testen
herunterladen
Lade einen Untertiteltrack herunter. Der Untertiteltrack wird im Originalformat zurückgegeben, es sei denn, in der Anfrage wird ein Wert für den Parameter tfmt angegeben. Er wird auch in der Originalsprache zurückgegeben, es sei denn, in der Anfrage wird ein Wert für den Parameter tlang angegeben. Jetzt testen
Delete
Bestimmten Untertiteltrack löschen Hier kannst du die Funktion ausprobieren.

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 Eigenschaften 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, mit der YouTube den Untertiteltrack eindeutig identifiziert.
snippet object
Das snippet-Objekt enthält grundlegende Details zur Untertitelung.
snippet.videoId string
Die ID, mit der YouTube das Video, das mit dem Untertitel-Track verknüpft ist, eindeutig identifiziert.
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 Untertitel-Tracks.

Gültige Werte für dieses Attribut sind:
  • ASR – ein Untertiteltrack, der mithilfe der automatischen Spracherkennung erstellt wurde.
  • forced – Ein Untertiteltrack, der wiedergegeben wird, wenn im Player kein anderer Track ausgewählt ist. In einem Video, in dem Aliens in einer fremden Sprache sprechen, kann beispielsweise ein Untertiteltrack erzwungen werden, damit nur Untertitel für die fremde Sprache angezeigt werden.
  • standard – ein regulärer Untertiteltrack. „Immer“ ist der Standardwert.
snippet.language string
Die Sprache des Untertitel-Tracks. Der Property-Wert ist ein BCP-47-Sprachtag.
snippet.name string
Der Name des Untertitel-Tracks. 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 Property sind:
  • commentary – Der Untertiteltrack entspricht einem alternativen Audiotrack mit Kommentaren, z. B. einem Kommentar zum Verzeichnis.
  • descriptive – Der Untertiteltrack entspricht einem alternativen Audiotrack mit zusätzlicher Audiodeskription.
  • primary – Der Untertiteltrack entspricht dem primären Audiotrack des Videos, also dem Audiotrack, der normalerweise mit dem Video verknüpft ist.
  • unknown: Das ist der Standardwert.
snippet.isCC boolean
Gibt an, ob der Titel Untertitel für Gehörlose und Schwerhörige enthält. Der Standardwert ist false.
snippet.isLarge boolean
Gibt an, ob im Untertiteltrack großer Text für sehbehinderte Personen verwendet wird. Der Standardwert ist false.
snippet.isEasyReader boolean
Gibt an, ob der Untertitel-Track für „leichte Leser“ formatiert ist, d. h. auf dem Niveau einer dritten Klasse für Sprachlernende. Der Standardwert ist false.
snippet.isDraft boolean
Gibt an, ob es sich bei dem Untertiteltrack um einen Entwurf handelt. Wenn der Wert true ist, ist der Titel nicht öffentlich sichtbar. Der Standardwert ist false.
snippet.isAutoSynced boolean
Gibt an, ob YouTube die Untertitelspur mit der Audiospur im Video synchronisiert hat. Der Wert ist true, wenn beim Hochladen des Untertitel-Tracks eine Synchronisierung ausdrücklich angefordert wurde. Wenn du beispielsweise die Methoden captions.insert oder captions.update aufrufst, kannst du den Parameter sync auf true festlegen, 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 Untertitel-Tracks.

Gültige Werte für dieses Attribut sind:
  • failed
  • serving
  • syncing
snippet.failureReason string
Der Grund, warum YouTube den Untertiteltrack nicht verarbeiten konnte. Diese Property ist nur vorhanden, wenn der Wert der Property state failed ist.

Gültige Werte für diese Property sind:
  • processingFailed – YouTube konnte den hochgeladenen Untertiteltrack nicht verarbeiten.
  • unknownFormat: Das Format des Untertitel-Tracks wurde nicht erkannt.
  • unsupportedFormat – Das Format des Untertitel-Tracks wird nicht unterstützt.