Python API reference

Parameters, returns and errors

This is a thin synchronous HTTP client. It does not prompt, scan automatically or orchestrate paid work for you. Use the complete recipe before adapting it. API methods need an account/token and access to the selected project. Planning and estimation do not charge; committing an operation does. Token generation/revocation needs the authenticated account and replaces/revokes its single active token.

positional-only, positional-or-keyword, keyword-only and variadic kinds describe Python calling syntax. A dash in Default means no default; required arguments must be supplied. _UNSET means omit a field, while None can explicitly clear a nullable project field.

JsonValue is Any, not a validated response model. HTTP helpers return decoded JSON, or None for an empty response; use the response-schema sections below for documented fields. request and put_upload_target return httpx.Response; close returns None, and resolve_url returns a URL string.

Catch SubftMaintenanceError before SubftApiError; inspect status_code, payload, response, mode and maintenance_until. SubftTransportError retains request_error. SubftError covers client-originated failures; local argument validation can also raise ValueError. A 409 requires a fresh read/plan, not replaying stale guards. Keep technical messages in internal logs and map codes to translated text in public interfaces. Do not blindly retry a charge-bearing commit after an ambiguous transport failure: reconcile the accepted operation first.

HTTP errors use {"detail":{"code":"…","params":{…}}}. Read SubftApiError.code and SubftApiError.params; raw server prose is diagnostic only. Credit amounts, maintenance metadata and subtitle line numbers are parameters. For example, an unreadable subtitle can return {"detail":{"code":"invalid_subtitles","params":{"line":2}}}. Unknown codes require a translated generic fallback in public interfaces.

SubftClient

Create one client and close it with a context manager. Optional extras are imported explicitly; the base package does not load FFmpeg or WebSocket dependencies.

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

Client methods

Every public method is listed once below. Returns and shared exception behavior follow the contract above; endpoint-specific conflicts preserve the server status and payload.

abandon_content_preparation

Abandon one still-actionable source preparation, preserving the operation’s other sources.

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

abort_operation

Abort accepted server work using the operation’s allowed action; this differs from detaching a watcher.

abort_operation(operation_id: str) -> JsonValue

add_project_media

Register one locally inspected inventory item and its physical sources.

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

add_project_media_bulk

Register a complete batch of inspected media records.

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

apply_project_directory_sync

Apply a reviewed directory snapshot with current observation guards; a stale response requires another preview.

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

archive_project

Archive a settled project as read-only. Repeating the request preserves its archive date.

archive_project(project_id: str) -> JsonValue

restore_project

Restore an archived project so it can be changed again. Restoring an active project changes nothing.

restore_project(project_id: str) -> JsonValue

delete_project

Permanently delete an archived project and its workspace, results and submitted inputs. Operation and credit records remain. The trimmed confirmation name must match exactly, including case.

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

attach_project_media_sidecars

Attach reviewed subtitle sidecars to a media item using its check baseline.

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

begin_media_asset_checks

Read the current asset-check baseline before reconciling physical observations.

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

begin_project_directory_checks

Read asset-check baselines for a complete directory preview/apply cycle.

begin_project_directory_checks(project_id: str) -> JsonValue

clone_media_asset

Create an editable copy or duplicate using the current snapshot guards.

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

close

Close the HTTP connection pool; the context manager calls this automatically.

close() -> None

compare_media_asset_exports

Compare selected export candidates without extracting or writing local files.

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

complete_media_asset_checks

Complete guarded physical checks and reconcile newly observed sources.

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

complete_upload

Finalize a direct upload for its current content, upload and preparation attempt.

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

create_blank_media_asset

Create a blank editable subtitle asset using the endpoint’s guarded request.

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

create_project

Create an empty file or directory project; local inventory is submitted separately.

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

create_project_operation

Commit the estimated, guarded source selections and charge the accepted estimate.

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

create_project_operation_plan

Request a source/stage plan without charging or uploading data.

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

create_upload_target

Request or refresh a direct-upload target after the preparation enters hashing/uploading.

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

estimate_project_operation_plan

Estimate the current plan using real requested metrics; inspect can_commit before asking for approval.

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

export_media_asset

Capture a saved asset’s subtitle export with current snapshot/version and metadata guards.

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

export_project_operation_artifact

Export a specific successful immutable stage; downloading does not create an editable or physical asset.

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

export_project_operation_result

Export the final successful stage for one operation source item.

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

export_project_operation_result_names

Final file names of the selected results written together to one ZIP or directory. Names that would clash get the source's asset number or a running number (clip.en.3.srt).

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

generate_api_token

Generate the single active API token, replacing the previous token; callers own confirmation and secret handling.

generate_api_token() -> JsonValue

get_api_token_status

Read token status without recovering an existing secret.

get_api_token_status() -> JsonValue

get_asset_document

Read a consistent saved subtitle document and its current version.

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

get_maintenance_status

Read gateway maintenance state without authentication.

get_maintenance_status() -> JsonValue

get_media_asset

Read one current asset and its binding/snapshot metadata.

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

get_operation

