Entwicklung

Python-Clientbibliothek

Baue vollständige SubFT-Workflows mit HTTP-Client, Echtzeitereignissen und lokalen Hilfen.

  • HTTP-API
  • Echtzeit
  • Lokale Extras
Schnellstart
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()
Installation und Extras
pip install subft-client
pip install "subft-client[local]"
pip install "subft-client[realtime]"
pip install "subft-client[local,realtime]"

Workflow

Durchgängiger Projekt-Workflow

Erstelle einen Client mit expliziter Basis-URL und Token und gleiche lokale Medien mit Remote-Ergebnissen ab.

  1. Client erstellenNutze einen Context Manager oder schließe den Client ausdrücklich.
  2. Erstellen und synchronisierenProjekt erstellen, lokale Medien scannen, Änderungen prüfen und Synchronisierung anwenden.
  3. Operation planenErstelle einen Plan und schätze ihn optional vor kostenpflichtiger Arbeit.
  4. Sicher hochladenSende Bytes nur an das exakte Direct-Upload-Ziel des Dienstes.
  5. Fortschritt abgleichenKombiniere Echtzeitereignisse mit verbindlichen HTTP-Lesevorgängen bis zum Endzustand.
  6. Ergebnisse abrufenListe Ergebnisspuren und schreibe lokale Ausgaben mit den optionalen Hilfen.
Lebenszyklus von Verzeichnisprojekt und Operation
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,
    )

Referenz

SubftClient-Methodenreferenz

Jede öffentliche Methode ist nach Workflow-Bereich aufgelistet. Methodennamen und Signaturen sind stabile API-Bezeichner.

Lebenszyklus, Anfragen und Upload-Ziele

Client-Lebenszeit, untergeordnete Anfragen, URL-Auflösung und Direct-Upload-Transfer.

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

Wartung und Authentifizierung

Dienststatus, Sitzungen, Tokenstatus, Tokenerzeugung und Widerruf.

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

Projekte

Projekte auflisten, erstellen, importieren, aktualisieren, prüfen und archivieren.

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

Projektmedien

Projektmedien und Metadaten ihrer lokalen Artefakte verwalten.

  • 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()

Verzeichnis- und Stream-Synchronisierung

Verzeichnisse scannen und Sidecars, Streams und Sprachüberschreibungen abgleichen.

  • 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()

Pläne, Operationen, Uploads und Steuerung

Arbeit planen, Operationen erstellen, Quellen hochladen, Fortschritt melden und Ausführung steuern.

  • 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()

Untertitel-Stream-Caches

Untertitel-Stream-Caches prüfen, schreiben, normalisieren, importieren und bereitstellen.

  • 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()

Spuren, Cues und Exporte

Ergebnisspuren, Cues, Bearbeitungsdaten, Exportpläne und geladene Ausgaben verwalten.

  • 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-Fehlerhierarchie

Fange die spezifischste Unterklasse ab, wenn die Wiederherstellung abweicht, oder SubftError für alle clientseitigen Fehler.

  • SubftError
  • SubftApiError
  • SubftMaintenanceError
  • SubftTransportError
Alle Exporte des Hauptpakets
  • JsonArray
  • JsonObject
  • JsonValue
  • SubftApiError
  • SubftClient
  • SubftError
  • SubftMaintenanceError
  • SubftTransportError
  • __version__

Sicherheit bei Direct Uploads

Behandle Upload-Ziele als kurzlebige Berechtigungen. Übergib URL, Methode und Header unverändert an put_upload_target(); das SubFT-Token wird ausgelassen. Folge keinen Weiterleitungen und verwende abgelaufene Ziele nicht erneut.

Direct Upload ohne API-Anmeldedaten
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,
)

Echtzeitabgleich

Echtzeitereignisse dienen der schnellen Reaktion. Lies verbindliche Ressourcen nach Verbindungsabbrüchen, Sequenzlücken und Endereignissen erneut.

Öffentliche Echtzeit-Exporte
  • OperationEvent
  • RealtimeConnectionState
  • RealtimeDependencyError
  • RealtimeProtocolError
  • RealtimeSubscriptionError
  • SubftRealtimeError
  • watch_operation_events
Ereignisse lösen verbindliche Lesevorgänge aus
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

Installiere das Local-Extra für Medienscans, FFmpeg-Adapter, Projektbindungen, lokale Operationspläne und Ausgabeanwendung.

Öffentliche lokale Exporte
  • 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