# كيف تحصل على توقيت كل كلمة في تسجيل

> أرسل طلبًا إلى POST /transcribe مع ضبط output_format على json وword_timestamps على true (وكلاهما مفعل افتراضيًا). سيضم كل مقطع في النتيجة مصفوفة words تحتوي على {start, end, word} بالثواني. يشرح هذا الدليل شكل الاستجابة، والنماذج التي تدعم توقيت الكلمات، وكيف تستفيد منه عمليًا.

آخر تحديث: 2026-10-18 · HTML: https://console.kolwrite.com/ar/guides/word-timestamps-api

## الطلب

```json
{
  "audio_url": "https://example.com/interview.mp3",
  "model": "oracle",
  "language": "auto",
  "word_timestamps": true,
  "output_format": "json"
}
```

ابدأ المهمة عبر `POST /transcribe` ثم تابع حالتها عبر `GET /transcribe/{jobId}` حتى تصبح `COMPLETED`. احرص على تحديد المعامل `model` صراحةً، لأن إغفاله يجعل الواجهة تستخدم النموذج القديم `core`.

## الاستجابة

```json
{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 1.0,
        "end": 3.75,
        "text": "Hello everyone and welcome to the show.",
        "speaker": "Speaker 1",
        "words": [
          { "start": 1.0, "end": 1.35, "word": "Hello" },
          { "start": 1.4, "end": 1.75, "word": "everyone" }
        ]
      }
    ]
  }
}
```

- `segments[]`: تضم `start` و`end` بالثواني، وحقل `text`، وحقل `speaker` عند تفعيل تمييز المتحدثين، ومصفوفة `words[]`.
- `words[]`: تضم `start` و`end` و`word` بالثواني، مقرّبة إلى ثلاث خانات عشرية.
- قد تتساوى قيمتا `start` و`end` في بعض الكلمات، وقد لا تستغرق الكلمة القصيرة سوى أجزاء من الثانية. لذلك تجنب القسمة الحسابية على مدة الكلمة.
- إذا مررت `word_timestamps` بقيمة `false`، أو اخترت نموذجًا يعيد توقيت المقاطع فقط، فلن يظهر الحقل `words` وستقتصر النتيجة على `start` و`end` لكل مقطع.

## النماذج التي تدعم توقيت الكلمات

| النموذج | أوقات الكلمات |
| --- | --- |
| `base` و`oracle` و`oracle_pro` و`oracle_max` | نعم |
| `oracle_mini` | يعيد أوقات المقاطع في التفريغ العادي، ويعيد أوقات الكلمات عند تفعيل وضع المتحدثين (تمييز المتحدثين أو فصل القنوات) |
| `core` و`edge` (قديمان) | نعم |

