# استرجاع الأزمنة المأخوذة

(أ) أن يُوفّر مساراً قائماً في إطار سقف YouTube مع نصه وتوقيته ولغته. أضف وصلة فيديو إلى كل جزء من أجل إستشهاد في تطبيقك أو جواب العميل

مرجع كانوني: https://flashdata.dev/ar/docs/guides/timestamped-captions-recipe
Reviewed: 2026-11-05 by FlashData

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

## قبل أن تبدأ

استخدم مفتاحًا بصلاحية youtube_captions ورصيد متاح. اختر Python 3.10+ مع requests أو Bash مع cURL 7.76+ وjq. على Windows، استخدم Git Bash لنسخة Bash.

- [احصل على مفتاح API](https://flashdata.dev/app/api-keys)
- [تجربة الوكيل وربط الحساب](https://flashdata.dev/ar/docs/guides/agent-onboarding/reference.md)
- [الأرصدة الدائنة والتسعير](https://flashdata.dev/ar/docs/guides/credits-and-billing/reference.md)

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

## 1. اختر شريط الفيديو وتتبع الاختباء

إنشاء مطوّر لقطع العينات وإنقاذ request.json هناك. افتح محطة طرفية في ذلك الملف. استبدال video_id بالفيديو 11-character ID، وليس كامل URL.

ويطالب هذا المثال باختطافات تلقائية باللغة الانكليزية. بالسياراتtrue"إنّه يحاول أن يُحاكم أولاً، ثمّ "إس رموز أوتوماتيكياتfalse إبقي على وجه الدقة. The API لا تبدل أبداً بين الأصفاد التلقائية و المزودة بأجهزة تحميل

### timestamped-captions/request.json

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

- [التحقق من لغات المرشحين في البيانات الفوقية](https://flashdata.dev/ar/docs/guides/video-metadata-recipe/reference.md#fields)

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

## 2. إجلبْ وإنقذْ الأسرَّةَ

اختر نسخة واحدة واحفظ نصها بجانبها request.json. إنه يقرأ FLASHDATA_API_KEY أو يطلب مفتاحك في عجل مخفي العملاء يجب أن يحمّلون تلك البيئة المتغيّرة من متجرهم السري.

أركض مع المسار001 كمجلد النواتج ويرسل ملف جديد استفساراً واحداً ويحتفظ باستخدامه المبلغ عنه. وقبل إنشاء captions.json، يتحقق النص من الفيديو الذي أعيد تسجيله ID، واللغة، ومصدر الإخفاء، وتوقيتات الأجزاء.

### Python

#### ضع في رأسك 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.")
```

#### الهروب من العيوب/المصابة بأوقات

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


### Bash

#### تحقق من أدواتك

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

#### الهروب من العيوب/المصابة بأوقات

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



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

## 3. اقرأ النص المصور

طبعة ناجحة محتفظة بقطع غير موزعة على track-001/captions.json. ويحفظ هذا الملف المسار المعادي ويضيف إلى كل جزء من أجزاء URL. ويحتوي record.json على الطلب المقدم على وجه الدقة، وهو requested_at، ورقم الاستخدام، ورقم segment_count؛ ويحتفظ result.json برد API الأصلي.

### Python

#### القراءة محلياً؛ لا API اتصلي

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


### Bash

#### القراءة محلياً؛ لا API اتصلي

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



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

### الناتج المثالي

Abbreviated, illustrative captions.json. رسالتك وتوقيتك ستختلفان languageName قد يكون nullالنص يبقيه هكذا

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

## قم بتصوير مقطع فيديو

طباعة الأجزاء الثلاثة الأولى بوصلات مصدرها، ابدأوا و ينتهيوا بالبقاء في ثوانٍ بدقتها الأصلية. فقط URL"وقت البدء مُقَوَّل" 12.5 تصبح الثواني=12S. ويجري الحفاظ على نظام الفصل والتوقيتات المتداخلة.

### Python

انقذوا cite.py بجانبك captions.pyثم تشغيله من نفس الملف.

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

#### الاستشهاد المطبوع من الأسر الموفرة

```bash
python cite.py
```


### Bash

#### الاستشهاد المطبوع من الأسر الموفرة

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


- [إعداد موجز مع الإشارة إليه](https://flashdata.dev/ar/docs/guides/youtube-summary/reference.md)

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

### حافظ على سياق الأسر

استخدام نص الجزء كدليل على الاستشهاد؛ والرقم fullText مفيد للقراءة ولكنه لا يحدد مكان المرور. تحقق من الأجزاء المحيطة قبل الاقتباس خصوصاً للاختفاءات التلقائية الحجز languageCode و isAutoGenerated حتى يستطيع تطبيقك أو وكيلك تحديد مسار المصدر.


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

## إعادة استخدام المسار المنقذ

أديري نفس القيادة لإعادة البناء captions.json من الاستجابة الموفرة، بدون سؤال رئيسي أو جديد. ولا يغير تحرير أعلى المستويات من الرقم request.json الطلب المخزن بمقياس تعقّب 001.

### Python

#### إعادة الاستخدام محليا

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


### Bash

#### إعادة الاستخدام محليا

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



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

### اختر مسار آخر

أن يطلب الحصول على أغطية انجليزية مقدمة من المرفع، وأن يحل محل request.json بهذه النسخة وأن يستخدم جهاز تتبع 002. تغيير اللغة إلى الشفرة التي تنوي استرجاعها مثل (فيوريج) أو (زه هانز) "ميتاداتا" transcriptLanguages يُدرج رموز المرشحين، لا ما إذا كان لكل واحد مسار تلقائي أو مُحمّل.

السيناريو يتوقع سلسلة لغوية واحدة وتتميز صفائف اللغات بصيغة مختلفة للرد على المسارات والأخطاء التي تحدثها كل لغة؛ وتستخدم مرجع API لتدفق العمل هذا.

#### timestamped-captions/request.json

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

#### Python

##### مسار جديد: طلب آخر من شركة API

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


#### Bash

##### مسار جديد: طلب آخر من شركة API

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


- [بارامترات القدرات وشكلات الاستجابة](https://flashdata.dev/ar/docs/sources/youtube_captions/reference.md)

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

## إذا كانت الأسر مفقودة أو لا يمكن استخدامها

| ماذا حدث؟ | الإجراء المطلوب |
| --- | --- |
| المسار المختار غير متاح | تحقق من الفيديو واللغة واختيار السيارات. اختر المسار المتاح صراحة؛ ولن يؤدي تكرار الطلب نفسه إلى اختلالات. |
| segments: [] | ولا يمكن أن يتضمن المسار الحالي أي نص. النص يحفظ المسار الفارغ ويُبلغ عن الفجوة لا تُحوّلْه إلى a نصّ أو موجز. |
| منشأ الفيديو الخاطئ أو اللغة أو الاختباء | لا captions.json مكتوب. Compare the rescue request with result.json before using any text. |
| التوقيت غير المستقر أو الأجزاء المفقودة | Inspect result.json. يتوقّف النص بدلاً من تعيين المصابيح المخترعة أو إسقاط جزء سيء بصمت. |
| 401 / 403 / 402 | تحقق من المفتاح، إذن وتوازن youtube_captions، على التوالي، قبل محاولة جديدة. |
| 429 | اقرأ Retry-After في response-headers.txt وانتظر. النص لا يعيد النظر تلقائياً |
| وقت مستقطع، 5x، غير صحيح JSON أو ملف غير كامل | حافظوا على المحاولة وتحققوا History قبل أن تقدم مرة أخرى. إعادة استخدام ملفها لا ترسل أبداً استفساراً آخر |

### Python

احفظ inspect_captions.py بجانب captions.py، ثم شغّله.

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

#### Inspect locally

```bash
python inspect_captions.py
```


### Bash

#### Inspect locally

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


- [التاريخ](https://flashdata.dev/app/jobs)
- [الأخطاء ورموز الحالة](https://flashdata.dev/ar/docs/errors/reference.md)
