# Récupérer des sous-titres horodatés

Enregistrez une piste de sous-titres YouTube existante avec son texte, ses horodatages et sa langue. Ajoutez un lien vidéo à chaque segment pour citer les passages dans votre application ou dans la réponse de votre agent.

Référence canonique : https://flashdata.dev/fr/docs/guides/timestamped-captions-recipe
Vérifié le 2026-11-05 par FlashData

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

## Avant de commencer

Utilisez une clé autorisant youtube_captions et un compte disposant de crédits. Choisissez Python 3.10+ avec requests, ou Bash avec cURL 7.76+ et jq. Sous Windows, utilisez Git Bash pour la version Bash.

- [Obtenir une clé API](https://flashdata.dev/app/api-keys)
- [Essai agent et rattachement au compte](https://flashdata.dev/fr/docs/guides/agent-onboarding/reference.md)
- [Crédits et tarifs](https://flashdata.dev/fr/docs/guides/credits-and-billing/reference.md)

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

## 1. Choisir la vidéo et la piste de sous-titres

Créez un dossier timestamped-captions et enregistrez-y request.json. Ouvrez un terminal dans ce dossier. Remplacez video_id par l’identifiant à 11 caractères de la vidéo, et non son URL complète.

Cet exemple demande les sous-titres automatiques en anglais. Avec auto=true, en essaie d’abord en-orig, puis en. Un code explicite se terminant par -orig ou une requête avec auto=false reste exact. L’API ne bascule jamais entre les sous-titres automatiques et ceux fournis par l’auteur.

### timestamped-captions/request.json

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

- [Consulter les langues possibles dans les métadonnées](https://flashdata.dev/fr/docs/guides/video-metadata-recipe/reference.md#fields)

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

## 2. Récupérer et enregistrer les sous-titres

Choisissez une version et enregistrez son script à côté de request.json. Il lit FLASHDATA_API_KEY ou vous demande la clé sans l’afficher. Les agents doivent charger cette variable d’environnement depuis leur gestionnaire de secrets.

Utilisez track-001 comme dossier de sortie. Un nouveau dossier déclenche une requête et enregistre sa consommation déclarée. Avant de créer captions.json, le script vérifie l’identifiant vidéo, la langue, l’origine des sous-titres et les horodatages des segments retournés.

### Python

#### Installer dans votre environnement Python

```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.")
```

#### Exécuter depuis timestamped-captions/

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


### Bash

#### Vérifier les outils

```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
```

#### Exécuter depuis timestamped-captions/

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



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

## 3. Lire le texte horodaté

En cas de succès, le script affiche Saved N segments to track-001/captions.json. Ce fichier conserve la piste retournée et ajoute une URL à chaque segment. record.json contient la requête exacte, requested_at, usage et segment_count ; result.json conserve la réponse API d’origine.

### Python

#### Lire localement · aucun appel API

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


### Bash

#### Lire localement · aucun appel API

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



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

### Exemple de sortie

Extrait illustratif de captions.json. Le texte et les horodatages retournés seront différents. languageName peut valoir null ; le script conserve cette valeur.

#### 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>

## Citer un passage de la vidéo

Affichez les trois premiers segments avec leurs liens source. start et end restent en secondes avec leur précision d’origine. Seul le début dans l’URL est arrondi à l’entier inférieur : 12,5 secondes devient &t=12s. L’ordre des segments et les chevauchements temporels sont conservés.

### Python

Enregistrez cite.py à côté de captions.py, puis exécutez-le depuis ce même dossier.

#### 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()
```

#### Afficher les citations des sous-titres enregistrés

```bash
python cite.py
```


### Bash

#### Afficher les citations des sous-titres enregistrés

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


- [Créer un résumé avec des citations](https://flashdata.dev/fr/docs/guides/youtube-summary/reference.md)

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

### Conserver le contexte des sous-titres

Utilisez le texte du segment pour étayer une citation ; fullText facilite la lecture, mais ne situe pas un passage. Lisez les segments voisins avant de citer, surtout pour les sous-titres automatiques. Conservez languageCode et isAutoGenerated pour que votre application ou votre agent identifie la piste source.


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

## Réutiliser la piste enregistrée

Relancez la même commande pour reconstruire captions.json à partir de la réponse enregistrée, sans clé ni nouvelle requête. Modifier request.json à la racine du dossier ne change pas la requête conservée dans track-001.

### Python

#### Réutiliser localement

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


### Bash

#### Réutiliser localement

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



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

### Choisir une autre piste

Pour demander les sous-titres anglais fournis par l’auteur, remplacez request.json par cette version et utilisez track-002. Définissez language sur le code que vous souhaitez récupérer, par exemple en-orig ou zh-Hans. Le champ transcriptLanguages des métadonnées liste les codes possibles, sans indiquer si chacun possède une piste automatique ou fournie par l’auteur.

Le script attend une seule langue sous forme de chaîne. Les tableaux de langues produisent une réponse différente, avec tracks et des erreurs par langue ; consultez la référence API pour ce cas.

#### timestamped-captions/request.json

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

#### Python

##### Nouvelle piste · nouvelle requête API

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


#### Bash

##### Nouvelle piste · nouvelle requête API

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


- [Paramètres des sous-titres et structures de réponse](https://flashdata.dev/fr/docs/sources/youtube_captions/reference.md)

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

## Si les sous-titres sont absents ou inutilisables

| Problème | Solution |
| --- | --- |
| La piste sélectionnée est indisponible | Vérifiez la vidéo, la langue et la valeur de auto. Choisissez explicitement une piste disponible ; répéter la même requête ne crée pas de sous-titres. |
| segments: [] | Une piste existante peut ne contenir aucun texte. Le script enregistre cette piste vide et signale l’absence de contenu. N’en produisez pas une transcription ou un résumé. |
| Vidéo, langue ou origine des sous-titres incorrecte | Aucun fichier captions.json n’est écrit. Comparez la requête enregistrée à result.json avant d’utiliser le texte. |
| Horodatages invalides ou segments absents | Inspectez result.json. Le script s’arrête au lieu d’inventer des horodatages ou d’omettre silencieusement un segment incorrect. |
| 401 / 403 / 402 | Vérifiez respectivement la clé, l’autorisation youtube_captions et le solde avant une nouvelle tentative. |
| 429 | Lisez Retry-After dans response-headers.txt et attendez. Le script ne réessaie pas automatiquement. |
| Délai dépassé, erreur 5xx, JSON invalide ou dossier incomplet | Conservez la tentative et consultez History avant de soumettre à nouveau la requête. Réutiliser son dossier n’envoie jamais de nouvelle requête. |

### Python

Enregistrez inspect_captions.py à côté de captions.py, puis exécutez-le.

#### 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")
```

#### Inspecter localement

```bash
python inspect_captions.py
```


### Bash

#### Inspecter localement

```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
```


- [Historique des requêtes](https://flashdata.dev/app/jobs)
- [Erreurs et codes d’état](https://flashdata.dev/fr/docs/errors/reference.md)
