Skip to content
Get packs

Guide · Open source

How to use NarratoAI: install, configure and make a video

Updated · written with AI from the project's own documentation and checked against our catalogue data

NarratoAI is an open-source tool for making commentary-style videos. It uses large language models to write narration scripts, then handles clip editing, voiceover and subtitle generation in one workflow. This guide walks through the install options the README lists, the configuration you need, and what the tool is and isn't suited for, so you can run it yourself by the end.

NarratoAIlinyqh/NarratoAI · ★ 11.7k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Docker, or Python 3.12+ and uv, and enough RAM for the workload.
  2. 2Clone the repository. Run git clone on the linyqh/NarratoAI repository and enter the NarratoAI folder.
  3. 3Start with Docker Compose. Run docker compose up -d from the project folder to start the app.
  4. 4Open the web interface. Visit http://localhost:8501 in your browser once the containers are running.
  5. 5Add your API keys. Copy config.example.toml to config.toml and enter the LLM and TTS provider keys you plan to use.
  6. 6Create a commentary video. Upload your source footage in the web UI, generate the narration script, then produce the voiceover and subtitles.

Check the requirements before you install

The README lists Docker, Python 3.12+ and uv as the prerequisites for the Docker and local setups. It recommends at least a 4-core CPU and 8 GB of RAM, with a GPU not required, and says it runs on Windows 10/11 or macOS 11.0 or later.

NarratoAI also needs API keys for the LLM and TTS providers you choose, because the README says you must configure them before the workflow runs.

  • CPU: 4 cores or more recommended
  • Memory: 8 GB or more recommended
  • GPU: not required
  • OS: Windows 10/11 or macOS 11.0+
  • Python 3.12+ for the local setup

Install NarratoAI with Docker Compose

The README marks Docker as the recommended path for macOS. Clone the repository, enter the project folder and start the stack with Docker Compose.

When the containers are up, open http://localhost:8501 in your browser to reach the web interface.

git clone https://github.com/linyqh/NarratoAI.git cd NarratoAI docker compose up -d

Run NarratoAI locally with uv

For a local Python run, the README uses uv to install dependencies. Copy the example config to config.toml, then add your API keys to that file before starting the app.

Start the web app with Streamlit, using the upload size flag from the README. Then open http://localhost:8501.

  • Install dependencies with uv
  • Copy config.example.toml to config.toml
  • Edit config.toml and add your API keys
git clone https://github.com/linyqh/NarratoAI.git cd NarratoAI uv sync cp config.example.toml config.toml # edit config.toml and add your API keys uv run streamlit run webui.py --server.maxUploadSize=2048

Use the packaged Windows or macOS build

The README lists a packaged build from cutagent.online as the first option. Download the build for your system and extract the full archive. Do not move the NarratoAI, runtime or tools folders on their own.

On Windows, run update-windows.bat first, then start.bat, and keep the launch window open. On Apple Silicon Macs, use the arm64 build and run update-macos.command, then start-macos.command. The README notes that if macOS blocks the scripts, you can clear the quarantine attribute and make the .command files executable with the commands shown there.

  • Windows: x64 build, folder NarratoAI-windows-x64
  • macOS: Apple Silicon arm64 build, folder NarratoAI-macos-arm64
  • Open http://127.0.0.1:8501 in your browser once started

Set up the workflow: script, voice and subtitles

NarratoAI's README describes four steps in one flow: an LLM writes the narration script, the tool edits clips, a TTS engine produces the voiceover, and subtitles are generated. Short-drama mashup and commentary modes are both mentioned in the project's release notes.

The README lists several TTS and voice-cloning options, including IndexTTS-1.5 for Apple Silicon via MLX and OmniVoice. Pick the engine that fits your platform and check its provider settings in config.toml.

  • Script: LLM writes narration
  • Edit: clip editing and video handling
  • Voice: TTS, with voice cloning engines listed in the README
  • Subtitles: automatic generation, plus transcription via Fun-ASR according to the release notes

Avoid common mistakes

The README warns about scams. It says NarratoAI is free software and that some people have renamed it and sold it on social media. Download only from the official repository, wiki or the official site listed in the README.

The README also says release notes can be sparse, and it lists frequent releases, so pin a working version and back up your config.toml before you update.

  • Do not pay for a renamed copy; the README says the project is free
  • Keep your API keys in config.toml and never commit them to git
  • Re-check config.toml after each update

What people use it for

  • Creating commentary-style videos from long-form footage
  • Making short-drama mashup videos with script generation and clip merging
  • Generating AI voiceovers, including voice-cloned narration with IndexTTS-1.5 or OmniVoice
  • Exporting clips to a CapCut (Jianying) draft, as listed in the README's feature plan

Frequently asked questions

Is NarratoAI free?

The README says NarratoAI is completely free software and is released under the MIT licence. It also warns that some people have renamed the project and sold it, so only use the official repository. You still need your own API keys for LLM and TTS providers.

What license does NarratoAI use?

NarratoAI is licensed under MIT, as shown in the repository's LICENSE file. The README links to that file for the full text.

What do I need to install NarratoAI?

The README lists Docker, Python 3.12+ and uv as prerequisites, and recommends 4 CPU cores and 8 GB of RAM. It supports Windows 10/11 and macOS 11.0 or later.

How do I install NarratoAI with Docker?

Clone the GitHub repository, enter the NarratoAI folder and run docker compose up -d. Then open http://localhost:8501 in your browser.

Can NarratoAI run fully offline?

Not in a verified way. The README says you must configure API keys for LLM and TTS providers, so the workflow depends on those services. Some voice engines like IndexTTS-1.5 on macOS run locally, but the README does not claim a fully offline workflow.

What are alternatives to NarratoAI?

The README lists MoneyPrinter and MoneyPrinterTurbo as related projects; NarratoAI was rebuilt from them and adds commentary features. Auto-Subtitle is also a comparable project for subtitle generation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

NarratoAI suits creators who are comfortable with Docker or Python, want commentary or short-drama mashups, and will supply their own API keys. If you want a no-setup experience, a mobile app, or a stable tool with detailed changelogs and guaranteed compatibility, look at one of the comparable projects instead.

Install options & downloads