PRINTFILM: An Open Source Pipeline for AI Short Videos and Episodic Comics

The gap PRINTFILM fills between a prompt box and a finished cut

Most text-to-video tools stop at a clip. PRINTFILM is built around the steps after that: a theme becomes a storyboard, the storyboard becomes images, images become video segments, narration is generated, and FFmpeg assembles the result. The README describes the flow as "theme → storyboard → image → video → voice → final cut" and calls the project an open-source AI studio for short videos and episodic comics.

The audience is narrower than the headline suggests. It targets creators and operators who run their own infrastructure: the deployment section says Docker only runs Postgres and Redis, while the application itself runs as local or server processes. Someone who wants a browser tab and a credit card is not the intended user.

Two product lines sit on the same pipeline. AI comics (漫剧) go outline, assets, per-episode storyboards, then a React Flow canvas, with an emphasis on keeping characters and scenes consistent. AI short videos, described as popular-science videos, pick a template, take a script, apply a style, then run the storyboard pipeline and compose with FFmpeg. The README lists 20+ built-in templates and two output modes: full, which includes video, and image_text, which pairs still images with narration.

How the pipeline is wired: FastAPI, an in-process task runtime, and two upstream providers

The architecture diagram in the README shows browsers on ports 5173 (user app) and 5174 (admin) talking to a FastAPI process on 8000 over /api and /static. Behind that process sit three components that start with it: a scheduler, an executor and a poller. There is no separate worker fleet or message broker in the documented setup, which keeps deployment small but ties task throughput to the API process.

State lives in PostgreSQL on 15432 and Redis on 16379. The README ties Redis to password recovery and caching, and notes that the password recovery flow is unavailable when Redis is not configured. Generated media lands in local static/generated, with Alibaba Cloud OSS as an optional destination.

Model access is deliberately split. Text goes through any OpenAI-compatible endpoint, with Kimi and DeepSeek named as examples. Image and video generation go through Volcengine Ark, using Seedream for images and Seedance for video. Narration prefers Doubao openspeech and falls back to edge-tts when VOLC_TTS_API_KEY is absent. That split is the single most consequential design decision in the project: it means two billing relationships and two failure surfaces before you generate anything.

Installing PRINTFILM and running your first generation

The README's quick start assumes you clone the repository, then bring up middleware before the application. Copy the example environment file first; the repository does not ship secrets, and the README asks you to replace POSTGRES_PASSWORD with your own strong password.

git clone https://github.com/yi1108/printfilm.git
cd printfilm
cp deploy/.env.prod.example deploy/.env.prod
docker compose -f deploy/docker-compose.yml --env-file deploy/.env.prod up -d

That compose file is documented as running only two images, postgres:16-alpine and redis:7-alpine, exposed on ports 15432 and 16379. Then set up the backend in its own virtual environment.

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000

Before starting uvicorn, edit backend/.env so DATABASE_URL carries the same password you put in deploy/.env.prod, and fill in the model keys. The README's example block uses OPENAI_API_KEY, OPENAI_BASE_URL, MODEL_LLM, ARK_API_KEY, MODEL_IMAGE, MODEL_VIDEO and MODEL_AUDIO. If you want to click through the interface without spending on model calls, set ARK_MOCK=true, which the README describes as serving local mock assets.

curl http://127.0.0.1:8000/api/health

The health endpoint returns JSON where ok indicates the task runtime is healthy, models lists the current LLM, image, video and audio models, and ark_mock reports whether mocking is on. That response is the fastest way to confirm the two upstream providers are wired correctly.

Finally, start the two front ends in separate terminals. The user app defaults to http://localhost:5173 and the admin panel to http://localhost:5174, which is documented as already proxying /api to port 8000.

cd frontend && npm install && npm run dev
cd admin && npm install && npm run dev

To get an account, register at /auth with an email and password. The README is explicit that there is no built-in demo account. Administrator access is granted by registering first, then adding your email to ADMIN_BOOTSTRAP_EMAILS in backend/.env and restarting the backend; the README stresses that this promotes an existing user and does not create one.

Where PRINTFILM will frustrate you: environment coupling and thin failure handling