Read canonical global operation state; reconcile this after events and reconnects.

get_operation(operation_id: str) -> JsonValue

get_project

Read a project and its current inventory overview.

get_project(project_id: str) -> JsonValue

get_project_media

Read one current project-media record.

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

get_project_operation

Read an operation through its owning project route.

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

get_session

Read the authenticated session resource.

get_session() -> JsonValue

get_workflow_preferences

Read account workflow and export defaults; explicit choices may override them.

get_workflow_preferences() -> JsonValue

hide_media_asset

Hide an asset using current guards while retaining its producing history.

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

import_project

Create a project from a complete supplied file/inventory setup.

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

list_media_assets

List saved assets belonging to one project-media item.

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

list_operations

List global operations with explicit pagination.

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

list_project_media

List project media with filters and pagination; inspect total and status_counts.

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

list_project_operation_results

List successful saved stage artifacts, including useful results from partially failed work.

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

list_project_operations

List operations owned by a project, optionally scoped to one media item.

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

list_archived_projects

List archived projects with mode, search, sort and pagination. Newest archive date comes first by default.

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

list_projects

List active projects with mode, search, sort and pagination.

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

materialize_asset

Register locally extracted physical subtitle text using current observation guards.

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

preview_project_directory_sync

Compare a complete local snapshot with current inventory before applying changes.

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

preview_project_sidecars

Find sidecar matches and ambiguities before attaching them.

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

put_upload_target

Upload directly using backend-issued method and headers; the SubFT token is omitted.

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

register_verified_asset_outputs

Register locally verified physical outputs using their frozen capture; downloading alone does not register them.

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

remove_project_media

Remove a media item from active inventory through the project route.

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

replace_project_media

Reconcile a changed local media file using its fresh inventory evidence.

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

report_content_progress

Report attempt-scoped client progress with the current progress contract and increasing revision.

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

request

Send an HTTP request and return the raw response after shared error handling.

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

request_json

Send an HTTP request and decode JSON; empty responses return None.

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

resolve_url

Resolve a backend relative URL against the client gateway.

resolve_url(url: str) -> str

restore_project_media

Restore an archived item. A video or audio item needs media, its file's fresh inventory evidence: unchanged streams keep their assets. A subtitle item needs none.

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

retry_content_preparation

Start a fresh attempt for eligible preparation, guarded by the previous attempt ID; this starts no new operation.

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

revoke_api_token

Revoke the active server token; removing a locally stored token does not do this.

revoke_api_token() -> JsonValue

save_media_asset_document

Save editable cues with snapshot/version guards; conflicts require a fresh document read.

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

scan_project_directory

Ask the backend to classify a supplied local snapshot; the server cannot scan the caller’s disk.

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

start_content_preparation

Start an allowed preparation attempt with a new UUID before hashing and upload.

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

update_content_preparation

Advance preparation, renew its heartbeat or report an awaiting_retry failure with the same attempt token.

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

update_media_asset

Update allowed asset metadata, leaving subtitle content unchanged.

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

update_project

Update supplied project fields. Omitted _UNSET fields differ from explicitly cleared None values.

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

verify_auth

Verify the effective credential and read its account identity.

verify_auth() -> JsonValue

Root exports

Import from subft_client. Local functions need the local extra and the selected system tools. Inspect returned failures before updating backend inventory. Realtime needs its extra and performs no canonical HTTP reconciliation.

JsonArray

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

JsonArray = list[Any]

JsonObject

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

JsonObject = dict[str, Any]

JsonValue

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

JsonValue = Any

SubftApiError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

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

SubftClient

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

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

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

SubftMaintenanceError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

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

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

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

__version__

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

__version__ = '0.1.0'

Local helpers and records

Import from subft_client.local. Local functions need the local extra and the selected system tools. Inspect returned failures before updating backend inventory. Realtime needs its extra and performs no canonical HTTP reconciliation.

AUDIO_EXTENSIONS

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

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

DEFAULT_HASH_CHUNK_SIZE

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

DEFAULT_HASH_CHUNK_SIZE = 4 * 1024 * 1024

DirectorySnapshotFile

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

DirectorySnapshotResult

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

ExtractedFile

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

FfmpegTools

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

ffmpeg_available: bool

ffprobe_available: bool

available: bool

to_api_dict() -> JsonObject

FfmpegUnavailableError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

FileFingerprint

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

GRAPHICAL_SUBTITLE_EXTENSIONS

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

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

InventoryResult

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

LANGUAGE_SAMPLE_BYTES

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

LANGUAGE_SAMPLE_BYTES = 64 * 1024

LocalFailure

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

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

to_api_dict() -> JsonObject

LocalFile

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

LocalFileChangedError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

LocalHashError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

LocalPathError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

LocalProgress

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

percent: float

to_api_dict() -> JsonObject

LocalScanError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

MediaInventoryItem

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

MediaEmbeddingError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

MediaExtractionError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

MediaProbe

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

MediaProbeError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

MuxedMedia

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

ProbeStream

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

SUBTITLE_EXTENSIONS

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

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

ScanResult

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

