Agnes Video Generator: a self-hosted text-to-video pipeline with narration and subtitles

The problem Agnes Video Generator addresses

Most text-to-video tools ask you to describe a single shot and return a clip of a few seconds. Turning that into something watchable, with a voice track, on-screen subtitles and several scenes stitched together, means moving files between a video model, a TTS service, a subtitle editor and a compositor. Agnes Video Generator collapses those steps into one job. The README describes the output as multi-scene videos with narration and subtitles, generated from a text idea, and lists text-to-video, image-to-video, keyframes animation, digital anchor and manuscript-to-video as the supported modes. The target user is someone who wants finished short-form video rather than raw generative clips, and who does not have a GPU workstation. The README states that all AI compute runs in the cloud and that a regular laptop is enough, which is the design constraint that shapes everything else in the repository.

How the pipeline is put together

The repository is a Python service with a web front end, not a library you import. server.py is the entry point, backed by FastAPI and uvicorn, with websockets in the dependency list for progress reporting to the browser. Work is organised around a working directory: docker-compose.yml mounts both /app/.working_dir and /app/.agnes_config from the container onto ./agnes_data/ on the host, and the comment in that file explains why, since the container's writable layer would otherwise discard generated videos, uploads and settings on recreation. Inside the working directory, tasks get their own folders holding final_video.mp4 and an uploads/ subdirectory.

Narration comes from edge_tts, which requirements.txt annotates as Azure Edge TTS with no API key required. Subtitles are handled with the srt package for parsing and generation, and composition runs through moviepy. ffmpeg is a hard dependency for muxing and audio processing, and the Dockerfile takes a deliberate shortcut: instead of installing ffmpeg via apt, it installs imageio-ffmpeg and symlinks the bundled static binary into /usr/local/bin/ffmpeg. That keeps the image on python:3.11-slim without the apt dependency tree. The same reasoning appears in requirements.txt, where imageio-ffmpeg is declared explicitly rather than left as an implicit transitive dependency of moviepy.

There is a second layer of configuration in the repository. A file named agnes-domain-config.md sits at the top level, and requirements.txt mentions pydantic-settings as the single source of truth for runtime configuration, with .env.example as a template. The API key, when one is used, is injected as AGNES_API_KEY, and docker-compose.yml shows it passed through from the host environment or a sibling .env file so it never lands in the image.

Installing it with Docker Compose and running a first job

The repository ships a docker-compose.yml, and the comments in that file give the intended flow. The image referenced there is ghcr.io/lcy362/agnes-video-generator/free-short-video:6.3.0, with a commented alternative on Docker Hub. Note that the GitHub releases list is at v6.5.0 while the Compose file pins 6.3.0, so if you want the newest build you will need to change the tag yourself.

Start the stack from the repository root. The -d flag runs it detached, and the panel becomes available on port 8765.

Where the design shows strain

The project depends on cloud inference. The README frames this as a feature, since no local GPU is needed, but it means your prompts and any uploaded images leave your machine. For a self-hosted tool, that is the central trade-off, and the repository does not offer a local model path. If your content cannot be sent to a third-party service, this is the wrong tool regardless of how the rest of the pipeline fits.

The dependency list also reveals the cost of multilingual support. Arabic narration pulls in mishkal for diacritics, plus arabic-reshaper and python-bidi, because requirements.txt notes that Pillow and moviepy's TextClip do not perform bidirectional reordering or letter joining. The comment is explicit that this reshaping has to happen before rendering or the letters will not join and the display order will be reversed. That is a real constraint, not a cosmetic one, and it tells you the rendering layer is a general-purpose text compositor being asked to do work it was not built for.

The release cadence is fast, with v6.4.7, v6.4.8 and v6.5.0 all dated within three days of each other, and the last push to master was on 2026-09-17. Frequent releases are not automatically a virtue here: the Compose file lagging two minor versions behind the latest tag suggests that pinned deployments can drift from the code the README describes.

How it differs from a hosted generator like Runway

Runway and similar services are hosted products: you upload or type, they render, you download, and the model, the queue and the pricing are theirs. Agnes Video Generator inverts the hosting question. The application, the web UI, the working directory and the ffmpeg binary all run on your machine, while the generative models stay remote. The practical difference is control over the surrounding pipeline. You choose where final_video.mp4 lands, you can mount the working directory onto a NAS, and you can script against a local HTTP service on port 8765 instead of an external API with its own rate limits and terms. The README's comparison table makes a similar split inside the project itself, contrasting this repository with FreeShortVideoStudio, a browser-only sibling that needs no install but whose features the README describes as under active construction. The README also lists Runway and Pika as alternatives in its structured metadata keywords, though it does not compare their output quality or pricing anywhere in the text.

Licence, maintenance and upgrade cost

The project is MIT licensed, and the LICENSE file is at the repository root. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice are preserved. That covers the source. It does not cover whatever terms Agnes AI attaches to the cloud models the application calls, and the repository does not restate those terms. Treat the two separately when you assess whether a commercial deployment is viable.

Upgrades are the other recurring cost. Because the application is distributed as a Docker image, an npm package and a source checkout, each channel can be at a different version, and the Compose file pinning 6.3.0 against a v6.5.0 release is the concrete example. The Dockerfile accepts a PIP_INDEX_URL build argument, which the comments say exists for faster builds from mainland China, so a rebuild is not identical across regions. There is no migration guide in the repository for moving a working directory between versions, so pinning a tag and testing an upgrade against a copy of agnes_data is the cautious path.

Editorial conclusion

Adopt Agnes Video Generator if you want a locally hosted pipeline that produces narrated, subtitled multi-scene videos from text and you are willing to run a Python service or a Docker container. Skip it if you need frame-level control over every shot, or if you cannot send your prompts to Agnes AI's cloud models. Before committing, check whether the AGNES_API_KEY environment variable is required for the modes you plan to use, and confirm that the image tag you pin in docker-compose.yml actually exists on the registry you pull from.

Frequently asked questions

Official sources

1. lcy362/agnes-video-generator on GitHub
2. License: MIT
3. Project website
4. README
5. Releases