المطورون

مكتبة عميل Python

ركّب سير عمل SubFT كاملاً باستخدام عميل HTTP وأحداث الوقت الفعلي والأدوات المحلية.

  • واجهة HTTP
  • الوقت الفعلي
  • إضافات محلية
بدء سريع
import os
from subft_client import SubftClient

with SubftClient(
    "https://api.subft.com",
    token=os.environ["SUBFT_API_TOKEN"],
    timeout=30.0,
) as client:
    projects = client.list_projects()
التثبيت والإضافات
pip install subft-client
pip install "subft-client[local]"
pip install "subft-client[realtime]"
pip install "subft-client[local,realtime]"

سير العمل

سير عمل المشروع الكامل

أنشئ عميلاً بعنوان أساسي ورمز صريحين ثم وفّق الوسائط المحلية والنتائج البعيدة.

  1. إنشاء العميلاستخدم مدير سياق أو أغلق العميل صراحة.
  2. الإنشاء والمزامنةأنشئ مشروعاً وافحص الوسائط المحلية وعاين التغييرات وطبّق المزامنة.
  3. تخطيط العمليةأنشئ خطة وقدّرها اختيارياً قبل بدء العمل المدفوع.
  4. الرفع الآمنأرسل البيانات فقط إلى هدف الرفع المباشر الدقيق الذي تعيده الخدمة.
  5. موافقة التقدمادمج أحداث الوقت الفعلي مع قراءات HTTP الموثوقة حتى الحالة النهائية.
  6. جلب النتائجاسرد مسارات النتائج واكتب المخرجات المحلية باستخدام الأدوات الاختيارية.
دورة حياة مشروع المجلد والعملية
import os
from subft_client import SubftClient

files = [...]    # DirectorySnapshotFile.to_api_dict() values
metrics = [...]  # Prepared source metrics accepted by the plan

with SubftClient(
    "https://api.subft.com",
    token=os.environ["SUBFT_API_TOKEN"],
) as client:
    project = client.create_project(
        name="Documentary",
        mode="directory",
        root_label="documentary",
    )
    project_id = project["id"]

    preview = client.preview_project_directory_sync(project_id, files)
    # Review preview before confirming non-safe changes.
    synced = client.apply_project_directory_sync(
        project_id,
        files=files,
        confirm_reviewed=True,
    )
    media_ids = [item["id"] for item in synced["media"]]

    selection = {
        "media_ids": media_ids,
        "target_language": "de",
    }
    plan = client.create_project_operation_plan(project_id, **selection)
    estimate = client.estimate_project_operation_plan(
        project_id,
        **selection,
        metrics=metrics,
    )
    commit = client.create_project_operation(
        project_id,
        **selection,
        metrics=metrics,
    )
    operation_id = commit["operation"]["operation_id"]

    state = client.get_operation(operation_id)
    tracks = client.list_project_operation_result_tracks(
        project_id,
        operation_id,
    )

المرجع

مرجع دوال SubftClient

تُسرد كل دالة عامة حسب مجال سير العمل. أسماء الدوال وتوقيعاتها معرفات واجهة مستقرة.

دورة الحياة والطلبات وأهداف الرفع

عمر العميل والطلبات منخفضة المستوى وحل الروابط ونقل الرفع المباشر.

  • close()
  • request()
  • request_json()
  • resolve_url()
  • put_upload_target()

الصيانة والمصادقة

صحة الخدمة والجلسات وحالة الرمز وإنشاؤه وإلغاؤه.

  • get_maintenance_status()
  • get_session()
  • verify_auth()
  • get_api_token_status()
  • generate_api_token()
  • revoke_api_token()

المشاريع

سرد المشاريع وإنشاؤها واستيرادها وتحديثها وفحصها وأرشفتها.

  • list_projects()
  • create_project()
  • import_project()
  • get_project()
  • update_project()
  • archive_project()

وسائط المشروع

إدارة سجلات وسائط المشروع وبيانات ملفاتها المحلية.

  • list_project_media()
  • add_project_media_bulk()
  • add_project_media()
  • get_project_media()
  • remove_project_media()
  • mark_project_media_missing()
  • replace_project_media()
  • restore_project_media()
  • update_project_media_artifact()
  • update_project_media_thumbnail()
  • update_project_media_waveform()

مزامنة المجلدات والتدفقات

فحص المجلدات وموافقة الملفات الجانبية والتدفقات وتجاوزات اللغة.

  • scan_project_directory()
  • preview_project_directory_sync()
  • apply_project_directory_sync()
  • update_project_media_stream_language_override()
  • preview_project_sidecars()
  • attach_project_media_sidecars()
  • mark_project_media_stream_missing()
  • replace_project_media_stream()
  • remove_project_media_stream()

الخطط والعمليات والرفع والتحكم

تخطيط العمل وإنشاء العمليات ورفع المصادر والإبلاغ عن التقدم والتحكم بالتنفيذ.

  • create_project_operation_plan()
  • estimate_project_operation_plan()
  • create_project_operation()
  • list_project_operations()
  • get_project_operation()
  • list_project_operation_result_tracks()
  • get_operation()
  • list_operations()
  • create_upload_target()
  • complete_upload()
  • report_content_progress()
  • use_stream_cache()
  • pause_operation()
  • resume_operation()
  • abort_operation()