صيغة النص العادي (`txt`) لا تتضمن أي توقيت. أما ملف SRT الذي تولّده الواجهة فيعتمد المنطق نفسه، راجع [دليل SRT](https://console.kolwrite.com/ar/guides/srt-subtitles-api).

## البحث عن موضع عبارة

سطّح مصفوفة الكلمات وابحث فيها لاستخراج النطاق الزمني المطلوب. بهذه الطريقة يستطيع الوكيل الإجابة عن سؤال مثل «أين تذكر الأسعار؟» بتوقيت دقيق، أو اقتطاع تلك الجملة في مقطع مستقل.

find.py

```python
# find.py — where is a phrase said? Returns (start, end) in seconds.
import re


def find_phrase(result, phrase):
    words = [w for segment in result["segments"] for w in segment.get("words", [])]
    clean = lambda text: re.sub(r"[^\w]", "", text.lower())
    target = [clean(p) for p in phrase.split()]
    tokens = [clean(w["word"]) for w in words]
    for i in range(len(tokens) - len(target) + 1):
        if tokens[i:i + len(target)] == target:
            return words[i]["start"], words[i + len(target) - 1]["end"]
    return None


# start, end = find_phrase(result, "welcome to the show")
# ffmpeg -ss <start> -to <end> -i talk.mp4 -c:v libx264 -c:a aac clip.mp4
```

اقتطاع مقطع حسب النطاق الزمني:

```bash
ffmpeg -ss 41.2 -to 47.8 -i talk.mp4 -c:v libx264 -c:a aac clip.mp4
```

## تقليص فترات الصمت وإنشاء قفزات قطعية

توقيت الكلمات يكشف لك الفجوات الزمنية بينها. احتفظ بالكلام المتصل واحذف الوقفات التي تتجاوز حدًا معينًا:

silences.py

```python
# silences.py — keep the speech, drop pauses longer than max_gap seconds
def speech_ranges(words, max_gap=0.7, pad=0.1):
    ranges = []
    for word in words:
        if ranges and word["start"] - ranges[-1][1] <= max_gap:
            ranges[-1][1] = word["end"]
        else:
            ranges.append([word["start"], word["end"]])
    return [[max(0.0, s - pad), e + pad] for s, e in ranges]

# Pass the ranges to cut() from cut.py to build the tightened video.
```

مرّر هذه النطاقات إلى الدالة `cut()` المشروحة في [دليل تحرير الفيديو](https://console.kolwrite.com/ar/guides/video-editing-with-ai).

## استخدامات أخرى للتوقيت

- تمييز الكلمات أثناء التشغيل على الويب: أبرز الكلمة التي يقع وقت المشغّل الحالي `currentTime` ضمن نطاقها.
- تفريغ تفاعلي قابل للنقر: اربط كل كلمة بالمعامل `?t=<start>` للقفز إليها مباشرة في المشغّل.
- تقسيم الفصول وأبرز اللحظات: يحدد النموذج اللغوي أرقام المقاطع المهمة، وتحوّلها شيفرتك إلى أوقات دقيقة.
- البحث داخل مكتبة صوتية: خزّن الكلمات مع أوقات بدايتها ليفتح المقطع عند الثانية المطلوبة مباشرة.
- المحاذاة الزمنية والمدونات اللغوية: حوّل أوقات الكلمات من JSON إلى صيغ الوسم التي تقبلها أدواتك.

## التكلفة

تفعيل توقيت الكلمات لا يغير التكلفة. يُحسب الاستهلاك بثواني الصوت الفعلية حسب سعر النموذج، بدءًا من 0.48 دولار للساعة على `base`، و1.44 دولار للساعة على `oracle`. تفاصيل الأسعار في [/llms/pricing.md](https://console.kolwrite.com/llms/pricing.md).

## أسئلة وأجوبة

### كيف أحصل على توقيت على مستوى الكلمة من واجهة تفريغ؟

أرسل الطلب مع `output_format: "json"` و`word_timestamps: true`. سيعود كل مقطع بمصفوفة `words[]` تضم `start` و`end` و`word` بالثواني.

### أي النماذج تدعم توقيت الكلمات؟

تدعمه النماذج `base` و`oracle` و`oracle_pro` و`oracle_max`. أما `oracle_mini` فيعيد أوقات المقاطع فقط إلا إذا فعّلت وضع المتحدثين. المخرجات النصية العادية لا تضم أي توقيت.

### ما دقة أوقات الكلمات؟

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

### هل أحصل على التوقيت لملف فيديو؟

نعم، تقرأ الواجهة المسار الصوتي من ملف الفيديو مباشرة. وإذا تجاوز حجم الملف 100 MiB، استخرج الصوت أولًا باستخدام ffmpeg.

### هل التوقيت بالثواني أم بالميلي ثانية؟

بالثواني، وتُكتب كأرقام عشرية حتى ثلاث خانات بعد الفاصلة (مثل `41.236`).

## صفحات ذات صلة

- [تحرير الفيديو مع وكلاء الذكاء الاصطناعي](https://console.kolwrite.com/ar/guides/video-editing-with-ai)
- [واجهة ترجمات SRT](https://console.kolwrite.com/ar/guides/srt-subtitles-api)
- [ترجمات البودكاست ويوتيوب](https://console.kolwrite.com/ar/guides/podcast-youtube-captions)
- [البحث اللغوي واللسانيات](https://console.kolwrite.com/ar/use-cases/researchers)
- [المطورون وفرق المنتجات](https://console.kolwrite.com/ar/use-cases/developers)
- [توثيق الـ API](https://console.kolwrite.com/ar/public_api_docs)

---
احصل على مفتاح API: https://console.kolwrite.com/auth?lang=ar · توثيق الـ API: https://console.kolwrite.com/ar/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt