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

The render service is open source (ultrafast serve) and speaks the same API as ultrafast Cloud. Point the client at it:

export ULTRAFAST_BASE_URL=http://localhost:8080
export ULTRAFAST_API_KEY=...   # one of the server's ULTRAFAST_API_KEYS

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

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://, 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: .status, .wait(), .save(path), .cancel()
uf.job(id), uf.jobs.list() jobs
uf.upload(path) an Asset: .id, .uri, .sha256
uf.me() caller, auth, webhook_secret

render options: inline=True (the MP4 comes back in the response, up to 32 MiB), uri="s3://bucket/key" (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

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, 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.0

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.0
File Size Uploaded Provenance Actions
ultrafastmov-0.1.0.tar.gz 65.6 kB Without provenance Details for ultrafastmov-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 113.6 kB

Release files / ultrafastmov-0.1.0.tar.gz

Download URL ultrafastmov-0.1.0.tar.gz
Size 65.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1c604db98194005188e27a7bc9b056fd4dd326ed98e26d243f695818b42a94ac
BLAKE2b-256 checksum
How to use checksums
6fc14ed9fe62f47f15f4daf2f2e354f34502f399afd5e39344d70c97dd5c7c81
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.0-py3-none-any.whl

Download URL ultrafastmov-0.1.0-py3-none-any.whl
Size 48.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c25862e399877717572eb5a9198eefee9cc951f8ca3a137c43b517cee3ccbe7b
BLAKE2b-256 checksum
How to use checksums
ede8418ad096a6fe3ae1e13253aad5555a3dd33b65860389e287f5c262950f59
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.0

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