Developer

Python client library

Compose complete SubFT workflows with the HTTP client, realtime events, and local helpers.

  • HTTP API
  • Realtime
  • Local extras
Quick start
import os
from subft_client import SubftClient

with SubftClient(
    "https://api.subft.com",
    token=os.environ["SUBFT_API_TOKEN"],
    timeout=30.0,
) as client:
    projects = client.list_projects()
Installation and extras
pip install subft-client
pip install "subft-client[local]"
pip install "subft-client[realtime]"
pip install "subft-client[local,realtime]"

Workflow

End-to-end project workflow

Create a client with an explicit base URL and token, then reconcile local media and remote results.

  1. Create a clientUse a context manager or close the client explicitly.
  2. Create and syncCreate a project, scan local media, preview changes, and apply the sync.
  3. Plan the operationCreate and optionally estimate a plan before starting paid work.
  4. Upload safelySend bytes only to the exact direct-upload target returned by the service.
  5. Reconcile progressCombine realtime events with authoritative HTTP reads until terminal state.
  6. Fetch resultsList result tracks and write local output with the optional helpers.
Directory project and operation lifecycle
import os
from subft_client import SubftClient

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

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

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

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

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

Reference

SubftClient method reference

Every public method is listed by workflow area. Method names and signatures are stable API identifiers.

Lifecycle, requests, and upload targets

Client lifetime, lower-level requests, URL resolution, and direct upload transfer.

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

Maintenance and authentication

Service health, sessions, token status, token generation, and revocation.

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

Projects

List, create, import, update, inspect, and archive projects.

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

Project media

Manage project media records and their local artifact metadata.

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

Directory and stream synchronization

Scan directories and reconcile sidecars, streams, and language overrides.

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

Plans, operations, uploads, and control

Plan work, create operations, upload sources, report progress, and control execution.

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

Subtitle stream caches

Inspect, write, normalize, import, and stage subtitle stream caches.

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

Tracks, cues, and exports

Manage result tracks, cues, editing data, export plans, and downloaded output.

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

HTTP error hierarchy

Catch the most specific subclass when recovery differs, or SubftError for all client-originated failures.

  • SubftError
  • SubftApiError
  • SubftMaintenanceError
  • SubftTransportError
All top-level package exports
  • JsonArray
  • JsonObject
  • JsonValue
  • SubftApiError
  • SubftClient
  • SubftError
  • SubftMaintenanceError
  • SubftTransportError
  • __version__

Direct-upload security

Treat upload targets as short-lived capabilities. Pass the returned URL, method, and headers unchanged to put_upload_target(); it omits the SubFT token. Do not follow redirects or reuse expired targets.

Direct upload without API credentials
target = client.create_upload_target(
    operation_id,
    media_id,
    content_id=content_id,
    content_hash=sha256,
    filename=source.name,
)
client.put_upload_target(
    target["upload_url"],
    method=target["method"],
    headers=target["headers"],
    content=source.read_bytes(),
)
client.complete_upload(
    operation_id,
    media_id,
    content_id=content_id,
    upload_id=target["upload_id"],
    content_hash=sha256,
)

Realtime reconciliation

Realtime events are hints for responsiveness. Re-read authoritative resources after reconnects, sequence gaps, and terminal events.

Public realtime exports
  • OperationEvent
  • RealtimeConnectionState
  • RealtimeDependencyError
  • RealtimeProtocolError
  • RealtimeSubscriptionError
  • SubftRealtimeError
  • watch_operation_events
Use events to trigger authoritative reads
from subft_client.realtime import watch_operation_events

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

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

subft_client.local

Install the local extra for media scanning, FFmpeg adapters, project bindings, local operation plans, and output application.

Public local exports
  • AUDIO_EXTENSIONS
  • DEFAULT_HASH_CHUNK_SIZE
  • DirectorySnapshotFile
  • DirectorySnapshotResult
  • ExtractedFile
  • FfmpegTools
  • FfmpegUnavailableError
  • FileFingerprint
  • InventoryResult
  • LANGUAGE_SAMPLE_BYTES
  • LocalFailure
  • LocalFile
  • LocalFileChangedError
  • LocalHashError
  • LocalPathError
  • LocalProgress
  • LocalScanError
  • MediaInventoryItem
  • MediaEmbeddingError
  • MediaExtractionError
  • MediaProbe
  • MediaProbeError
  • MuxedMedia
  • ProbeStream
  • SUBTITLE_EXTENSIONS
  • ScanResult
  • SubftLocalError
  • SubtitleMuxInput
  • VIDEO_EXTENSIONS
  • VOBSUB_EXTENSIONS
  • build_directory_snapshot
  • build_inventory
  • check_ffmpeg_tools
  • embed_subtitle_tracks
  • extract_audio_stream
  • extract_subtitle_stream
  • fingerprint_media_file
  • hash_file_sha256
  • hash_text_subtitle
  • inspect_media
  • probe_media
  • read_subtitle_language_sample
  • require_ffmpeg_tools
  • scan_directory
  • vobsub_pair_hash