كيف تنشئ ترجمات SRT من فيديو عبر واجهة برمجية

الطلب

استدعاءان: ابدأ المهمة ثم استعلم عنها. وresult في مهمة srt المكتملة سلسلة نصية لا JSON. هذه النسخة تحتاج curl وjq فقط:

# 1. Start the job. "word_timestamps": false gives one cue per segment.
JOB=$(curl -s https://app.kolwrite.com/transcribe \
  -H "x-api-key: $KOLWRITE_API_KEY" -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/talk.mp3", "model": "oracle", "output_format": "srt", "word_timestamps": false}' \
  | jq -r .jobId)

# 2. Poll until it is done and save the result string as a .srt file.
while true; do
  REPLY=$(curl -s "https://app.kolwrite.com/transcribe/$JOB" -H "x-api-key: $KOLWRITE_API_KEY")
  STATUS=$(echo "$REPLY" | jq -r .status)
  if [ "$STATUS" = "COMPLETED" ]; then echo "$REPLY" | jq -r .result > talk.srt; break; fi
  if [ "$STATUS" = "FAILED" ]; then echo "$REPLY" | jq -r .error; break; fi
  sleep 5
done

يصلح إرسال ملف فيديو أيضًا لأن الواجهة تقرأ مسار الصوت منه. ويمر الملف المحلي أولًا عبر POST /upload (حتى 100 MiB)، أما للفيديو الطويل فاستخرج الصوت باستخدام ffmpeg. وتنجز الدالة المساعدة في دليل تحرير الفيديو الأمرين بلغة Python.

ما بداخل ملف SRT

عند ضبط "word_timestamps": false، يظهر لك سطر واحد لكل مقطع، وهذا هو الشكل المعتاد لملفات الترجمة:

1
00:00:01,000 --> 00:00:03,750
Hello everyone and welcome to the show.

2
00:00:05,000 --> 00:00:07,750
Today we talk about editing video from a transcript.

أما إذا تركت توقيت الكلمات مفعلًا (وهو الإعداد الافتراضي)، فستعيد الواجهة سطرًا مستقلًا لكل كلمة. يكرر كل سطر نص المقطع كاملًا ويضع الكلمة المنطوقة حينها داخل وسم <font> باللون الأصفر، ليظهر النص بأسلوب تظليل الكلمات مع الصوت بدل الترجمة العادية:

1
00:00:01,000 --> 00:00:01,350
<font color="yellow">Hello</font> everyone and welcome to the show.

2
00:00:01,400 --> 00:00:01,750
Hello <font color="yellow">everyone</font> and welcome to the show.

إذا أردت ترجمة عادية، مرّر "word_timestamps": false، أو جمّع الأسطر بنفسك من كلمات ملف JSON بالطريقة التالية.

تجميع أسطر مرتبة من توقيت الكلمات

اطلب الصيغة output_format: "json" وجمّع الكلمات في أسطر بنفسك، بحيث لا يتجاوز السطر 42 حرفًا و6 ثوانٍ، وابدأ سطرًا جديدًا بعد كل وقفة. يمنحك هذا تحكمًا في طول السطر، وهو أمر مهم عند دمج الترجمة في الفيديو.

srt_tools.py

# srt_tools.py — neat subtitle cues from word timings
def srt_time(seconds):
    ms = round(seconds * 1000)
    h, ms = divmod(ms, 3_600_000)
    m, ms = divmod(ms, 60_000)
    s, ms = divmod(ms, 1000)
    return f"{h:02}:{m:02}:{s:02},{ms:03}"


def cues_from_words(words, max_chars=42, max_seconds=6.0, max_gap=0.8):
    """Group timed words into subtitle cues: (start, end, text)."""
    cues, line = [], []
    for word in words:
        text = word["word"].strip()
        if not text:
            continue
        if line:
            length = sum(len(w["word"]) + 1 for w in line) + len(text)
            if (length > max_chars
                    or word["end"] - line[0]["start"] > max_seconds
                    or word["start"] - line[-1]["end"] > max_gap):
                cues.append(line)
                line = []
        line.append({"start": word["start"], "end": word["end"], "word": text})
    if line:
        cues.append(line)
    return [(c[0]["start"], c[-1]["end"], " ".join(w["word"] for w in c)) for c in cues]


def cues_from_result(result):
    """Cues for a whole JSON result; a segment without word times becomes one cue."""
    cues = []
    for segment in result["segments"]:
        if segment.get("words"):
            cues += cues_from_words(segment["words"])
        elif segment["text"].strip():
            cues.append((segment["start"], segment["end"], segment["text"].strip()))
    return cues


def write_srt(cues, path):
    with open(path, "w", encoding="utf-8") as out:
        for number, (start, end, text) in enumerate(cues, 1):
            out.write(f"{number}\n{srt_time(start)} --> {srt_time(end)}\n{text}\n\n")

تُخرج الدالة cues_from_result(result) قوائم ثلاثية على شكل (start, end, text) للنتيجة كاملة، وتعتمد تلقائيًا على توقيت المقطع إذا لم يُرجع النموذج توقيت الكلمات. بعد ذلك، تتولى write_srt(cues, "talk.srt") كتابة الملف.

ترجمة النص إلى لغة أخرى

مرّر المعامل translate_to مع رمز اللغة المطلوبة واستخدم أحد نماذج Oracle (نموذج oracle_mini هو الأقل تكلفة بين النماذج التي تدعم الترجمة). ستحصل على الأسطر مترجمة إلى اللغة الهدف. احرص على إبقاء word_timestamps على القيمة false ليمثل كل سطر مقطعًا كاملًا.

{
  "audio_url": "https://example.com/lecture-he.mp4",
  "model": "oracle_mini",
  "language": "he",
  "translate_to": "en",
  "output_format": "srt",
  "word_timestamps": false
}

إذا أردت ترجمة الفيديو نفسه إلى عدة لغات، أرسل مهمة مستقلة لكل لغة. تعامل مع الترجمة الآلية كمسودة أولى، وراجع الأسماء والأرقام والمصطلحات قبل نشرها.

التحويل إلى WebVTT وASS وصيغ أخرى

تُخرج الواجهة صيغ json أو txt أو srt فقط. إذا كنت تحتاج إلى ملف WebVTT لتشغيله داخل وسم <video> في HTML5، حوّل ملف SRT باستخدام ffmpeg:

ffmpeg -i video.srt video.vtt

تستطيع التحويل بين أغلب صيغ الترجمة عبر ffmpeg بالطريقة ذاتها، وكل ما عليك هو تغيير امتداد ملف الإخراج.

حرق الترجمة على الفيديو أو إرفاقها كمسار

محروقة على الصورة:

ffmpeg -i edited.mp4 -vf "subtitles=edited.srt" -c:a copy burned.mp4

كمسار ترجمة مدمج داخل ملف MP4 (يمكن للمشاهد إخفاؤه من المشغّل):

ffmpeg -i edited.mp4 -i edited.srt -c copy -c:s mov_text -metadata:s:s:0 language=eng soft.mp4

يقبل YouTube Studio وأغلب مشغّلات الفيديو وبرامج المونتاج ملفات .srt مباشرة دون تحويل.

الترجمة بالعربية والعبرية

• تُرجع الواجهة نصًا عاديًا بترميز Unicode. ويتكفل مشغّل الفيديو أو محرك الترجمة في ffmpeg بضبط اتجاه القراءة من اليمين إلى اليسار، وتظهر العربية والعبرية بشكل سليم طالما يدعم الخط المستخدم حروفهما.
• مرّر خطًا يدعم لغة النص، واختبر النتيجة على إطار واحد قبل معالجة الفيديو بالكامل. في تجاربنا، ظهرت العبرية دون مشاكل بخط Arial، لكن إحدى الكلمات العربية سقط منها حرف عند استخدام الخط نفسه، لذا ننصحك بتجربة خط مختلف للعربية.

ffmpeg -i video.mp4 -vf "subtitles=video.he.srt:force_style='FontName=Arial,FontSize=24'" -c:a copy burned.mp4

• إذا انتهى السطر بعلامة ترقيم أو كلمة بحروف لاتينية (مثل اسم علامة تجارية أو رقم)، فقد يختل ترتيب عرضه في المشغّلات التي لا تدعم النصوص ثنائية الاتجاه جيدًا. جرّب الملف على المشغّلات التي يعتمد عليها جمهورك.

التكلفة

تُحسب التكلفة بالثانية دون حد أدنى. راجع الأسعار هنا: /llms/pricing.md.

أسئلة وأجوبة