Skip to main content

ultrafastmov

The Python client for ultrafast, the GPU video engine. A video is a JSON document; this package sends it to an ultrafast render service and gives you back frames, contact sheets, reviews, estimates and MP4s.

pip install ultrafastmov
from ultrafastmov import Ultrafast

uf = Ultrafast()  # ULTRAFAST_API_KEY

doc = uf.load("film.json")
print(uf.estimate(doc))      # $0.004, 8 s of 1080p
for issue in uf.review(doc):
    print(issue.kind, issue.node, issue.message)
uf.render(doc).save("film.mp4")

Python 3.9 or later. No dependencies.

Your own server

ultrafast serve is the open-source render service for one machine with a GPU. Point the client at it:

export ULTRAFAST_BASE_URL=http://localhost:8080
export ULTRAFAST_API_KEY=...   # the server's key (it prints one at first start)

or Ultrafast(base_url="http://localhost:8080", api_key="..."). Without ULTRAFAST_BASE_URL the client talks to https://api.ultrafast.mov.

Everything here works against it except what only ultrafast Cloud has: jobs and webhooks, uri= (your own bucket) and gs://, s3:// or r2:// inputs. Those raise CloudOnly (e.feature says which).

Local files

Documents name footage, images, fonts and audio by path ("src": "footage/a.mp4", relative to the document). Before each call the client uploads every local file the document reads, once per client, and sends a copy that points at the uploads (asset://...). Your document is not changed. Image sequences ("frames/f_{frame:06}.png") go up as one zip. Family names ("font": "Inter") and references (asset://, https://, and on Cloud gs://, s3://, r2://) are sent as they are.

asset = uf.upload("interview.mp4")     # or upload yourself
print(asset.uri)                       # asset://7KqH2...

What it does

Call Returns
uf.load(path), uf.new("vertical") a Document (a dict)
uf.check(doc) .ok and .issues (node, severity, message)
uf.frame(doc, at=2.5) PNG bytes with .save(path) (format="jpeg" too)
uf.sheet(doc, count=9) a labeled contact sheet, the same way
uf.review(doc, safe="social") issues with kind, node, from_, to, message
uf.estimate(doc) .usd, .seconds, .minutes, ...; prints as $0.004, 8 s of 1080p
uf.render(doc) a Render: .url, .sha256, .bytes, .duration, .save(path)
uf.render(doc, webhook=url), uf.submit(doc) a Job (Cloud): .status, .wait(), .save(path), .cancel()
uf.job(id), uf.jobs.list() jobs (Cloud)
uf.upload(path) an Asset: .id, .uri, .sha256
uf.me() caller, auth (and webhook_secret on Cloud)

render options: inline=True (the MP4 comes back in the response, up to 32 MiB), uri="s3://bucket/key" (Cloud: create it in your bucket; also r2://, gs://), codec="hevc", bitrate, audio=False, range=[from, to], name, deadline, and attempt=True (or your own render id), which sends an attempt id and retries the request safely on 429, 503 and dropped connections. save streams to disk and checks the receipt's sha256.

Reads (frame, sheet, check, review, estimate, GETs, uploads) are retried twice on 429 and 503 when the server says so.

Jobs and webhooks (Cloud)

job = uf.render(doc, webhook="https://example.com/rendered")
print(job.id, job.status)              # job_01J... queued
job.save("film.mp4")                   # or wait for the webhook
from ultrafastmov import webhooks

secret = uf.me()["webhook_secret"]
job = webhooks.verify(raw_body, headers["Ultrafast-Signature"], secret)

verify checks the HMAC-SHA256 signature over the raw body (constant time) and refuses deliveries whose sent_at is more than 5 minutes off.

Errors

Every API error raises an UltrafastError subclass carrying status, code, message, retry and the full body; extra fields read as attributes (e.location, e.node, e.limit):

BadRequest, InvalidDocument (.issues), Unauthorized, PaymentRequired, Forbidden, NotFound, Conflict, TooLarge, InputUnavailable, Busy (RateLimited), ServerError, Unavailable, DeadlineExceeded, CloudOnly (.feature), and APIConnectionError when no answer came back.

Types

ultrafastmov.types has TypedDicts generated from the document schema: Document, Format, Node, Timing, and one <Op>Params per op (TextParams, VideoParams, ...). Regenerate with python3 tools/gen_types.py.

Development

python3 -m unittest discover -s tests -t .

The tests run against an in-process fake of the service (tests/fake_server.py). tests/test_live.py runs the same calls against a real server (tiny documents) when ULTRAFAST_LIVE=1 and ULTRAFAST_BASE_URL/ULTRAFAST_API_KEY are set.

Licensed under Apache-2.0 OR MIT.

Metadata

Release files for ultrafastmov 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ultrafastmov 0.1.1
File Size Uploaded Provenance Actions
ultrafastmov-0.1.1.tar.gz 66.4 kB Without provenance Details for ultrafastmov-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ultrafastmov 0.1.1
File Interpreter ABI Platform Actions
ultrafastmov-0.1.1-py3-none-any.whl Python 3 none any Details for ultrafastmov-0.1.1-py3-none-any.whl

Total release size: 114.7 kB

Release files / ultrafastmov-0.1.1.tar.gz

Download URL ultrafastmov-0.1.1.tar.gz
Size 66.4 kB
Tags Source
SHA-256 checksum
How to use checksums
0426bbc386d82c8aa01c57c315e3f6aff7266914eecd6779ea5c7d1d8f8e4250
BLAKE2b-256 checksum
How to use checksums
f14ad930bb18512396bc43229f031a603eeaa1e3fb9047a5542a322a03cf3d44
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Release files / ultrafastmov-0.1.1-py3-none-any.whl

Download URL ultrafastmov-0.1.1-py3-none-any.whl
Size 48.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7d4324bb56ddbab0d97bf40bb9a28082195cd70d0e1849ebd7ba5ef53d861a8e
BLAKE2b-256 checksum
How to use checksums
4a663b483eb4fde03b7efc90d35f6b9c78c536d68a7ee8a539a6f5b7e69cbff6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Security for ultrafastmov 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page