to_api_dict() -> JsonObject

SubftLocalError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

SubtitleMuxInput

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

VIDEO_EXTENSIONS

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

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

VOBSUB_EXTENSIONS

Public constant or type alias. The value below comes from source; identifiers and units retain their technical meaning.

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

build_directory_snapshot

Build complete files, fingerprints and bounded language samples for directory reconciliation.

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

build_inventory

Inspect scanned media into API-ready inventory; any recorded failure must be handled before submission.

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

check_ffmpeg_tools

Return tool availability without requiring all tools to exist.

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

count_pgs_images

Count graphical subtitle images from the real source; paired VobSub input requires both files.

count_pgs_images(content: bytes) -> int

count_vobsub_images

Count graphical subtitle images from the real source; paired VobSub input requires both files.

count_vobsub_images(text: str) -> int

embed_subtitle_tracks

Write a caller-owned muxed output, preserving unrelated streams; installation and registration are separate.

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

extract_audio_stream

Extract one selected audio stream as MP3 without changing the original.

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

extract_subtitle_stream

Extract text as SRT or copy graphical subtitles to Matroska; the caller owns cleanup.

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

fingerprint_media_file

Compute the compatible full or partial media fingerprint and reject source mutation.

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

hash_file_sha256

Stream all bytes into a SHA-256 FileFingerprint; read its hash field for API requests.

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

hash_text_subtitle

Hash subtitle text after newline and surrounding-whitespace normalization.

hash_text_subtitle(source: LocalSource) -> FileFingerprint

inspect_media

Inspect one supported file and return actual probe evidence and source observations.

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

pgs_duration_seconds

Derive subtitle duration in seconds from actual cue/image timing.

pgs_duration_seconds(content: bytes) -> float

probe_media

Read FFprobe duration, streams and container evidence without modifying the file.

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

read_subtitle_language_sample

Read a bounded source-text sample for language classification.

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

require_ffmpeg_tools

Require the selected tools and raise FfmpegUnavailableError if prerequisites are absent.

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

scan_directory

Scan deterministically, skip symlinks and record per-path failures.

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

subtitle_duration_seconds

Derive subtitle duration in seconds from actual cue/image timing.

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

vobsub_duration_seconds

Derive subtitle duration in seconds from actual cue/image timing.

vobsub_duration_seconds(text: str) -> float

vobsub_pair_hash

Combine matching IDX/SUB fingerprints in the documented deterministic order.

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

visible_subtitle_character_count

Count visible subtitle characters using the billing normalization rules.

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

Realtime helpers and records

Import from subft_client.realtime. Local functions need the local extra and the selected system tools. Inspect returned failures before updating backend inventory. Realtime needs its extra and performs no canonical HTTP reconciliation.

OperationEvent

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

RealtimeConnectionState

Public client or immutable record. Fields are returned local/realtime evidence, not an instruction to launch work. Public methods below expose its recorded values.

RealtimeDependencyError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

RealtimeProtocolError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

RealtimeSubscriptionError

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

Realtime subscription rejections use event: "failed" with a {code, params} descriptor in payload.error. RealtimeSubscriptionError exposes code and params; diagnostic text is not a presentation contract.

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

SubftRealtimeError

Public exception. Catch the specific type when recovery differs; the base exception covers its subclasses. Optional constructor fields preserve HTTP status, payload or transport evidence as annotated.

watch_operation_events

Yield operation events and connection changes with reconnect/backoff; canonical HTTP reconciliation remains the caller’s responsibility.

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]

Request and response schemas

The tables reproduce declared fields, including inherited fields. Required uses True/False. A dash means no default declaration; Field(...) records actual Pydantic defaults and constraints. Nullable fields can still be required. Named types describe nested records; dict[str, Any] is deliberately open, not an invented exhaustive schema. Upload targets additionally return upload_id, operation_id, media_id, content_id, upload_url, method, headers, expires_at and optional sidecar; preserve their identity, expiry and method. The worked recipe validates the fields it consumes.

AssetSelection

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

CapturedExport

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

CommittedSource

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

Value under source_ref_map keyed as project-media-ID:asset-ID. Use its runtime media_id/content_id for preparation and upload; plans identify sources with source_ref.

ContentFlow

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

ContentPreparation

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

Canonical preparation has states awaiting_client, preparing, hashing, uploading, awaiting_retry, ready, abandoned and not_required. attempt_id and lease/upload expiry may be null. allowed_actions contains only currently eligible start_preparation, retry_preparation or abandon_source. Retry requires the previous attempt_id and a fresh UUID; ready and terminal work must not be resupplied blindly.

ContentPreparationResponse

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

This is the nested preparation snapshot, not operation execution_state. The preparation endpoint wraps it with operation_id, content_id and progress. Its state is preparing after an accepted start/retry; verify the echoed attempt_id. media_id comes from the route/source_ref_map, not this response wrapper.

ContentProgress

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

CreditEstimate

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

CreditEstimateContent

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.

EffectiveMetadata

Source-derived contract. Keep required fields and guards when adapting the recipe; nullable values are distinct from missing required fields.