Python-API-Referenz

Signaturen, Parameter, Rückgabeverträge und öffentliche Exporte von subft-client.

Parameter, Rückgaben und Fehler

Dies ist ein schlanker synchroner HTTP-Client. Er fragt nicht nach, scannt nicht automatisch und orchestriert keine bezahlte Arbeit. Beginne mit dem vollständigen Beispiel. API-Methoden benötigen Konto/Token und Zugriff auf das Projekt. Planung und Schätzung berechnen nichts; der Operationsstart schon. Tokenerzeugung und -widerruf benötigen das angemeldete Konto und ersetzen oder widerrufen dessen einziges aktives Token.

positional-only, positional-or-keyword, keyword-only und variadische Arten beschreiben die Python-Aufrufsyntax. Ein Strich bei Standard bedeutet keinen Standardwert; erforderliche Argumente müssen übergeben werden. _UNSET lässt ein Feld weg, während None ein nullable Projektfeld ausdrücklich leeren kann.

JsonValue ist Any, kein validiertes Antwortmodell. HTTP-Helfer geben dekodiertes JSON oder bei leerer Antwort None zurück; dokumentierte Felder stehen in den Antwortschemata unten. request und put_upload_target liefern httpx.Response, close liefert None und resolve_url eine URL-Zeichenfolge.

Fange SubftMaintenanceError vor SubftApiError ab; prüfe status_code, payload, response, mode und maintenance_until. SubftTransportError behält request_error. SubftError umfasst Clientfehler; Argumentprüfung kann auch ValueError auslösen. Bei 409 neu lesen oder planen, statt alte Schranken erneut zu senden. Technische Meldungen gehören in interne Protokolle; öffentliche Oberflächen übersetzen Codes. Nach unklarem Transportfehler einen kostenpflichtigen Start nicht blind wiederholen: zuerst angenommene Operation abgleichen.

HTTP-Fehler verwenden {"detail":{"code":"…","params":{…}}}. Lies SubftApiError.code und SubftApiError.params; rohe Servertexte dienen nur der Diagnose. Guthabenbeträge, Wartungsdaten und Untertitel-Zeilennummern stehen in den Parametern. Ein unlesbarer Untertitel kann zum Beispiel {"detail":{"code":"invalid_subtitles","params":{"line":2}}} zurückgeben. Öffentliche Oberflächen benötigen für unbekannte Codes eine übersetzte allgemeine Fehlermeldung.

SubftClient

Einen Client erstellen und per Kontextmanager schließen. Extras werden ausdrücklich importiert; das Basispaket lädt weder FFmpeg noch WebSocket-Abhängigkeiten.

Python

SubftClient(
    base_url: str,
    *,
    token: str | None = None,
    timeout: float | httpx.Timeout = 30.0,
    headers: Mapping[str, str] | None = None,
    cookies: Mapping[str, str] | None = None,
    transport: httpx.BaseTransport | None = None
) -> None

Parameter	Typ	Übergabe	Standard	Bedeutung
`base_url`	`str`	`positional-or-keyword`	—	Gateway-URL für API, Anmeldung und Echtzeitrouten; der abschließende Schrägstrich wird normalisiert.
`token`	`str \| None`	`keyword-only`	`None`	API-Token aus dem Entwicklerzugang. In einer geschützten Umgebungsvariable halten.
`timeout`	`float \| httpx.Timeout`	`keyword-only`	`30.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.
`headers`	`Mapping[str, str] \| None`	`keyword-only`	`None`	HTTP-Header. Upload-Header unverändert übernehmen; Anfrage-Header überschreiben Konstruktor-Header.
`cookies`	`Mapping[str, str] \| None`	`keyword-only`	`None`	Optionale HTTP-Cookies für diese Client-Sitzung.
`transport`	`httpx.BaseTransport \| None`	`keyword-only`	`None`	Optionaler HTTPX-Transport; in Tests MockTransport statt eines echten Gateways verwenden.

Client-Methoden

Jede öffentliche Methode steht unten genau einmal. Rückgaben und gemeinsame Ausnahmen folgen dem Vertrag oben; Endpunktkonflikte behalten Serverstatus und Antwortdaten.

`abandon_content_preparation`

Eine noch bearbeitbare Quellvorbereitung aufgeben; andere Quellen bleiben erhalten.

Python

abandon_content_preparation(
    operation_id: str, media_id: str, content_id: str
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`content_id`	`str`	`positional-or-keyword`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.

`abort_operation`

Angenommene Serverarbeit mit erlaubter Aktion abbrechen; das unterscheidet sich vom Beenden der Beobachtung.

Python

abort_operation(operation_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.

`add_project_media`

Einen lokal geprüften Inventareintrag mit physischen Quellen registrieren.

Python

add_project_media(
    project_id: str, media: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media`	`Mapping[str, Any]`	`positional-or-keyword`	—	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.

`add_project_media_bulk`

Einen vollständigen Stapel geprüfter Medieneinträge registrieren.

Python

