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 your own ultrafast serve and gives you back frames, contact sheets, reviews, estimates and videos.

ultrafast serve           # on the machine with the GPU; prints its API key when it starts
pip install ultrafastmov
from ultrafastmov import Ultrafast

uf = Ultrafast()  # the server on this machine; ULTRAFAST_API_KEY

doc = uf.load("film.json")
print(uf.estimate(doc))      # 8 s of 1080p, 2.1 GPU seconds
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.

The server

ultrafast serve is the open-source render service for one machine with a GPU: install ultrafast with cargo install ultrafast, brew install ultrafastmov/tap/ultrafast or the ghcr.io/ultrafastmov/ultrafast image (self-hosting). The client talks to http://127.0.0.1:8080 unless told otherwise:

export ULTRAFAST_BASE_URL=http://gpu-box:8080   # a server on another machine
export ULTRAFAST_API_KEY=...                    # the server's key

or Ultrafast(base_url="http://gpu-box:8080", api_key="...").

Jobs and webhooks, uri= (your own bucket) and gs://, s3:// or r2:// inputs are for ultrafast Cloud, which isn't open yet. The server answers them with 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://) 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) .seconds, .minutes, .gpu_seconds, ... (and .usd where the server sets a price); prints as 8 s of 1080p, 2.1 GPU seconds
uf.render(doc) a Render: .url, .sha256, .bytes, .duration, .save(path)
uf.upload(path) an Asset: .id, .uri, .sha256
uf.me() caller, auth

render options: inline=True (the file comes back in the response, up to 32 MiB), 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; given a folder it names the file for its format.

The export settings are ultrafast export's, so one document gives every deliverable:

uf.render(doc, quality="draft", size="720p", inline=True)   # a quick preview
uf.render(doc, size="4k", quality="high")                   # rendered at 4K, not scaled up
uf.render(doc, codec="prores", alpha=True, name="overlay.mov")  # ProRes 4444 with alpha
uf.render(doc, format="webm", alpha=True)                   # VP9 with alpha, for the web
uf.render(doc, format="gif", fps=15, size="480p", loops=0)  # a GIF that plays once
uf.render(doc, format="png", alpha=True).save("frames/")    # a zip of PNG frames and audio.wav
uf.render(doc, format="wav")                                # the sound alone
print(uf.estimate(doc, size="4k", quality="master"))        # counted at the output size

format (mp4, mov, mkv, webm, gif, png, exr, wav, mp3, m4a, flac, opus), codec (h264, hevc, av1, vp9, prores), quality (draft, standard, high, master), size ("720p", "1080p", "4k", "WxH" or (w, h)) or scale, fps, crf or bitrate ("8M"), prores_profile, alpha, audio_codec, audio_bitrate, loops.

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

Jobs and webhooks (ultrafast Cloud, not open yet)

uf.render(doc, webhook=url) and uf.submit(doc) return a Job (.status, .wait(), .save(path), .cancel()); uf.job(id) and uf.jobs.list() read them; uri="s3://bucket/key" (also r2://, gs://) writes the render to your bucket. ultrafast serve answers these with CloudOnly.

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.2

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.2
File Size Uploaded Provenance Actions
ultrafastmov-0.1.2.tar.gz 68.2 kB With provenance Details for ultrafastmov-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 118.8 kB

Release files / ultrafastmov-0.1.2.tar.gz

Download URL ultrafastmov-0.1.2.tar.gz
Size 68.2 kB
Tags Source
SHA-256 checksum
How to use checksums
84ef02a35cbc2313c52c26f73acd5f817cf1bca62f022ef182a6b5b95b6f2758
BLAKE2b-256 checksum
How to use checksums
d89d2a9caee6e6f02844430d00c1556ebbac8f484aaa31a32010e621fefd1a24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

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

Download URL ultrafastmov-0.1.2-py3-none-any.whl
Size 50.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce1d357d313036fddf319753457feef1b9400129bc0b7606080b23fac58aa551
BLAKE2b-256 checksum
How to use checksums
a7e365137b10c3344b069e93d6f79099148f1b7c13edda2bbadbed9e2e81504b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for ultrafastmov 0.1.2

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ultrafastmov-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

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