ذاكرة تخزين تدفقات الترجمة

فحص ذاكرة تدفقات الترجمة وكتابتها وتطبيعها واستيرادها وتجهيزها.

  • list_project_media_subtitle_stream_caches()
  • get_project_media_subtitle_stream_cache()
  • write_project_media_subtitle_stream_cache()
  • normalize_project_media_subtitle_stream()
  • import_project_media_subtitle_stream()
  • stage_project_media_subtitle_stream()

المسارات والمقاطع والتصدير

إدارة مسارات النتائج والمقاطع وبيانات التحرير وخطط التصدير والمخرجات المنزلة.

  • list_project_media_subtitle_tracks()
  • create_project_media_subtitle_track()
  • get_project_media_subtitle_track()
  • duplicate_project_media_subtitle_track()
  • delete_project_media_subtitle_track()
  • export_project_media_subtitle_track()
  • stage_project_media_subtitle_track()
  • commit_project_media_subtitle_track()
  • mark_project_media_subtitle_track_applied()
  • discard_project_media_subtitle_track()

تسلسل أخطاء HTTP

التقط الفئة الفرعية الأكثر تحديداً عند اختلاف الاسترداد، أو SubftError لكل أخطاء العميل.

  • SubftError
  • SubftApiError
  • SubftMaintenanceError
  • SubftTransportError
كل صادرات الحزمة العليا
  • JsonArray
  • JsonObject
  • JsonValue
  • SubftApiError
  • SubftClient
  • SubftError
  • SubftMaintenanceError
  • SubftTransportError
  • __version__

أمان الرفع المباشر

عامل أهداف الرفع كصلاحيات قصيرة العمر. مرّر الرابط والطريقة والترويسات المعادة دون تغيير إلى put_upload_target()؛ فهي لا ترسل رمز SubFT. لا تتبع إعادة التوجيه ولا تعد استخدام الأهداف المنتهية.

رفع مباشر دون بيانات اعتماد API
target = client.create_upload_target(
    operation_id,
    media_id,
    content_id=content_id,
    content_hash=sha256,
    filename=source.name,
)
client.put_upload_target(
    target["upload_url"],
    method=target["method"],
    headers=target["headers"],
    content=source.read_bytes(),
)
client.complete_upload(
    operation_id,
    media_id,
    content_id=content_id,
    upload_id=target["upload_id"],
    content_hash=sha256,
)

الموافقة في الوقت الفعلي

أحداث الوقت الفعلي إشارات للاستجابة السريعة. أعد قراءة الموارد الموثوقة بعد إعادة الاتصال وفجوات التسلسل والأحداث النهائية.

صادرات الوقت الفعلي العامة
  • OperationEvent
  • RealtimeConnectionState
  • RealtimeDependencyError
  • RealtimeProtocolError
  • RealtimeSubscriptionError
  • SubftRealtimeError
  • watch_operation_events
استخدام الأحداث لتشغيل قراءات موثوقة
from subft_client.realtime import watch_operation_events

async def reconcile(client, operation_id, token):
    state = client.get_operation(operation_id)
    yield state

    async for event in watch_operation_events(
        client.base_url,
        operation_id,
        token=token,
    ):
        # Events trigger reads; HTTP remains authoritative.
        state = client.get_operation(operation_id)
        yield state

subft_client.local

ثبّت الإضافة المحلية لفحص الوسائط ومحولات FFmpeg وروابط المشاريع وخطط العمليات المحلية وتطبيق المخرجات.

الصادرات المحلية العامة
  • AUDIO_EXTENSIONS
  • DEFAULT_HASH_CHUNK_SIZE
  • DirectorySnapshotFile
  • DirectorySnapshotResult
  • ExtractedFile
  • FfmpegTools
  • FfmpegUnavailableError
  • FileFingerprint
  • InventoryResult
  • LANGUAGE_SAMPLE_BYTES
  • LocalFailure
  • LocalFile
  • LocalFileChangedError
  • LocalHashError
  • LocalPathError
  • LocalProgress
  • LocalScanError
  • MediaInventoryItem
  • MediaEmbeddingError
  • MediaExtractionError
  • MediaProbe
  • MediaProbeError
  • MuxedMedia
  • ProbeStream
  • SUBTITLE_EXTENSIONS
  • ScanResult
  • SubftLocalError
  • SubtitleMuxInput
  • VIDEO_EXTENSIONS
  • VOBSUB_EXTENSIONS
  • build_directory_snapshot
  • build_inventory
  • check_ffmpeg_tools
  • embed_subtitle_tracks
  • extract_audio_stream
  • extract_subtitle_stream
  • fingerprint_media_file
  • hash_file_sha256
  • hash_text_subtitle
  • inspect_media
  • probe_media
  • read_subtitle_language_sample
  • require_ffmpeg_tools
  • scan_directory
  • vobsub_pair_hash