add_project_media_bulk(
    project_id: str, media: Iterable[Mapping[str, Any]]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media`	`Iterable[Mapping[str, Any]]`	`positional-or-keyword`	—	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.

`apply_project_directory_sync`

Geprüften Verzeichnisstand mit aktuellen Schranken anwenden; bei veraltetem Stand erneut Vorschau erstellen.

Python

apply_project_directory_sync(
    project_id: str,
    *,
    files: Iterable[Mapping[str, Any]],
    media: Iterable[Mapping[str, Any]] | None = None,
    confirmed_moves: Iterable[Mapping[str, Any]] | None = None,
    confirm_reviewed: bool = False,
    expected_assets: Mapping[str, Any] | None = None,
    complete: bool = True
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`files`	`Iterable[Mapping[str, Any]]`	`keyword-only`	—	Vollständiger Verzeichnisstand, Dateiliste oder Nachweise dieses Endpunkts; aus lokalen Dateien erstellen.
`media`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.
`confirmed_moves`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Geprüfte Zuordnungen alter und neuer Medienpfade aus der Verzeichnisvorschau.
`confirm_reviewed`	`bool`	`keyword-only`	`False`	Ausdrückliche Zustimmung zu geprüften Verzeichnisänderungen; der Client erteilt keine automatische Zustimmung.
`expected_assets`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	Aktuelle Beobachtungs-, Generations- oder Speicherschranken aus Lese- oder Prüfantworten; veraltete Schranken erfordern neues Lesen.
`complete`	`bool`	`keyword-only`	`True`	Ob der Stand vollständig ist; einen teilweise fehlgeschlagenen Scan nicht als vollständig markieren.

`archive_project`

Ein abgeschlossenes Projekt schreibgeschützt archivieren. Wiederholte Aufrufe behalten das Archivierungsdatum bei.

Python

archive_project(project_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.

`restore_project`

Ein archiviertes Projekt wiederherstellen, um es erneut zu bearbeiten. Bei einem aktiven Projekt ändert sich nichts.

Python

restore_project(project_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.

`delete_project`

Ein archiviertes Projekt mit Arbeitsbereich, Ergebnissen und eingereichten Eingaben endgültig löschen. Auftrags- und Credit-Buchungen bleiben erhalten. Der Bestätigungsname muss nach Entfernen äußerer Leerzeichen einschließlich Groß- und Kleinschreibung genau übereinstimmen.

Python

delete_project(project_id: str, confirmation_name: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`confirmation_name`	`str`	`positional-or-keyword`	—	Exakter Projektname ohne äußere Leerzeichen; Groß- und Kleinschreibung beachten.

`attach_project_media_sidecars`

Geprüfte Untertitel-Begleitdateien anhand des Prüfstands einem Medium zuordnen.

Python

attach_project_media_sidecars(
    project_id: str,
    media_id: str,
    sidecars: Iterable[Mapping[str, Any]],
    *,
    expected_assets: Iterable[Mapping[str, Any]] = ()
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`sidecars`	`Iterable[Mapping[str, Any]]`	`positional-or-keyword`	—	Beobachtete Untertitel-Begleitdateien mit Paarungs- und Klassifikationsdaten.
`expected_assets`	`Iterable[Mapping[str, Any]]`	`keyword-only`	`()`	Aktuelle Beobachtungs-, Generations- oder Speicherschranken aus Lese- oder Prüfantworten; veraltete Schranken erfordern neues Lesen.

`begin_media_asset_checks`

Aktuellen Asset-Prüfstand vor dem Abgleich physischer Beobachtungen lesen.

Python

begin_media_asset_checks(
    project_id: str, media_id: str, *, scope: Mapping[str, Any] | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`scope`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	Endpunktspezifischer Assettyp, Prüfumfang, Bereitschafts- oder Platzierungswert gemäß dessen Vertrag.

`begin_project_directory_checks`

Asset-Prüfstände für einen vollständigen Verzeichnis-Vorschau- und Anwendungslauf lesen.

Python

begin_project_directory_checks(project_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.

`clone_media_asset`

Bearbeitbare Kopie oder Duplikat mit aktuellen Snapshot-Schranken erstellen.

Python

clone_media_asset(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`close`

HTTP-Verbindungspool schließen; der Kontextmanager erledigt dies automatisch.

Python

close() -> None

`compare_media_asset_exports`

Ausgewählte Exportkandidaten ohne Extraktion oder lokale Dateiausgabe vergleichen.

Python

compare_media_asset_exports(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`complete_media_asset_checks`

Abgesicherte physische Prüfungen abschließen und neue Quellen abgleichen.

Python

complete_media_asset_checks(
    project_id: str, media_id: str, payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`complete_upload`

Direkten Upload für das aktuelle Quellelement, den Upload und Vorbereitungsversuch abschließen.

Python

complete_upload(
    operation_id: str,
    media_id: str,
    *,
    content_id: str,
    attempt_id: str,
    upload_id: str,
    content_hash: str | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`content_id`	`str`	`keyword-only`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.
`attempt_id`	`str`	`keyword-only`	—	Neue UUID, vom Aufrufer gewählt und durch die Vorbereitung bestätigt; für alle Anfragen dieses Versuchs verwenden.
`upload_id`	`str`	`keyword-only`	—	Upload-ID aus der aktuellen Zielantwort, zusammen mit dem aktuellen Versuch.
`content_hash`	`str \| None`	`keyword-only`	`None`	Hash der vorbereiteten Bytes oder dokumentierter Paar-Hash, nicht der Fingerabdruck des ursprünglichen Mediums.

`create_blank_media_asset`

Leeres bearbeitbares Untertitel-Asset mit abgesicherter Anfrage erstellen.

Python

create_blank_media_asset(
    project_id: str, media_id: str, payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`create_project`

Leeres Datei- oder Verzeichnisprojekt erstellen; lokales Inventar wird getrennt übermittelt.

Python

create_project(
    *, name: str, mode: str, root_label: str | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`name`	`str`	`keyword-only`	—	Anzeigename des Projekts; update_project kann nullable Werte mit None leeren.
`mode`	`str`	`keyword-only`	—	Projektmodus: file oder directory.
`root_label`	`str \| None`	`keyword-only`	`None`	Lesbare Bezeichnung des Wurzelpfads, kein für den Server erreichbarer lokaler Dateipfad.

`create_project_operation`

Geschätzte, abgesicherte Quellauswahl verbindlich starten und akzeptierte Schätzung berechnen.

Python

create_project_operation(
    project_id: str,
    *,
    media_ids: Iterable[str],
    target_language: str,
    content_overrides: Iterable[Mapping[str, Any]] | None = None,
    metrics: Iterable[Mapping[str, Any]] | None = None,
    source_selections: Iterable[Mapping[str, Any]]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_ids`	`Iterable[str]`	`keyword-only`	—	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.
`target_language`	`str`	`keyword-only`	—	Zielsprachcode für erzeugte oder übersetzte Untertitel.
`content_overrides`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Überschreibungen nach stabilem source_ref: Quelle aktivieren oder Quellsprache ausdrücklich ändern.
`metrics`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Nur vom aktuellen Plan angeforderte Quellmetriken, lokal ermittelt. Audiodauer steht bereits im analysierten Inventar.
`source_selections`	`Iterable[Mapping[str, Any]]`	`keyword-only`	—	Abgesicherte Auswahl aus dem geschätzten Plan mit kanonischer source_language; Snapshots und Beobachtungen erhalten.

`create_project_operation_plan`

Quell- und Stufenplan ohne Berechnung oder Upload anfordern.

Python

create_project_operation_plan(
    project_id: str,
    *,
    media_ids: Iterable[str],
    target_language: str,
    content_overrides: Iterable[Mapping[str, Any]] | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_ids`	`Iterable[str]`	`keyword-only`	—	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.
`target_language`	`str`	`keyword-only`	—	Zielsprachcode für erzeugte oder übersetzte Untertitel.
`content_overrides`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Überschreibungen nach stabilem source_ref: Quelle aktivieren oder Quellsprache ausdrücklich ändern.

`create_upload_target`

Direktes Upload-Ziel nach Beginn von Hashing oder Upload anfordern oder erneuern.

Python

create_upload_target(
    operation_id: str,
    media_id: str,
    *,
    content_id: str,
    attempt_id: str,
    content_hash: str,
    filename: str | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`content_id`	`str`	`keyword-only`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.
`attempt_id`	`str`	`keyword-only`	—	Neue UUID, vom Aufrufer gewählt und durch die Vorbereitung bestätigt; für alle Anfragen dieses Versuchs verwenden.
`content_hash`	`str`	`keyword-only`	—	Hash der vorbereiteten Bytes oder dokumentierter Paar-Hash, nicht der Fingerabdruck des ursprünglichen Mediums.
`filename`	`str \| None`	`keyword-only`	`None`	Name der vorbereiteten Datei mit tatsächlicher Erweiterung zur Wahl des Speicherformats.

`estimate_project_operation_plan`

Aktuellen Plan mit tatsächlichen angeforderten Metriken schätzen; can_commit vor Zustimmung prüfen.

Python

estimate_project_operation_plan(
    project_id: str,
    *,
    media_ids: Iterable[str],
    target_language: str,
    content_overrides: Iterable[Mapping[str, Any]] | None = None,
    metrics: Iterable[Mapping[str, Any]] | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_ids`	`Iterable[str]`	`keyword-only`	—	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.
`target_language`	`str`	`keyword-only`	—	Zielsprachcode für erzeugte oder übersetzte Untertitel.
`content_overrides`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Überschreibungen nach stabilem source_ref: Quelle aktivieren oder Quellsprache ausdrücklich ändern.
`metrics`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Nur vom aktuellen Plan angeforderte Quellmetriken, lokal ermittelt. Audiodauer steht bereits im analysierten Inventar.

`export_media_asset`

Untertitelexport eines gespeicherten Assets mit aktuellen Snapshot-, Versions- und Metadatenschranken erfassen.

Python

export_media_asset(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`export_project_operation_artifact`

Bestimmte erfolgreiche unveränderliche Stufe exportieren; Download erzeugt kein bearbeitbares oder physisches Asset.

Python

export_project_operation_artifact(
    project_id: str,
    operation_id: str,
    artifact_id: str,
    *,
    output_target: str | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`artifact_id`	`str`	`positional-or-keyword`	—	ID einer unveränderlichen erfolgreichen Operationsstufe aus der Ergebnisliste.
`output_target`	`str \| None`	`keyword-only`	`None`	external_srt, external_vtt, external_ass oder embedded; None nutzt den Endpunkt- oder Kontostandard.

`export_project_operation_result`

Letzte erfolgreiche Stufe eines Quellelements der Operation exportieren.

Python

export_project_operation_result(
    project_id: str,
    operation_id: str,
    content_id: str,
    *,
    output_target: str | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`content_id`	`str`	`positional-or-keyword`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.
`output_target`	`str \| None`	`keyword-only`	`None`	external_srt, external_vtt, external_ass oder embedded; None nutzt den Endpunkt- oder Kontostandard.

`export_project_operation_result_names`

Endgültige Dateinamen der ausgewählten Ergebnisse, die zusammen in ein ZIP oder Verzeichnis geschrieben werden. Namen, die kollidieren würden, erhalten die Asset-Nummer der Quelle oder eine fortlaufende Nummer (clip.en.3.srt).

Python

export_project_operation_result_names(
    project_id: str,
    operation_id: str,
    artifact_ids: list[str],
    *,
    output_target: str
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`artifact_ids`	`list[str]`	`positional-or-keyword`	—	IDs der unveränderlichen erfolgreichen Operationsstufen, die zusammen geschrieben werden, aus der Ergebnisliste.
`output_target`	`str`	`keyword-only`	—	external_srt, external_vtt oder external_ass; eingebettete Ergebnisse haben keinen eigenen Dateinamen.

`generate_api_token`

Einzelnes aktives API-Token erzeugen und vorheriges ersetzen; Aufrufer verwaltet Zustimmung und Geheimnis.

Python

generate_api_token() -> JsonValue

`get_api_token_status`

Tokenstatus lesen, ohne ein vorhandenes Geheimnis wiederherzustellen.

Python

get_api_token_status() -> JsonValue

`get_asset_document`

Konsistentes gespeichertes Untertiteldokument mit aktueller Version lesen.

Python

get_asset_document(
    project_id: str, media_id: str, asset_id: str
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.

`get_maintenance_status`

Gateway-Wartungsstatus ohne Anmeldung lesen.

Python

get_maintenance_status() -> JsonValue

`get_media_asset`

Ein aktuelles Asset mit Bindungs- und Snapshot-Daten lesen.

Python

get_media_asset(
    project_id: str, media_id: str, asset_id: str
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.

`get_operation`

Kanonischen globalen Operationsstand lesen; nach Ereignissen und Wiederverbindungen abgleichen.

Python

get_operation(operation_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.

`get_project`

Projekt mit aktueller Inventarübersicht lesen.

Python

get_project(project_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.

`get_project_media`

Einen aktuellen Projektmedieneintrag lesen.

Python

get_project_media(project_id: str, media_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.

`get_project_operation`

Operation über die Route ihres Projekts lesen.

Python

get_project_operation(project_id: str, operation_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.

`get_session`

Ressource der angemeldeten Sitzung lesen.

Python

get_session() -> JsonValue

`get_workflow_preferences`

Workflow- und Exportstandards des Kontos lesen; ausdrückliche Auswahl kann sie überschreiben.

Python

get_workflow_preferences() -> JsonValue

`hide_media_asset`

Asset mit aktuellen Schranken ausblenden und Herkunft erhalten.

Python

hide_media_asset(
    project_id: str,
    media_id: str,
    asset_id: str,
    *,
    expected_autosave_version: int | None = None,
    guards: Mapping[str, Any] | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.
`expected_autosave_version`	`int \| None`	`keyword-only`	`None`	Aktuelle Beobachtungs-, Generations- oder Speicherschranken aus Lese- oder Prüfantworten; veraltete Schranken erfordern neues Lesen.
`guards`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	Aktuelle Beobachtungs-, Generations- oder Speicherschranken aus Lese- oder Prüfantworten; veraltete Schranken erfordern neues Lesen.

`import_project`

Projekt aus vollständig übermittelter Datei- und Inventarkonfiguration erstellen.

Python

import_project(
    *,
    name: str,
    mode: str,
    root_label: str | None = None,
    media: Iterable[Mapping[str, Any]] | None = None,
    file_evidence: Iterable[Mapping[str, Any]] | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`name`	`str`	`keyword-only`	—	Anzeigename des Projekts; update_project kann nullable Werte mit None leeren.
`mode`	`str`	`keyword-only`	—	Projektmodus: file oder directory.
`root_label`	`str \| None`	`keyword-only`	`None`	Lesbare Bezeichnung des Wurzelpfads, kein für den Server erreichbarer lokaler Dateipfad.
`media`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.
`file_evidence`	`Iterable[Mapping[str, Any]] \| None`	`keyword-only`	`None`	Vollständiger Verzeichnisstand, Dateiliste oder Nachweise dieses Endpunkts; aus lokalen Dateien erstellen.

`list_media_assets`

Gespeicherte Assets eines Projektmediums auflisten.

Python

list_media_assets(
    project_id: str,
    media_id: str,
    *,
    limit: int = 50,
    offset: int = 0,
    content_type: str | None = None,
    kind: str | None = None,
    search: str | None = None,
    language: str | None = None,
    forced: bool | None = None,
    sdh: bool | None = None,
    commentary: bool | None = None,
    classification: str | None = None,
    readiness: str | None = None,
    placement: str | None = None,
    sort: str = 'created_at',
    direction: str = 'asc'
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`limit`	`int`	`keyword-only`	`50`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`offset`	`int`	`keyword-only`	`0`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`content_type`	`str \| None`	`keyword-only`	`None`	MIME-Typ der vorbereiteten Daten; ein vorhandener Upload-Header hat Vorrang.
`kind`	`str \| None`	`keyword-only`	`None`	Endpunktspezifischer Assettyp, Prüfumfang, Bereitschafts- oder Platzierungswert gemäß dessen Vertrag.
`search`	`str \| None`	`keyword-only`	`None`	Optionaler Suchtext für die angeforderte Projekt- oder Medienliste.
`language`	`str \| None`	`keyword-only`	`None`	Untertitelsprache oder Klassifikation normal/Forced/SDH/Kommentar; technische Sprachcodes bleiben unverändert.
`forced`	`bool \| None`	`keyword-only`	`None`	Untertitelsprache oder Klassifikation normal/Forced/SDH/Kommentar; technische Sprachcodes bleiben unverändert.
`sdh`	`bool \| None`	`keyword-only`	`None`	Untertitelsprache oder Klassifikation normal/Forced/SDH/Kommentar; technische Sprachcodes bleiben unverändert.
`commentary`	`bool \| None`	`keyword-only`	`None`	Untertitelsprache oder Klassifikation normal/Forced/SDH/Kommentar; technische Sprachcodes bleiben unverändert.
`classification`	`str \| None`	`keyword-only`	`None`	Untertitelsprache oder Klassifikation normal/Forced/SDH/Kommentar; technische Sprachcodes bleiben unverändert.
`readiness`	`str \| None`	`keyword-only`	`None`	Endpunktspezifischer Assettyp, Prüfumfang, Bereitschafts- oder Platzierungswert gemäß dessen Vertrag.
`placement`	`str \| None`	`keyword-only`	`None`	Endpunktspezifischer Assettyp, Prüfumfang, Bereitschafts- oder Platzierungswert gemäß dessen Vertrag.
`sort`	`str`	`keyword-only`	`'created_at'`	Vom Listenendpunkt unterstütztes Sortierfeld oder Sortierrichtung.
`direction`	`str`	`keyword-only`	`'asc'`	Vom Listenendpunkt unterstütztes Sortierfeld oder Sortierrichtung.

`list_operations`

Globale Operationen mit ausdrücklicher Seiteneinteilung auflisten.

Python

list_operations(*, limit: int = 50, offset: int = 0) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`limit`	`int`	`keyword-only`	`50`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`offset`	`int`	`keyword-only`	`0`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.

`list_project_media`

Projektmedien mit Filtern und Seiten auflisten; total und status_counts beachten.

Python

list_project_media(
    project_id: str,
    *,
    limit: int = 50,
    offset: int = 0,
    search: str | None = None,
    status: str = 'all',
    media_ids: Iterable[str] | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`limit`	`int`	`keyword-only`	`50`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`offset`	`int`	`keyword-only`	`0`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`search`	`str \| None`	`keyword-only`	`None`	Optionaler Suchtext für die angeforderte Projekt- oder Medienliste.
`status`	`str`	`keyword-only`	`'all'`	Statusfilter oder neuer Status je nach Methode; archivierte Projekte behalten gespeicherte Ergebnisse.
`media_ids`	`Iterable[str] \| None`	`keyword-only`	`None`	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.

`list_project_operation_results`

Erfolgreiche gespeicherte Stufenartefakte auflisten, auch aus teilweise fehlgeschlagener Arbeit.

Python

list_project_operation_results(
    project_id: str, operation_id: str
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.

`list_project_operations`

Operationen eines Projekts auflisten, optional für ein Medium.

Python

list_project_operations(
    project_id: str,
    *,
    limit: int = 50,
    offset: int = 0,
    media_id: str | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`limit`	`int`	`keyword-only`	`50`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`offset`	`int`	`keyword-only`	`0`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`media_id`	`str \| None`	`keyword-only`	`None`	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.

`list_archived_projects`

Archivierte Projekte nach Modus, Suchtext und Sortierung seitenweise auflisten. Standardmäßig stehen die zuletzt archivierten zuerst.

Python

list_archived_projects(
    *,
    limit: int = 50,
    offset: int = 0,
    mode: str | None = None,
    search: str | None = None,
    sort: str = 'archived_at',
    direction: str = 'desc'
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`limit`	`int`	`keyword-only`	`50`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`offset`	`int`	`keyword-only`	`0`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`mode`	`str \| None`	`keyword-only`	`None`	Projektmodus: file oder directory.
`search`	`str \| None`	`keyword-only`	`None`	Optionaler Suchtext für die angeforderte Projekt- oder Medienliste.
`sort`	`str`	`keyword-only`	`'archived_at'`	Vom Listenendpunkt unterstütztes Sortierfeld oder Sortierrichtung.
`direction`	`str`	`keyword-only`	`'desc'`	Vom Listenendpunkt unterstütztes Sortierfeld oder Sortierrichtung.

`list_projects`

Aktive Projekte nach Modus, Suchtext und Sortierung seitenweise auflisten.

Python

list_projects(
    *,
    limit: int = 50,
    offset: int = 0,
    mode: str | None = None,
    search: str | None = None,
    sort: str = 'updated_at',
    direction: str = 'desc'
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`limit`	`int`	`keyword-only`	`50`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`offset`	`int`	`keyword-only`	`0`	Seitengröße oder nullbasierter Versatz; bis zur gemeldeten Gesamtzahl weiterblättern.
`mode`	`str \| None`	`keyword-only`	`None`	Projektmodus: file oder directory.
`search`	`str \| None`	`keyword-only`	`None`	Optionaler Suchtext für die angeforderte Projekt- oder Medienliste.
`sort`	`str`	`keyword-only`	`'updated_at'`	Vom Listenendpunkt unterstütztes Sortierfeld oder Sortierrichtung.
`direction`	`str`	`keyword-only`	`'desc'`	Vom Listenendpunkt unterstütztes Sortierfeld oder Sortierrichtung.

`materialize_asset`

Lokal extrahierten physischen Untertiteltext mit aktuellen Beobachtungsschranken registrieren.

Python

materialize_asset(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`preview_project_directory_sync`

Vollständigen lokalen Stand vor Anwendung mit aktuellem Inventar vergleichen.

Python

preview_project_directory_sync(
    project_id: str, files: Iterable[Mapping[str, Any]]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`files`	`Iterable[Mapping[str, Any]]`	`positional-or-keyword`	—	Vollständiger Verzeichnisstand, Dateiliste oder Nachweise dieses Endpunkts; aus lokalen Dateien erstellen.

`preview_project_sidecars`

Treffer und Mehrdeutigkeiten von Begleitdateien vor Zuordnung ermitteln.

Python

preview_project_sidecars(
    project_id: str, sidecars: Iterable[Mapping[str, Any]]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`sidecars`	`Iterable[Mapping[str, Any]]`	`positional-or-keyword`	—	Beobachtete Untertitel-Begleitdateien mit Paarungs- und Klassifikationsdaten.

`put_upload_target`

Direkt mit Backend-Methode und -Headern hochladen; das SubFT-Token wird weggelassen.

Python

put_upload_target(
    upload_url: str,
    *,
    method: str = 'PUT',
    data: Any | None = None,
    content: Any | None = None,
    headers: Mapping[str, str] | None = None,
    content_type: str = 'application/octet-stream'
) -> httpx.Response

Parameter	Typ	Übergabe	Standard	Bedeutung
`upload_url`	`str`	`positional-or-keyword`	—	URL aus der API; relative URLs werden am Gateway aufgelöst. Upload-URLs erhalten kein SubFT-Token.
`method`	`str`	`keyword-only`	`'PUT'`	HTTP-Methode; beim direkten Upload die vom Backend gelieferte Methode beibehalten.
`data`	`Any \| None`	`keyword-only`	`None`	Von HTTPX akzeptierte Formular- oder Upload-Daten; beim direkten Upload nicht mit content kombinieren.
`content`	`Any \| None`	`keyword-only`	`None`	Rohbytes oder eine Folge von Byteblöcken. Für Uploads die vorbereitete Datei verwenden.
`headers`	`Mapping[str, str] \| None`	`keyword-only`	`None`	HTTP-Header. Upload-Header unverändert übernehmen; Anfrage-Header überschreiben Konstruktor-Header.
`content_type`	`str`	`keyword-only`	`'application/octet-stream'`	MIME-Typ der vorbereiteten Daten; ein vorhandener Upload-Header hat Vorrang.

`register_verified_asset_outputs`

Lokal verifizierte physische Ausgaben mit eingefrorener Erfassung registrieren; Download allein reicht nicht.

Python

register_verified_asset_outputs(
    project_id: str, media_id: str, payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`remove_project_media`

Medium über die Projektroute aus dem aktiven Inventar entfernen.

Python

remove_project_media(project_id: str, media_id: str) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.

`replace_project_media`

Geänderte lokale Mediendatei anhand frischer Inventarnachweise abgleichen.

Python

replace_project_media(
    project_id: str, media_id: str, media: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`media`	`Mapping[str, Any]`	`positional-or-keyword`	—	Backend-konforme Inventareinträge oder ausgewählte Projektmedien-IDs aus aktuellen Antworten.

`report_content_progress`

Client-Fortschritt des Versuchs mit aktuellem Vertrag und steigender Revision melden.

Python

report_content_progress(
    operation_id: str,
    media_id: str,
    content_id: str,
    payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`content_id`	`str`	`positional-or-keyword`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`request`

HTTP-Anfrage senden und Rohantwort nach gemeinsamer Fehlerbehandlung zurückgeben.

Python

request(
    method: str,
    path: str,
    *,
    params: Mapping[str, Any] | None = None,
    json: JsonValue | None = None,
    data: Any | None = None,
    content: Any | None = None,
    headers: Mapping[str, str] | None = None,
    authenticated: bool = True
) -> httpx.Response

Parameter	Typ	Übergabe	Standard	Bedeutung
`method`	`str`	`positional-or-keyword`	—	HTTP-Methode; beim direkten Upload die vom Backend gelieferte Methode beibehalten.
`path`	`str`	`positional-or-keyword`	—	HTTP-Pfad relativ zu base_url oder absolute URL; kein lokaler Dateisystempfad.
`params`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	Abfrageparameter; None-Werte und leere Sammlungen werden weggelassen.
`json`	`JsonValue \| None`	`keyword-only`	`None`	JSON-Anfragetext entsprechend dem Vertrag des Endpunkts.
`data`	`Any \| None`	`keyword-only`	`None`	Von HTTPX akzeptierte Formular- oder Upload-Daten; beim direkten Upload nicht mit content kombinieren.
`content`	`Any \| None`	`keyword-only`	`None`	Rohbytes oder eine Folge von Byteblöcken. Für Uploads die vorbereitete Datei verwenden.
`headers`	`Mapping[str, str] \| None`	`keyword-only`	`None`	HTTP-Header. Upload-Header unverändert übernehmen; Anfrage-Header überschreiben Konstruktor-Header.
`authenticated`	`bool`	`keyword-only`	`True`	Ob der Client seinen SubFT-Authorization-Header hinzufügen darf. Direkte Uploads verwenden False.

`request_json`

HTTP-Anfrage senden und JSON dekodieren; leere Antworten liefern None.

Python

request_json(
    method: str,
    path: str,
    *,
    params: Mapping[str, Any] | None = None,
    json: JsonValue | None = None,
    headers: Mapping[str, str] | None = None,
    authenticated: bool = True
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`method`	`str`	`positional-or-keyword`	—	HTTP-Methode; beim direkten Upload die vom Backend gelieferte Methode beibehalten.
`path`	`str`	`positional-or-keyword`	—	HTTP-Pfad relativ zu base_url oder absolute URL; kein lokaler Dateisystempfad.
`params`	`Mapping[str, Any] \| None`	`keyword-only`	`None`	Abfrageparameter; None-Werte und leere Sammlungen werden weggelassen.
`json`	`JsonValue \| None`	`keyword-only`	`None`	JSON-Anfragetext entsprechend dem Vertrag des Endpunkts.
`headers`	`Mapping[str, str] \| None`	`keyword-only`	`None`	HTTP-Header. Upload-Header unverändert übernehmen; Anfrage-Header überschreiben Konstruktor-Header.
`authenticated`	`bool`	`keyword-only`	`True`	Ob der Client seinen SubFT-Authorization-Header hinzufügen darf. Direkte Uploads verwenden False.

`resolve_url`

Relative Backend-URL am Client-Gateway auflösen.

Python

resolve_url(url: str) -> str

Parameter	Typ	Übergabe	Standard	Bedeutung
`url`	`str`	`positional-or-keyword`	—	URL aus der API; relative URLs werden am Gateway aufgelöst. Upload-URLs erhalten kein SubFT-Token.

`restore_project_media`

Ein archiviertes Element wiederherstellen. Ein Video- oder Audioelement braucht media, die aktuellen Inventardaten seiner Datei: Unveränderte Streams behalten ihre Assets. Ein Untertitelelement braucht keine.

Python

restore_project_media(
    project_id: str, media_id: str, media: Mapping[str, Any] | None = None
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`media`	`Mapping[str, Any] \| None`	`positional-or-keyword`	`None`	Inventardatensatz der Datei des Elements wie bei `replace_project_media`; bei einem Untertitelelement weglassen.

`retry_content_preparation`

Neuen zulässigen Vorbereitungsversuch mit vorheriger Versuchs-ID starten; keine neue Operation.

Python

retry_content_preparation(
    operation_id: str,
    media_id: str,
    content_id: str,
    *,
    attempt_id: str,
    previous_attempt_id: str
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`content_id`	`str`	`positional-or-keyword`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.
`attempt_id`	`str`	`keyword-only`	—	Neue UUID, vom Aufrufer gewählt und durch die Vorbereitung bestätigt; für alle Anfragen dieses Versuchs verwenden.
`previous_attempt_id`	`str`	`keyword-only`	—	Versuchs-ID des aktuellen kanonischen Vorbereitungsstands als Schutz vor veralteten Wiederholungen.

`revoke_api_token`

Aktives Servertoken widerrufen; Entfernen eines lokalen Tokens erledigt dies nicht.

Python

revoke_api_token() -> JsonValue

`save_media_asset_document`

Bearbeitbare Cues mit Snapshot- und Versionsschranken speichern; bei Konflikten neu lesen.

Python

save_media_asset_document(
    project_id: str, media_id: str, asset_id: str, payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`scan_project_directory`

Backend um Klassifikation eines lokalen Stands bitten; der Server kann die lokale Festplatte nicht durchsuchen.

Python

scan_project_directory(files: Iterable[str]) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`files`	`Iterable[str]`	`positional-or-keyword`	—	Vollständiger Verzeichnisstand, Dateiliste oder Nachweise dieses Endpunkts; aus lokalen Dateien erstellen.

`start_content_preparation`

Erlaubten Vorbereitungsversuch mit neuer UUID vor Hashing und Upload starten.

Python

start_content_preparation(
    operation_id: str, media_id: str, content_id: str, *, attempt_id: str
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`content_id`	`str`	`positional-or-keyword`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.
`attempt_id`	`str`	`keyword-only`	—	Neue UUID, vom Aufrufer gewählt und durch die Vorbereitung bestätigt; für alle Anfragen dieses Versuchs verwenden.

`update_content_preparation`

Vorbereitung fortsetzen, Heartbeat erneuern oder awaiting_retry-Fehler mit gleichem Versuch melden.

Python

update_content_preparation(
    operation_id: str,
    media_id: str,
    content_id: str,
    attempt_id: str,
    payload: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`content_id`	`str`	`positional-or-keyword`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.
`attempt_id`	`str`	`positional-or-keyword`	—	Neue UUID, vom Aufrufer gewählt und durch die Vorbereitung bestätigt; für alle Anfragen dieses Versuchs verwenden.
`payload`	`Mapping[str, Any]`	`positional-or-keyword`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`update_media_asset`

Erlaubte Asset-Metadaten aktualisieren; Untertitelinhalt bleibt erhalten.

Python

update_media_asset(
    project_id: str, media_id: str, asset_id: str, metadata: Mapping[str, Any]
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`media_id`	`str`	`positional-or-keyword`	—	Medien-ID dieser Route: Projektmedien-ID bei Projektrouten, Operationsmedien-ID beim Hochladen und Vorbereiten.
`asset_id`	`str`	`positional-or-keyword`	—	ID der zum Medium gehörenden Untertitel- oder Audioquelle.
`metadata`	`Mapping[str, Any]`	`positional-or-keyword`	—	Erlaubte Sprach- und Klassifikationsdaten des Assets; dadurch werden keine Untertitel-Cues bearbeitet.

`update_project`

Übermittelte Projektfelder ändern. Weggelassene _UNSET-Felder unterscheiden sich von ausdrücklich geleerten None-Werten.

Python

update_project(
    project_id: str,
    *,
    name: str | None | object = _UNSET,
    root_label: str | None | object = _UNSET
) -> JsonValue

Parameter	Typ	Übergabe	Standard	Bedeutung
`project_id`	`str`	`positional-or-keyword`	—	ID des gespeicherten Projekts aus der Erstellung oder Projektliste.
`name`	`str \| None \| object`	`keyword-only`	`_UNSET`	Anzeigename des Projekts; update_project kann nullable Werte mit None leeren.
`root_label`	`str \| None \| object`	`keyword-only`	`_UNSET`	Lesbare Bezeichnung des Wurzelpfads, kein für den Server erreichbarer lokaler Dateipfad.

`verify_auth`

Wirksame Zugangsdaten prüfen und Kontoidentität lesen.

Python

verify_auth() -> JsonValue

Exporte des Basispakets

Aus subft_client importieren. Lokale Funktionen benötigen das lokale Extra und gewählte Systemwerkzeuge. Fehler vor Inventaränderung prüfen. Echtzeit benötigt sein Extra und führt keinen kanonischen HTTP-Abgleich aus.

`JsonArray`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

JsonArray = list[Any]

`JsonObject`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

JsonObject = dict[str, Any]

`JsonValue`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

JsonValue = Any

`SubftApiError`

Öffentliche Ausnahme. Bei unterschiedlicher Wiederherstellung spezifischen Typ abfangen; Basisausnahme umfasst Unterklassen. Optionale Konstruktorfelder erhalten annotierten HTTP-Status, Antwort- oder Transportnachweise.

Python

SubftApiError(
    status_code: int,
    message: str,
    *,
    payload: Any | None = None,
    response: httpx.Response | None = None
) -> None

`SubftClient`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Python

SubftClient(
    base_url: str,
    *,
    token: str | None = None,
    timeout: float | httpx.Timeout = 30.0,
    headers: Mapping[str, str] | None = None,
    cookies: Mapping[str, str] | None = None,
    transport: httpx.BaseTransport | None = None
) -> None

`SubftError`

`SubftMaintenanceError`

Python

SubftMaintenanceError(
    status_code: int,
    message: str,
    *,
    payload: Any | None = None,
    response: httpx.Response | None = None,
    mode: str | None = None,
    maintenance_until: str | None = None
) -> None

`SubftTransportError`

Python

SubftTransportError(
    message: str, *, request_error: httpx.RequestError
) -> None

`version`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

__version__ = '0.1.0'

Lokale Helfer und Datensätze

Aus subft_client.local importieren. Lokale Funktionen benötigen das lokale Extra und gewählte Systemwerkzeuge. Fehler vor Inventaränderung prüfen. Echtzeit benötigt sein Extra und führt keinen kanonischen HTTP-Abgleich aus.

`AUDIO_EXTENSIONS`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

AUDIO_EXTENSIONS = frozenset({'mp3', 'wav', 'flac', 'aac', 'ogg', 'm4a'})

`DEFAULT_HASH_CHUNK_SIZE`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

DEFAULT_HASH_CHUNK_SIZE = 4 * 1024 * 1024

`DirectorySnapshotFile`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`path`	`str`	`True`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`size_bytes`	`int`	`True`	—	Tatsächliche Datei-/Transfergröße oder gemessener Bytefortschritt.
`last_modified_ms`	`int`	`True`	—	Beobachtete Dateiänderungszeit in Millisekunden.
`mime_type`	`str \| None`	`True`	—	Ermittelter MIME-Typ; er belegt allein keine Codec-Unterstützung.
`file_kind`	`LocalFileKind`	`True`	—	Erkannte Erweiterung, Inventarklassifikation oder analysierter Container.
`file_fingerprint_hash`	`str \| None`	`False`	`None`	An der Quelle gemessener Hash/Fingerabdruck; dessen Typ beachten.
`language_text_sample`	`str \| None`	`False`	`None`	Begrenzter tatsächlicher Untertiteltext als Sprachnachweis.

Python

to_api_dict() -> JsonObject

`DirectorySnapshotResult`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`files`	`tuple[DirectorySnapshotFile, ...]`	`True`	—	Vollständiger Verzeichnisstand, Dateiliste oder Nachweise dieses Endpunkts; aus lokalen Dateien erstellen.
`failures`	`tuple[LocalFailure, ...]`	`True`	—	Aufgezeichnete Einzelfehler; dadurch ist ein Teilinventar nicht sicher übermittelbar.

Python

to_api_dict() -> JsonObject

`ExtractedFile`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`path`	`Path`	`True`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`filename`	`str`	`True`	—	Name der vorbereiteten Datei mit tatsächlicher Erweiterung zur Wahl des Speicherformats.
`content_type`	`str`	`True`	—	MIME-Typ der vorbereiteten Daten; ein vorhandener Upload-Header hat Vorrang.

Python

to_api_dict() -> JsonObject

`FfmpegTools`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`wrapper_available`	`bool`	`True`	—	Beobachtete Werkzeuginstallation, Version oder Diagnose; Python-Extras installieren keine Systemprogramme.
`ffmpeg_path`	`str \| None`	`True`	—	Beobachtete Werkzeuginstallation, Version oder Diagnose; Python-Extras installieren keine Systemprogramme.
`ffmpeg_version`	`str \| None`	`True`	—	Beobachtete Werkzeuginstallation, Version oder Diagnose; Python-Extras installieren keine Systemprogramme.
`ffmpeg_error`	`str \| None`	`True`	—	Beobachtete Werkzeuginstallation, Version oder Diagnose; Python-Extras installieren keine Systemprogramme.
`ffprobe_path`	`str \| None`	`True`	—	Beobachtete Werkzeuginstallation, Version oder Diagnose; Python-Extras installieren keine Systemprogramme.
`ffprobe_version`	`str \| None`	`True`	—	Beobachtete Werkzeuginstallation, Version oder Diagnose; Python-Extras installieren keine Systemprogramme.
`ffprobe_error`	`str \| None`	`True`	—	Beobachtete Werkzeuginstallation, Version oder Diagnose; Python-Extras installieren keine Systemprogramme.

Python

ffmpeg_available: bool

Python

ffprobe_available: bool

Python

available: bool

Python

to_api_dict() -> JsonObject

`FfmpegUnavailableError`

`FileFingerprint`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`kind`	`FingerprintKind`	`True`	—	Endpunktspezifischer Assettyp, Prüfumfang, Bereitschafts- oder Platzierungswert gemäß dessen Vertrag.
`hash`	`str`	`True`	—	An der Quelle gemessener Hash/Fingerabdruck; dessen Typ beachten.

Python

to_api_dict() -> JsonObject

`GRAPHICAL_SUBTITLE_EXTENSIONS`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

GRAPHICAL_SUBTITLE_EXTENSIONS = frozenset({'sup', 'idx', 'sub'})

`InventoryResult`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`items`	`tuple[MediaInventoryItem, ...]`	`True`	—	Geprüfte Medieneinträge; Fehler vor Übermittlung prüfen.
`failures`	`tuple[LocalFailure, ...]`	`True`	—	Aufgezeichnete Einzelfehler; dadurch ist ein Teilinventar nicht sicher übermittelbar.
`total_candidates`	`int`	`True`	—	Zahl der Scan-Kandidaten vor Filterung nicht unterstützter Dateien oder Fehler.

Python

to_api_dict() -> JsonObject

`LANGUAGE_SAMPLE_BYTES`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

LANGUAGE_SAMPLE_BYTES = 64 * 1024

`LocalFailure`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`path`	`str`	`True`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`error_type`	`str`	`True`	—	Technische Diagnosedaten für interne Protokolle; öffentliche Oberflächen übersetzen Codes.
`message`	`str`	`True`	—	Technische Diagnosedaten für interne Protokolle; öffentliche Oberflächen übersetzen Codes.

Python

from_exception(path: str | Path, error: Exception) -> LocalFailure

Python

to_api_dict() -> JsonObject

`LocalFile`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`absolute_path`	`Path`	`True`	—	Aufgelöster lokaler Pfad des Aufrufers; nicht in öffentlicher Suche veröffentlichen.
`relative_path`	`str`	`True`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`size_bytes`	`int`	`True`	—	Tatsächliche Datei-/Transfergröße oder gemessener Bytefortschritt.
`last_modified_ms`	`int`	`True`	—	Beobachtete Dateiänderungszeit in Millisekunden.
`mime_type`	`str \| None`	`True`	—	Ermittelter MIME-Typ; er belegt allein keine Codec-Unterstützung.
`suffix`	`str`	`True`	—	Erkannte Erweiterung, Inventarklassifikation oder analysierter Container.
`file_kind`	`LocalFileKind`	`True`	—	Erkannte Erweiterung, Inventarklassifikation oder analysierter Container.

Python

to_api_dict() -> JsonObject

`LocalFileChangedError`

`LocalHashError`

`LocalPathError`

`LocalProgress`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`phase`	`ProgressPhase`	`True`	—	Lokale Fortschrittsphase und gemessene Elemente/Bytes; Rückrufe sind synchron.
`path`	`str \| None`	`True`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`current`	`int`	`True`	—	Lokale Fortschrittsphase und gemessene Elemente/Bytes; Rückrufe sind synchron.
`total`	`int`	`True`	—	Lokale Fortschrittsphase und gemessene Elemente/Bytes; Rückrufe sind synchron.
`loaded_bytes`	`int \| None`	`False`	`None`	Tatsächliche Datei-/Transfergröße oder gemessener Bytefortschritt.
`total_bytes`	`int \| None`	`False`	`None`	Tatsächliche Datei-/Transfergröße oder gemessener Bytefortschritt.

Python

percent: float

Python

to_api_dict() -> JsonObject

`LocalScanError`

`MediaInventoryItem`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`path`	`str`	`True`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`display_name`	`str`	`True`	—	Anzeigename dieses lokal beobachteten Mediums.
`size_bytes`	`int`	`True`	—	Tatsächliche Datei-/Transfergröße oder gemessener Bytefortschritt.
`last_modified_ms`	`int`	`True`	—	Beobachtete Dateiänderungszeit in Millisekunden.
`mime_type`	`str \| None`	`True`	—	Ermittelter MIME-Typ; er belegt allein keine Codec-Unterstützung.
`file_fingerprint_hash`	`str \| None`	`True`	—	An der Quelle gemessener Hash/Fingerabdruck; dessen Typ beachten.
`duration_seconds`	`float`	`True`	—	Gemessene Dauer in Sekunden, keine zugesagte Verarbeitungszeit.
`container_format`	`str \| None`	`True`	—	Erkannte Erweiterung, Inventarklassifikation oder analysierter Container.
`probe_data`	`JsonObject \| None`	`True`	—	Tatsächliche FFprobe-Container-/Streamdaten; offene Wörterbücher behalten deren Felder.
`streams`	`tuple[ProbeStream, ...]`	`True`	—	Normalisierte Audio-/Untertitelspuren mit ursprünglichen Indizes.
`status`	`str`	`False`	`'active'`	Statusfilter oder neuer Status je nach Methode; archivierte Projekte behalten gespeicherte Ergebnisse.

Python

to_api_dict() -> JsonObject

`MediaEmbeddingError`

`MediaExtractionError`

`MediaProbe`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`duration_seconds`	`float`	`True`	—	Gemessene Dauer in Sekunden, keine zugesagte Verarbeitungszeit.
`has_audio`	`bool`	`True`	—	Ob die beobachtete Spur/Quelle auswählbar ist oder Audio enthält.
`streams`	`tuple[ProbeStream, ...]`	`True`	—	Normalisierte Audio-/Untertitelspuren mit ursprünglichen Indizes.
`format`	`JsonObject`	`True`	—	Tatsächliche FFprobe-Container-/Streamdaten; offene Wörterbücher behalten deren Felder.
`raw_streams`	`tuple[JsonObject, ...]`	`True`	—	Tatsächliche FFprobe-Container-/Streamdaten; offene Wörterbücher behalten deren Felder.

Python

to_api_dict() -> JsonObject

`MediaProbeError`

`MuxedMedia`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`path`	`Path`	`True`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`size_bytes`	`int`	`True`	—	Tatsächliche Datei-/Transfergröße oder gemessener Bytefortschritt.
`last_modified_ms`	`int`	`True`	—	Beobachtete Dateiänderungszeit in Millisekunden.

Python

to_api_dict() -> JsonObject

`ProbeStream`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`stream_index`	`int \| None`	`True`	—	FFprobe-Streamindex oder ausdrücklich zu ersetzende Indizes, nicht die Position in einer gefilterten Liste.
`stream_type`	`str`	`True`	—	Tatsächlicher Stream-Codec oder Untertitelklassifikation, unabhängig von Importerkennung.
`stream_class`	`StreamClass`	`True`	—	Normal oder eine beliebige Kombination aus Kommentar, Forced und SDH.
`codec_type`	`str`	`True`	—	Tatsächlicher Stream-Codec oder Untertitelklassifikation, unabhängig von Importerkennung.
`codec_name`	`str \| None`	`True`	—	Tatsächlicher Stream-Codec oder Untertitelklassifikation, unabhängig von Importerkennung.
`language`	`str \| None`	`True`	—	Untertitelsprache oder Klassifikation normal/Forced/SDH/Kommentar; technische Sprachcodes bleiben unverändert.
`tags`	`JsonObject \| None`	`True`	—	Aktuelle Streamdaten und physische Nachweise für Beobachtungsschranken.
`disposition`	`JsonObject \| None`	`True`	—	Aktuelle Streamdaten und physische Nachweise für Beobachtungsschranken.
`selectable`	`bool`	`False`	`True`	Ob die beobachtete Spur/Quelle auswählbar ist oder Audio enthält.
`language_text_sample`	`str \| None`	`False`	`None`	Begrenzter tatsächlicher Untertiteltext als Sprachnachweis.
`sidecar_path`	`str \| None`	`False`	`None`	Identität und Nachweise der Begleitdatei; zusammengehöriges Paar erhalten.
`sidecar_display_name`	`str \| None`	`False`	`None`	Identität und Nachweise der Begleitdatei; zusammengehöriges Paar erhalten.
`sidecar_size_bytes`	`int \| None`	`False`	`None`	Identität und Nachweise der Begleitdatei; zusammengehöriges Paar erhalten.
`sidecar_last_modified_ms`	`int \| None`	`False`	`None`	Identität und Nachweise der Begleitdatei; zusammengehöriges Paar erhalten.
`sidecar_content_hash`	`str \| None`	`False`	`None`	Identität und Nachweise der Begleitdatei; zusammengehöriges Paar erhalten.
`source_observation`	`JsonObject \| None`	`False`	`None`	Aktuelle Streamdaten und physische Nachweise für Beobachtungsschranken.
`text_content`	`str \| None`	`False`	`None`	Vollständiger Untertiteltext, den Dateiprojekte speichern; `None` für andere Spuren.

Python

to_api_dict() -> JsonObject

`SUBTITLE_EXTENSIONS`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

SUBTITLE_EXTENSIONS = frozenset({'srt', 'vtt', 'ass'})

`ScanResult`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`files`	`tuple[LocalFile, ...]`	`True`	—	Vollständiger Verzeichnisstand, Dateiliste oder Nachweise dieses Endpunkts; aus lokalen Dateien erstellen.
`failures`	`tuple[LocalFailure, ...]`	`True`	—	Aufgezeichnete Einzelfehler; dadurch ist ein Teilinventar nicht sicher übermittelbar.

Python

to_api_dict() -> JsonObject

`SubftLocalError`

`SubtitleMuxInput`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`path`	`Path`	`True`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`language`	`str \| None`	`False`	`None`	Untertitelsprache oder Klassifikation normal/Forced/SDH/Kommentar; technische Sprachcodes bleiben unverändert.
`stream_class`	`StreamClass`	`False`	`'normal'`	Normal oder eine beliebige Kombination aus Kommentar, Forced und SDH.

`VIDEO_EXTENSIONS`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

VIDEO_EXTENSIONS = frozenset({'mp4', 'mkv', 'avi', 'mov', 'webm'})

`VOBSUB_EXTENSIONS`

Öffentliche Konstante oder Typalias. Der Wert stammt aus dem Quellcode; Bezeichner und Einheiten behalten ihre technische Bedeutung.

Python

VOBSUB_EXTENSIONS = frozenset({'idx', 'sub'})

`build_directory_snapshot`

Vollständige Dateien, Fingerabdrücke und begrenzte Sprachproben für Verzeichnisabgleich erstellen.

Python

build_directory_snapshot(
    source: FileCollection,
    *,
    include_hidden: bool = False,
    hash_media_paths: Iterable[str | os.PathLike[str]] = (),
    include_text_samples: bool = False,
    on_progress: ProgressCallback | None = None
) -> DirectorySnapshotResult

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`FileCollection`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`include_hidden`	`bool`	`keyword-only`	`False`	Bei True Dateien und Verzeichnisse mit Punktpräfix einschließen; Symlinks bleiben ausgeschlossen.
`hash_media_paths`	`Iterable[str \| os.PathLike[str]]`	`keyword-only`	`()`	Relative Medienpfade, deren Fingerabdrücke für diesen Verzeichnisstand benötigt werden.
`include_text_samples`	`bool`	`keyword-only`	`False`	Begrenzte Sprachproben aus Untertiteln einschließen oder maximale Quellbytezahl festlegen.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.

`build_inventory`

Gescannten Medienbestand API-konform prüfen; jeden aufgezeichneten Fehler vor Übermittlung behandeln.

Python

build_inventory(
    source: FileCollection,
    *,
    include_hidden: bool = False,
    ffprobe_executable: str = 'ffprobe',
    probe_timeout: float = 30.0,
    on_progress: ProgressCallback | None = None
) -> InventoryResult

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`FileCollection`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`include_hidden`	`bool`	`keyword-only`	`False`	Bei True Dateien und Verzeichnisse mit Punktpräfix einschließen; Symlinks bleiben ausgeschlossen.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`probe_timeout`	`float`	`keyword-only`	`30.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.

`check_ffmpeg_tools`

Werkzeugverfügbarkeit zurückgeben, ohne alle Werkzeuge vorauszusetzen.

Python

check_ffmpeg_tools(
    *,
    ffmpeg_executable: str = 'ffmpeg',
    ffprobe_executable: str = 'ffprobe',
    timeout: float = 5.0
) -> FfmpegTools

Parameter	Typ	Übergabe	Standard	Bedeutung
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`timeout`	`float`	`keyword-only`	`5.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.

`count_pgs_images`

Grafische Untertitelbilder aus der tatsächlichen Quelle zählen; VobSub benötigt beide Dateien.

Python

count_pgs_images(content: bytes) -> int

Parameter	Typ	Übergabe	Standard	Bedeutung
`content`	`bytes`	`positional-or-keyword`	—	Rohbytes oder eine Folge von Byteblöcken. Für Uploads die vorbereitete Datei verwenden.

`count_vobsub_images`

Grafische Untertitelbilder aus der tatsächlichen Quelle zählen; VobSub benötigt beide Dateien.

Python

count_vobsub_images(text: str) -> int

Parameter	Typ	Übergabe	Standard	Bedeutung
`text`	`str`	`positional-or-keyword`	—	Tatsächlicher Untertiteltext oder dessen Format SRT/VTT/ASS; Metriken normalisieren Formatierung statt Dateibytes zu zählen.

`embed_subtitle_tracks`

Ausgabe des Aufrufers muxen und andere Streams erhalten; Installation und Registrierung sind getrennt.

Python

embed_subtitle_tracks(
    source: LocalSource,
    subtitles: Iterable[SubtitleMuxInput],
    output_path: str | os.PathLike[str],
    *,
    ffmpeg_executable: str = 'ffmpeg',
    ffprobe_executable: str = 'ffprobe',
    timeout: float = 1800.0,
    on_progress: ProgressCallback | None = None,
    replace_stream_indexes: Iterable[int] = ()
) -> MuxedMedia

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalSource`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`subtitles`	`Iterable[SubtitleMuxInput]`	`positional-or-keyword`	—	SubtitleMuxInput-Einträge mit tatsächlichen SRT-Dateien, Sprachen und Streamklassen zum Hinzufügen.
`output_path`	`str \| os.PathLike[str]`	`positional-or-keyword`	—	Neuer Ausgabepfad des Aufrufers. Extraktion und Muxen ersetzen kein Original und registrieren keine Backend-Assets.
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`timeout`	`float`	`keyword-only`	`1800.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.
`replace_stream_indexes`	`Iterable[int]`	`keyword-only`	`()`	FFprobe-Streamindex oder ausdrücklich zu ersetzende Indizes, nicht die Position in einer gefilterten Liste.

`extract_audio_stream`

Gewählte Audiospur als MP3 extrahieren, ohne das Original zu ändern.

Python

extract_audio_stream(
    source: LocalSource,
    stream_index: int,
    output_path: str | os.PathLike[str],
    *,
    ffmpeg_executable: str = 'ffmpeg',
    timeout: float = 1800.0,
    on_progress: ProgressCallback | None = None
) -> ExtractedFile

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalSource`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`stream_index`	`int`	`positional-or-keyword`	—	FFprobe-Streamindex oder ausdrücklich zu ersetzende Indizes, nicht die Position in einer gefilterten Liste.
`output_path`	`str \| os.PathLike[str]`	`positional-or-keyword`	—	Neuer Ausgabepfad des Aufrufers. Extraktion und Muxen ersetzen kein Original und registrieren keine Backend-Assets.
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`timeout`	`float`	`keyword-only`	`1800.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.

`extract_subtitle_stream`

Text als SRT extrahieren oder grafische Untertitel nach Matroska kopieren; Aufrufer bereinigt.

Python

extract_subtitle_stream(
    source: LocalSource,
    stream_index: int,
    output_path: str | os.PathLike[str],
    *,
    graphical: bool = False,
    source_format: str = 'srt',
    ffmpeg_executable: str = 'ffmpeg',
    timeout: float = 1800.0,
    on_progress: ProgressCallback | None = None
) -> ExtractedFile

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalSource`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`stream_index`	`int`	`positional-or-keyword`	—	FFprobe-Streamindex oder ausdrücklich zu ersetzende Indizes, nicht die Position in einer gefilterten Liste.
`output_path`	`str \| os.PathLike[str]`	`positional-or-keyword`	—	Neuer Ausgabepfad des Aufrufers. Extraktion und Muxen ersetzen kein Original und registrieren keine Backend-Assets.
`graphical`	`bool`	`keyword-only`	`False`	Ob die Extraktion eine grafische Untertitelspur nach Matroska kopiert statt SRT zu erzeugen.
`source_format`	`str`	`keyword-only`	`'srt'`	Tatsächlicher Untertiteltext oder dessen Format SRT/VTT/ASS; Metriken normalisieren Formatierung statt Dateibytes zu zählen.
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`timeout`	`float`	`keyword-only`	`1800.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.

`fingerprint_media_file`

Kompatiblen vollständigen oder teilweisen Medienfingerabdruck berechnen und Quelländerungen ablehnen.

Python

fingerprint_media_file(
    source: LocalSource,
    *,
    chunk_size: int = DEFAULT_HASH_CHUNK_SIZE,
    on_progress: ProgressCallback | None = None
) -> FileFingerprint

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalSource`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`chunk_size`	`int`	`keyword-only`	`DEFAULT_HASH_CHUNK_SIZE`	Positive Bytezahl pro Hash-Leseblock; für kompatible Teilfingerabdrücke den Standard behalten.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.

`hash_file_sha256`

Alle Bytes in einen SHA-256-FileFingerprint einlesen; für API-Anfragen dessen hash verwenden.

Python

hash_file_sha256(
    source: LocalSource,
    *,
    chunk_size: int = DEFAULT_HASH_CHUNK_SIZE,
    on_progress: ProgressCallback | None = None
) -> FileFingerprint

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalSource`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`chunk_size`	`int`	`keyword-only`	`DEFAULT_HASH_CHUNK_SIZE`	Positive Bytezahl pro Hash-Leseblock; für kompatible Teilfingerabdrücke den Standard behalten.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.

`hash_text_subtitle`

Untertiteltext nach Normalisierung von Zeilenumbrüchen und äußerem Leerraum hashen.

Python

hash_text_subtitle(source: LocalSource) -> FileFingerprint

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalSource`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.

`inspect_media`

Eine unterstützte Datei prüfen und tatsächliche Analyse- und Quellnachweise zurückgeben.

Python

inspect_media(
    source: LocalFile | str | os.PathLike[str],
    *,
    relative_path: str | None = None,
    ffprobe_executable: str = 'ffprobe',
    probe_timeout: float = 30.0,
    on_progress: ProgressCallback | None = None,
    file_project: bool = False
) -> MediaInventoryItem

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalFile \| str \| os.PathLike[str]`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`relative_path`	`str \| None`	`keyword-only`	`None`	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`probe_timeout`	`float`	`keyword-only`	`30.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.
`file_project`	`bool`	`keyword-only`	`False`	Regeln für Dateiprojekte anwenden: vollständigen Untertiteltext aufnehmen und grafische Untertiteldateien ablehnen.

`pgs_duration_seconds`

Untertiteldauer in Sekunden aus tatsächlichen Cue- oder Bildzeiten ermitteln.

Python

pgs_duration_seconds(content: bytes) -> float

Parameter	Typ	Übergabe	Standard	Bedeutung
`content`	`bytes`	`positional-or-keyword`	—	Rohbytes oder eine Folge von Byteblöcken. Für Uploads die vorbereitete Datei verwenden.

`probe_media`

FFprobe-Dauer, Streams und Containernachweise ohne Dateiänderung lesen.

Python

probe_media(
    source: LocalSource,
    *,
    ffprobe_executable: str = 'ffprobe',
    timeout: float = 30.0
) -> MediaProbe

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalSource`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`timeout`	`float`	`keyword-only`	`30.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.

`read_subtitle_language_sample`

Begrenzte Quelltextprobe für Sprachklassifikation lesen.

Python

read_subtitle_language_sample(
    source: LocalSource, *, max_bytes: int = LANGUAGE_SAMPLE_BYTES
) -> str | None

Parameter	Typ	Übergabe	Standard	Bedeutung
`source`	`LocalSource`	`positional-or-keyword`	—	Vorhandene Quelldatei, LocalFile-Eintrag oder annotierte Dateisammlung; Fehler vor Inventarübermittlung prüfen.
`max_bytes`	`int`	`keyword-only`	`LANGUAGE_SAMPLE_BYTES`	Begrenzte Sprachproben aus Untertiteln einschließen oder maximale Quellbytezahl festlegen.

`require_ffmpeg_tools`

Gewählte Werkzeuge verlangen und bei fehlenden Voraussetzungen FfmpegUnavailableError auslösen.

Python

require_ffmpeg_tools(
    *,
    ffmpeg_executable: str = 'ffmpeg',
    ffprobe_executable: str = 'ffprobe',
    timeout: float = 5.0,
    require_ffmpeg: bool = True,
    require_ffprobe: bool = True
) -> FfmpegTools

Parameter	Typ	Übergabe	Standard	Bedeutung
`ffmpeg_executable`	`str`	`keyword-only`	`'ffmpeg'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`ffprobe_executable`	`str`	`keyword-only`	`'ffprobe'`	Name oder Pfad des Systemprogramms; das Python-Extra installiert diese Programme nicht.
`timeout`	`float`	`keyword-only`	`5.0`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.
`require_ffmpeg`	`bool`	`keyword-only`	`True`	Ob diese Werkzeugprüfung das jeweilige Programm voraussetzt.
`require_ffprobe`	`bool`	`keyword-only`	`True`	Ob diese Werkzeugprüfung das jeweilige Programm voraussetzt.

`scan_directory`

Deterministisch scannen, Symlinks auslassen und Fehler je Pfad aufzeichnen.

Python

scan_directory(
    root: str | os.PathLike[str],
    *,
    include_hidden: bool = False,
    on_progress: ProgressCallback | None = None
) -> ScanResult

Parameter	Typ	Übergabe	Standard	Bedeutung
`root`	`str \| os.PathLike[str]`	`positional-or-keyword`	—	Lokaler Wurzelpfad, Pfad oder relativer POSIX-Pfad. Scan-Helfer schließen Symlinks aus; Pfade innerhalb der Wurzel halten.
`include_hidden`	`bool`	`keyword-only`	`False`	Bei True Dateien und Verzeichnisse mit Punktpräfix einschließen; Symlinks bleiben ausgeschlossen.
`on_progress`	`ProgressCallback \| None`	`keyword-only`	`None`	Synchroner Rückruf mit LocalProgress. Eine Ausnahme bricht die Arbeit ab und wird weitergegeben.

`subtitle_duration_seconds`

Untertiteldauer in Sekunden aus tatsächlichen Cue- oder Bildzeiten ermitteln.

Python

subtitle_duration_seconds(
    text: str, format_hint: str | None = None
) -> float

Parameter	Typ	Übergabe	Standard	Bedeutung
`text`	`str`	`positional-or-keyword`	—	Tatsächlicher Untertiteltext oder dessen Format SRT/VTT/ASS; Metriken normalisieren Formatierung statt Dateibytes zu zählen.
`format_hint`	`str \| None`	`positional-or-keyword`	`None`	Tatsächlicher Untertiteltext oder dessen Format SRT/VTT/ASS; Metriken normalisieren Formatierung statt Dateibytes zu zählen.

`vobsub_duration_seconds`

Untertiteldauer in Sekunden aus tatsächlichen Cue- oder Bildzeiten ermitteln.

Python

vobsub_duration_seconds(text: str) -> float

Parameter	Typ	Übergabe	Standard	Bedeutung
`text`	`str`	`positional-or-keyword`	—	Tatsächlicher Untertiteltext oder dessen Format SRT/VTT/ASS; Metriken normalisieren Formatierung statt Dateibytes zu zählen.

`vobsub_pair_hash`

Zusammengehörende IDX/SUB-Fingerabdrücke in dokumentierter Reihenfolge kombinieren.

Python

vobsub_pair_hash(idx_hash: str, sub_hash: str) -> str

Parameter	Typ	Übergabe	Standard	Bedeutung
`idx_hash`	`str`	`positional-or-keyword`	—	Hashes der tatsächlich zusammengehörenden IDX- und SUB-Dateien für einen stabilen Paar-Hash.
`sub_hash`	`str`	`positional-or-keyword`	—	Hashes der tatsächlich zusammengehörenden IDX- und SUB-Dateien für einen stabilen Paar-Hash.

`visible_subtitle_character_count`

Sichtbare Untertitelzeichen nach den Abrechnungsregeln zählen.

Python

visible_subtitle_character_count(
    text: str, format_hint: str | None = None
) -> int

Parameter	Typ	Übergabe	Standard	Bedeutung
`text`	`str`	`positional-or-keyword`	—	Tatsächlicher Untertiteltext oder dessen Format SRT/VTT/ASS; Metriken normalisieren Formatierung statt Dateibytes zu zählen.
`format_hint`	`str \| None`	`positional-or-keyword`	`None`	Tatsächlicher Untertiteltext oder dessen Format SRT/VTT/ASS; Metriken normalisieren Formatierung statt Dateibytes zu zählen.

Echtzeit-Helfer und Datensätze

Aus subft_client.realtime importieren. Lokale Funktionen benötigen das lokale Extra und gewählte Systemwerkzeuge. Fehler vor Inventaränderung prüfen. Echtzeit benötigt sein Extra und führt keinen kanonischen HTTP-Abgleich aus.

`OperationEvent`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`event`	`str`	`True`	—	Echtzeit-Ereignis-/Verbindungsdaten; Ergebnis erst nach kanonischem HTTP-Lesen bestimmen.
`operation_id`	`str`	`True`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`content_id`	`str \| None`	`True`	—	Ein Quellelement einer Operation, keine Projektmedien- oder Artefakt-ID.
`session_id`	`str \| None`	`True`	—	Echtzeit-Ereignis-/Verbindungsdaten; Ergebnis erst nach kanonischem HTTP-Lesen bestimmen.
`status`	`str \| None`	`True`	—	Statusfilter oder neuer Status je nach Methode; archivierte Projekte behalten gespeicherte Ergebnisse.
`payload`	`Mapping[str, Any]`	`True`	—	Endpunktspezifische Anfragedaten. Schema beachten und Beobachtungs- oder Vorbereitungsschranken beibehalten.

`RealtimeConnectionState`

Öffentlicher Client oder unveränderlicher Datensatz. Felder liefern lokale oder Echtzeitnachweise, keinen Arbeitsauftrag. Methoden unten stellen gespeicherte Werte bereit.

Feld	Typ	Erforderlich	Deklaration / Standard	Bedeutung
`status`	`ConnectionStatus`	`True`	—	Statusfilter oder neuer Status je nach Methode; archivierte Projekte behalten gespeicherte Ergebnisse.
`attempt`	`int`	`True`	—	Echtzeit-Ereignis-/Verbindungsdaten; Ergebnis erst nach kanonischem HTTP-Lesen bestimmen.
`reconnected`	`bool`	`True`	—	Ob das Ereignis auf erfolgreiche Wiederverbindung folgt; kanonischen Stand neu lesen.
`reason`	`str \| None`	`False`	`None`	Technischer Grund dieses Verbindungsstands; Wiederherstellung anhand kanonischem HTTP-Stand entscheiden.

`RealtimeDependencyError`

`RealtimeProtocolError`

`RealtimeSubscriptionError`

Python

RealtimeSubscriptionError(code: str='request_failed', params: Mapping[str, Any] | None=None)

Abgelehnte Echtzeit-Abonnements verwenden event: "failed" mit einem {code, params}-Deskriptor in payload.error. RealtimeSubscriptionError stellt code und params bereit; Diagnosetexte sind kein Vertrag für die Darstellung.

`SubftRealtimeError`

`watch_operation_events`

Operationsereignisse und Verbindungswechsel mit Wiederverbindung liefern; kanonischer HTTP-Abgleich bleibt Aufgabe des Aufrufers.

Python

watch_operation_events(
    base_url: str,
    operation_id: str,
    *,
    token: str,
    heartbeat_interval: float = DEFAULT_HEARTBEAT_INTERVAL,
    pong_timeout: float = DEFAULT_PONG_TIMEOUT,
    subscribe_timeout: float = DEFAULT_SUBSCRIBE_TIMEOUT,
    reconnect_initial_delay: float = DEFAULT_RECONNECT_INITIAL_DELAY,
    reconnect_max_delay: float = DEFAULT_RECONNECT_MAX_DELAY,
    _sleep: Callable[[float], Awaitable[None]] = asyncio.sleep
) -> AsyncGenerator[RealtimeMessage, None]

Parameter	Typ	Übergabe	Standard	Bedeutung
`base_url`	`str`	`positional-or-keyword`	—	Gateway-URL für API, Anmeldung und Echtzeitrouten; der abschließende Schrägstrich wird normalisiert.
`operation_id`	`str`	`positional-or-keyword`	—	ID der gestarteten Operation; vor dem Verlassen oder einem Vorbereitungsversuch aufbewahren.
`token`	`str`	`keyword-only`	—	API-Token aus dem Entwicklerzugang. In einer geschützten Umgebungsvariable halten.
`heartbeat_interval`	`float`	`keyword-only`	`DEFAULT_HEARTBEAT_INTERVAL`	Heartbeat-, Pong- oder Wiederverbindungsintervall in Sekunden; Wiederverbindung nutzt begrenztes Backoff.
`pong_timeout`	`float`	`keyword-only`	`DEFAULT_PONG_TIMEOUT`	Heartbeat-, Pong- oder Wiederverbindungsintervall in Sekunden; Wiederverbindung nutzt begrenztes Backoff.
`subscribe_timeout`	`float`	`keyword-only`	`DEFAULT_SUBSCRIBE_TIMEOUT`	Zeitlimit in Sekunden; der Standard für Anfrage, Analyse oder Abonnement steht in der Signatur.
`reconnect_initial_delay`	`float`	`keyword-only`	`DEFAULT_RECONNECT_INITIAL_DELAY`	Heartbeat-, Pong- oder Wiederverbindungsintervall in Sekunden; Wiederverbindung nutzt begrenztes Backoff.
`reconnect_max_delay`	`float`	`keyword-only`	`DEFAULT_RECONNECT_MAX_DELAY`	Heartbeat-, Pong- oder Wiederverbindungsintervall in Sekunden; Wiederverbindung nutzt begrenztes Backoff.
`_sleep`	`Callable[[float], Awaitable[None]]`	`keyword-only`	`asyncio.sleep`	Optionale asynchrone Wartefunktion für deterministische Tests; normale Integrationen behalten den Standard.

Anfrage- und Antwortschemata

Die Tabellen geben deklarierte und geerbte Felder wieder. Erforderlich verwendet True/False. Ein Strich bedeutet keine Standarddeklaration; Field(...) zeigt tatsächliche Pydantic-Standards und Grenzen. Nullable Felder können Pflichtfelder sein. Benannte Typen beschreiben verschachtelte Datensätze; dict[str, Any] ist absichtlich offen, kein erfundenes vollständiges Schema. Upload-Ziele liefern außerdem upload_id, operation_id, media_id, content_id, upload_url, method, headers, expires_at und optional sidecar; Identität, Ablauf und Methode erhalten. Das vollständige Beispiel prüft verwendete Felder.