# Tijdstempel bijschriften ophalen

Sla een bestaande YouTube titeltrack op met zijn tekst, timing en taal. Voeg een videolink toe aan elk segment voor citaten in het antwoord van uw app of agent.

Canonische referentie: https://flashdata.dev/nl/docs/guides/timestamped-captions-recipe
Beoordeeld: 2026-11-05 door FlashData

<a id="prepare"></a>

## Voordat u begint

Gebruik een sleutel met youtube_captions toestemming en beschikbare credits. Kies Python 3.10+ met verzoeken, of Bash met cURL 7.76+ en jq. Gebruik Git Bash op Windows voor de Bash versie.

- [Een API-sleutel aanmaken](https://flashdata.dev/app/api-keys)
- [Proefgebruik en accountkoppeling](https://flashdata.dev/nl/docs/guides/agent-onboarding/reference.md)
- [Kredieten en prijzen](https://flashdata.dev/nl/docs/guides/credits-and-billing/reference.md)

<a id="input"></a>

## 1. Kies de video- en bijschrifttrack

Maak een map met tijdstempels en sla request.json daar op. Open een terminal in die map. video_id vervangen door 11-karakter ID, niet zijn volledige URL.

Dit voorbeeld vraagt om Engelse automatische bijschriften. Met auto=true, en probeert en-orig eerst, dan en. Expliciete -orig codes en auto=false blijven exact. De API schakelt nooit tussen automatische en uploader-ondertitels.

### timestamped-captions/request.json

```json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": true
  }
}
```

- [Kandidaattalen controleren in metagegevens](https://flashdata.dev/nl/docs/guides/video-metadata-recipe/reference.md#fields)

<a id="run"></a>

## 2. De bijschriften ophalen en opslaan

Kies één versie en sla het script op naast request.json. Het leest FLASHDATA_API_KEY of vraagt om uw sleutel op een verborgen prompt. Agenten moeten die omgevingsvariabele uit hun geheime winkel laden.

Uitvoeren met track-001 als uitvoermap. Een nieuwe map verstuurt één query en slaat het gerapporteerde gebruik op. Alvorens captions.json aan te maken, controleert het script de teruggekeerde video ID, taal, bijschrift oorsprong en segment timings.

### Python

#### Installeer in uw Python omgeving

```bash
python -m pip install requests
```

#### timestamped-captions/captions.py

```python
import argparse
import getpass
import json
import math
import os
import re
from datetime import datetime, timezone
from pathlib import Path

import requests

parser = argparse.ArgumentParser()
parser.add_argument("folder", help="New output folder, or an existing saved caption request")
out = Path(parser.parse_args().folder)

if not out.exists():
    body = Path("request.json").read_bytes()
    request = json.loads(body)
    if (not isinstance(request, dict) or request.get("source") != "youtube_captions"
            or not isinstance(request.get("video_id"), str)
            or not re.fullmatch(r"[A-Za-z0-9_-]{11}", request["video_id"])):
        raise SystemExit("Use youtube_captions and an 11-character video_id")
    options = request.get("params")
    if (not isinstance(options, dict) or not isinstance(options.get("language"), str)
            or not re.fullmatch(r"[A-Za-z0-9-]{1,35}", options["language"])
            or type(options.get("auto")) is not bool):
        raise SystemExit("Set one language code and auto: true or false explicitly")
    key = os.environ.get("FLASHDATA_API_KEY") or getpass.getpass("FlashData API key: ")
    if not key.strip():
        raise SystemExit("An API key is required")
    out.mkdir()
    (out / "request.json").write_bytes(body)
    (out / "requested-at.txt").write_text(
        datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), encoding="utf-8"
    )
    try:
        response = requests.post(
            "https://data.flashdata.dev/v1/queries/realtime",
            headers={"X-API-Key": key, "Content-Type": "application/json",
                     "Accept": "application/json"},
            data=body, timeout=120, allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(f"Request interrupted. Keep {out} and check History before retrying.")
    (out / "result.json").write_bytes(response.content)
    (out / "response-headers.txt").write_text(
        "\n".join(f"{k}: {v}" for k, v in response.headers.items()), encoding="utf-8"
    )
    (out / "http-status.txt").write_text(str(response.status_code), encoding="utf-8")
else:
    print(f"Reading saved response from {out}; no API call.")

if not (out / "http-status.txt").exists():
    raise SystemExit("Incomplete attempt. Keep the folder and check History before retrying.")
status = (out / "http-status.txt").read_text().strip()
if status != "200":
    raise SystemExit(f"HTTP {status}: inspect {out}/result.json and response-headers.txt")
try:
    data = json.loads((out / "result.json").read_bytes())
except ValueError:
    raise SystemExit("Invalid JSON; inspect the saved result.json")
request = json.loads((out / "request.json").read_bytes())
if not isinstance(data, dict) or data.get("source") != "youtube_captions" or data.get("status") != "done":
    raise SystemExit("Caption request did not finish successfully; inspect result.json")
tracks = data.get("results")
if not isinstance(tracks, list) or len(tracks) != 1 or not isinstance(tracks[0], dict):
    raise SystemExit("Expected one caption track; inspect result.json")
track = tracks[0]
language = request["params"]["language"]
allowed_languages = [language]
if request["params"]["auto"] and not language.endswith("-orig"):
    allowed_languages.append(language + "-orig")
if (track.get("videoId") != request["video_id"]
        or track.get("languageCode") not in allowed_languages
        or track.get("requestedLanguageCode", track.get("languageCode")) != language
        or track.get("isAutoGenerated") is not request["params"]["auto"]):
    raise SystemExit("Returned video, language or caption origin does not match the request")
if not isinstance(track.get("segments"), list):
    raise SystemExit("Expected a segments array; inspect result.json")
segments = []
for cue in track["segments"]:
    if not isinstance(cue, dict):
        raise SystemExit("Expected caption segment objects")
    start, end, text = cue.get("start"), cue.get("end"), cue.get("text")
    if (type(start) not in (int, float) or not math.isfinite(start) or start < 0
            or type(end) not in (int, float) or not math.isfinite(end) or end < start
            or not isinstance(text, str)):
        raise SystemExit("Invalid caption timing or text; inspect result.json")
    segments.append({**cue, "url": f"https://www.youtube.com/watch?v={track['videoId']}&t={math.floor(start)}s"})
captions = {**track, "segments": segments}
record = {"request": request, "requested_at": (out / "requested-at.txt").read_text().strip(),
          "usage": data.get("usage"), "segment_count": len(segments), "result_file": "result.json"}
for filename, value in (("captions.json", captions), ("record.json", record)):
    (out / filename).write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
print(f"Saved {len(segments)} segments to {out}/captions.json")
if not any(cue["text"].strip() for cue in segments):
    print("No caption text to cite. Keep the empty track and report the gap.")
```

#### Uitvoeren van tijdstempels/

```bash
python captions.py track-001
```


### Bash

#### Controleer uw gereedschap

```bash
curl --version
jq --version
```

#### timestamped-captions/captions.sh

```bash
#!/usr/bin/env bash
set -euo pipefail
out="${1:?Usage: bash captions.sh OUTPUT_FOLDER}"

if [[ ! -e "$out" ]]; then
  jq -e '.source == "youtube_captions" and
    (.video_id | if type == "string" then length == 11 and test("^[A-Za-z0-9_-]{11}$") else false end) and
    (.params.language | if type == "string" then length > 0 and length <= 35 and
      (test("[^A-Za-z0-9-]") | not) else false end) and
    (.params.auto | type == "boolean")' request.json > /dev/null
  if [[ -z "${FLASHDATA_API_KEY:-}" ]]; then
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
  fi
  : "${FLASHDATA_API_KEY:?An API key is required}"
  mkdir -- "$out"
  cp request.json "$out/request.json"
  date -u +'%Y-%m-%dT%H:%M:%SZ' > "$out/requested-at.txt"
  curl --fail-with-body --silent --show-error --max-time 120 \
    --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --header 'Content-Type: application/json' --header 'Accept: application/json' \
    --data-binary "@$out/request.json" \
    --dump-header "$out/response-headers.txt" --output "$out/result.json" \
    --write-out '%{http_code}' > "$out/http-status.txt" || {
      printf 'Request failed. Keep %s and inspect its saved files before retrying.\n' "$out" >&2
      exit 1
    }
else
  printf 'Reading saved response from %s; no API call.\n' "$out"
fi

if [[ ! -f "$out/http-status.txt" ]] || [[ "$(cat "$out/http-status.txt")" != 200 ]]; then
  printf 'Incomplete or failed attempt. Inspect the saved files and History before retrying.\n' >&2
  exit 1
fi
captions=$(jq -e --slurpfile request "$out/request.json" '
  if .source != "youtube_captions" or .status != "done"
  then error("Expected a successful youtube_captions response") else . end
  | .results
  | if type != "array" then error("Expected a results array")
    elif length != 1 then error("Expected exactly one track") else .[0] end
  | $request[0].params.language as $language
  | if type != "object" then error("Expected a caption object")
    elif .videoId != $request[0].video_id or (.requestedLanguageCode // .languageCode) != $language
      or (.languageCode != $language and ($request[0].params.auto != true
        or ($language | endswith("-orig")) or .languageCode != ($language + "-orig")))
      or .isAutoGenerated != $request[0].params.auto
    then error("Returned video, language or caption origin does not match the request") else . end
  | if (.segments | type) != "array" then error("Expected a segments array") else . end
  | .videoId as $id
  | .segments |= map(
      if type != "object" then error("Expected caption segment objects") else . end
      | if (.start | type) != "number" or (.end | type) != "number" or (.text | type) != "string"
        then error("Invalid caption timing or text")
        elif (.start | isfinite | not) or (.end | isfinite | not) or .start < 0 or .end < .start
        then error("Invalid caption timing")
        else . + {url: ("https://www.youtube.com/watch?v=" + $id + "&t=" + (.start | floor | tostring) + "s")} end
    )' "$out/result.json")
printf '%s\n' "$captions" > "$out/captions.json"
jq --slurpfile request "$out/request.json" --slurpfile captions "$out/captions.json" \
  --arg requested_at "$(tr -d '\r\n' < "$out/requested-at.txt")" \
  '{request: $request[0], requested_at: $requested_at, usage,
    segment_count: ($captions[0].segments | length), result_file: "result.json"}' \
  "$out/result.json" > "$out/record.json"
printf 'Saved %s segments to %s/captions.json\n' "$(jq '.segments | length' "$out/captions.json")" "$out"
if ! jq -e 'any(.segments[]; .text | test("\\S"))' "$out/captions.json" > /dev/null; then
  printf 'No caption text to cite. Keep the empty track and report the gap.\n'
fi
```

#### Uitvoeren van tijdstempels/

```bash
bash captions.sh track-001
```



<a id="output"></a>

## 3. Lees de tekst met de tijdstempel

Succes afdrukken N-segmenten opgeslagen naar track-001/captions.json. Dat bestand behoudt de geretourneerde track en voegt een URL toe aan elk segment. record.json bevat de exacte ingediende aanvraag, requested_at, gebruik en segment_count; result.json behoudt de originele API respons.

### Python

#### Lokaal lezen · geen API-gesprek

```bash
python -m json.tool track-001/captions.json
python -m json.tool track-001/record.json
```


### Bash

#### Lokaal lezen · geen API-gesprek

```bash
cat track-001/captions.json
cat track-001/record.json
```



<a id="expected"></a>

### Voorbeelduitvoer

Afgekort, illustratief captions.json. Je tekst en timing zullen verschillen. languageName kan null zijn; het script houdt het zo.

#### timestamped-captions/track-001/captions.json

```json
{
  "videoId": "FUfGcZ092b0",
  "languageCode": "en",
  "languageName": null,
  "isAutoGenerated": true,
  "segments": [
    {
      "start": 12.5,
      "end": 16.2,
      "text": "This is an illustrative caption segment.",
      "url": "https://www.youtube.com/watch?v=FUfGcZ092b0&t=12s"
    }
  ]
}
```


<a id="cite"></a>

## Een video-passage opzoeken

Druk de eerste drie segmenten af met hun bronlinks. begin en eindig in seconden met hun originele precisie. Alleen de starttijd van de URL wordt naar beneden afgerond: 12.5 seconden worden &t=12s. Segment orde en overlappende timings worden bewaard.

### Python

Bewaar cite.py naast captions.py en voer het vervolgens uit vanuit dezelfde map.

#### timestamped-captions/cite.py

```python
import json
from pathlib import Path

captions = json.loads(Path("track-001/captions.json").read_text(encoding="utf-8"))
for cue in captions["segments"][:3]:
    print(f"[{cue['start']}–{cue['end']}s] {cue['text']}")
    print(cue["url"])
    print()
```

#### Citaties van bewaarde bijschriften afdrukken

```bash
python cite.py
```


### Bash

#### Citaties van bewaarde bijschriften afdrukken

```bash
jq -r '.segments[:3][] |
  "[\(.start)–\(.end)s] \(.text)\n\(.url)\n"' track-001/captions.json
```


- [Bouw een samenvatting met citaten](https://flashdata.dev/nl/docs/guides/youtube-summary/reference.md)

<a id="evidence"></a>

### De bijschriftcontext behouden

Gebruik segmenttekst als bewijs voor een citatie; fullText is nuttig voor het lezen, maar vindt geen passage. Controleer de omliggende segmenten voordat u citeert, vooral voor automatische bijschriften. Behoud languageCode en isAutoGenerated zodat uw app of agent de brontrack kan identificeren.


<a id="reuse"></a>

## De opgeslagen track hergebruiken

Voer hetzelfde commando uit om captions.json te herbouwen vanaf het opgeslagen antwoord, zonder een sleutel of nieuwe query. Het bewerken van de top-level request.json verandert niet het verzoek opgeslagen met track-001.

### Python

#### Lokaal hergebruik

```bash
python captions.py track-001
```


### Bash

#### Lokaal hergebruik

```bash
bash captions.sh track-001
```



<a id="track"></a>

### Kies een andere track

Voor het aanvragen van een uploader met Engelse bijschriften, vervang request.json met deze versie en gebruik track-002. Verander taal alleen naar de code die u van plan bent op te halen, zoals en-orig of zh-Hans. Metadata's transcriptLanguages geeft candidate codes aan, niet of elke code een automatisch of geüploade track heeft.

Het script verwacht één taalreeks. Taalarrays hebben een andere responsvorm met tracks en per-taal fouten; gebruik de API referentie voor die workflow.

#### timestamped-captions/request.json

```json
{
  "source": "youtube_captions",
  "video_id": "FUfGcZ092b0",
  "params": {
    "language": "en",
    "auto": false
  }
}
```

#### Python

##### Nieuwe track · een ander API verzoek

```bash
python captions.py track-002
```


#### Bash

##### Nieuwe track · een ander API verzoek

```bash
bash captions.sh track-002
```


- [Bijschriftparameters en responsvormen](https://flashdata.dev/nl/docs/sources/youtube_captions/reference.md)

<a id="recover"></a>

## Als bijschriften ontbreken of onbruikbaar zijn

| Wat is er gebeurd? | Wat je moet doen |
| --- | --- |
| De geselecteerde track is niet beschikbaar | Controleer de video, taal en automatische selectie. Kies een beschikbare track expliciet; het herhalen van hetzelfde verzoek zal geen bijschriften aanmaken. |
| segments: [] | Een bestaande track kan geen tekst bevatten. Het script slaat de lege track op en rapporteert de kloof. Verander het niet in een transcriptie of samenvatting. |
| Verkeerde oorsprong van video, taal of bijschrift | Er is geen captions.json geschreven. Vergelijk het opgeslagen verzoek met result.json voordat u een tekst gebruikt. |
| Ongeldige timings of ontbrekende segmenten | Inspecteer result.json. Het script stopt in plaats van het toewijzen van uitgevonden tijdstempels of het stil laten vallen van een slecht segment. |
| 401 / 403 / 402 | Controleer de sleutel, youtube_captions permissie en balans, respectievelijk, voordat een nieuwe poging. |
| 429 | Lees Retry-After in response-headers.txt en wacht. Het script wordt niet automatisch opnieuw geprobeerd. |
| Timeout, 5xx, ongeldige JSON of een onvolledige map | Houd de poging en controleer History alvorens opnieuw te verzenden. Hergebruik van de map stuurt nooit een andere query. |

### Python

Bewaar inspect_captions.py naast captions.py, voer het dan uit.

#### timestamped-captions/inspect_captions.py

```python
from pathlib import Path

for name in ("http-status.txt", "response-headers.txt", "result.json"):
    path = Path("track-001") / name
    print(f"--- {name} ---")
    print(path.read_text(encoding="utf-8", errors="replace") if path.exists() else "Not saved")
```

#### Lokaal controleren

```bash
python inspect_captions.py
```


### Bash

#### Lokaal controleren

```bash
for name in http-status.txt response-headers.txt result.json; do
  printf '\n--- %s ---\n' "$name"
  if [[ -f "track-001/$name" ]]; then cat "track-001/$name"; else printf 'Not saved\n'; fi
done
```


- [Geschiedenis aanvragen](https://flashdata.dev/app/jobs)
- [Fouten en statuscodes](https://flashdata.dev/nl/docs/errors/reference.md)