The most common first-run failure is not a code bug. It is the database password. The README states that the password in deploy/.env.prod must match both DATABASE_URL and DATABASE_URL_SYNC in backend/.env. Two files, three places, and the health endpoint will not diagnose a mismatch for you.

Chinese subtitles are a second trap. The environment requirements list fonts-wqy-zenhei for Linux, warning that without a suitable font, burned-in Chinese text can render as boxes. FFmpeg and ffprobe must also be on PATH, and the README suggests reserving several gigabytes of disk because storyboard images, video segments and final cuts accumulate.

Long video jobs are governed by ARK_VIDEO_POLL_TIMEOUT, documented as defaulting to 900 seconds. The troubleshooting table lists timeouts as a symptom with that variable as the remedy, which tells you the pipeline is synchronous enough that a slow upstream can stall a job. The same table points at /api/health's task_runtime when generation sits in a queue, and attributes 401 errors to an invalid or expired key or a wrong channel base URL.

There is a production constraint worth reading before you plan hosting. The README warns against publishing the SPA to OSS as the only delivery method, and says production builds must set VITE_API_BASE to an empty string so requests go same-origin through nginx. It also notes that payment gateway callbacks must not contain /api/ because some WAFs block that path, so the documented workaround is /epay/notify reverse-proxied to /api/billing/epay/notify. If you deploy the obvious way, you will hit one of these.

PRINTFILM compared with assembling separate generation tools

The realistic alternative is not another studio application. It is stitching together a text model, an image model, a video model and FFmpeg yourself, or using a hosted generator that hides all of it. Those differ from PRINTFILM in where the state lives.

With separate tools, the storyboard is a spreadsheet, character consistency is a naming convention you enforce by hand, and the final cut is a shell script. PRINTFILM keeps those in PostgreSQL behind a FastAPI service, exposes an asset library for characters, scenes, props and voices, and gives the storyboard workbench per-shot actions: redraw a single image, regenerate a single shot's video, or edit and continue. That is the concrete difference. It is a persistence and review layer, not a better model.

Against a hosted generator, the trade runs the other way. You get the pipeline and the data, but you also get the operational surface: Postgres, Redis, FFmpeg, font packages, two upstream providers, and a task runtime that lives inside the API process. The README recommends running uvicorn with a single worker in production, which caps how much parallel generation one instance can absorb.

There is also an API-only path for teams that want the pipeline without the UI. The README documents an open API under /api/v1 for image and video generation, authenticated with either a Bearer token or an X-Api-Key header, with keys managed in the personal center.

Licence, maintenance and what upgrading actually costs

PRINTFILM is MIT licensed, and the LICENSE file sits at the repository root alongside README.md, backend/, frontend/, admin/, deploy/ and docs/. MIT is permissive, so the practical question is not whether you may use it but what you inherit: the README names specific model endpoints and providers, and your own agreements with those providers are separate from the code licence. Nothing here is legal advice, and if you enable the billing and wallet features, the README points to docs/ for billing and product rules that you should read directly.

The repository is not archived, and the last push was on 2026-09-10. The README header states version 0.2.0 with the same update date, and no releases were retrieved, so versioning appears to track the repository rather than tagged artifacts. That matters for upgrades: there is no documented release channel, no migration guide and no rollback procedure in the README. If you deploy this, pin the commit you validated rather than tracking main.

Upgrade cost concentrates in three places: backend/requirements.txt, the two front-end package manifests, and the .env files, since the README treats .env.example as the authority for variable names and says .env can serve as a first-time import into the admin model routing screen. After pulling, re-check /api/health, because a changed model routing default is exactly the kind of thing that response surfaces.

Editorial conclusion

Adopt PRINTFILM if you want a self-hosted, MIT licensed studio that keeps the storyboard, asset library and final FFmpeg cut in one place, and you already hold keys for an OpenAI-compatible text model and Volcengine Ark for image and video. Do not adopt it if you expect a hosted service, a built-in demo account or a single API key to cover everything: the README states the repository contains no keys and no demo account, and image and video generation run through Ark. Before committing, verify that ffmpeg and ffprobe resolve on PATH, that the Postgres password in deploy/.env.prod matches DATABASE_URL and DATABASE_URL_SYNC in backend/.env, and that /api/health reports the models you configured.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. yi1108/printfilm on GitHub