DOCSEARCHbyAlgolia
Submit Docs

NarratoAI Documentation

repository·main·Indexed 27 days ago

https://github.com/linyqh/narratoai

An all-in-one AI-powered tool for film commentary and automated video editing. NarratoAI uses Large Language Models (LLMs) to handle scriptwriting, automated video editing, voiceovers, and subtitle generation. It supports optional integrations such as TwelveLabs Pegasus for video understanding and Sonilo for AI-generated background music. Version 0.8.4.

Tokens
1.6K
Snippets
5
Records
10
Agent score
95%

What's inside NarratoAI

  1. System Requirements for NarratoAI

    main

    To ensure smooth operation, the following hardware and software specifications are recommended:

    • CPU: Minimum 4 cores or higher.
    • RAM: 8GB or more.
    • GPU: Optional (not strictly required).
    • OS: Windows 10/11 or macOS 11.0 or higher.
    • Python: Version 3.12 or higher.

  2. Run NarratoAI locally

    main

    To run NarratoAI from a local clone, ensure you have Python 3.12+ installed. Use uv for dependency management and streamlit to launch the web interface. You must also create a config.toml file from the provided example.

    git clone https://github.com/linyqh/NarratoAI.git
cd NarratoAI

uv sync
cp config.example.toml config.toml
uv run streamlit run webui.py --server.maxUploadSize=2048

  3. Quick Start: Deploy via macOS Docker

    main

    If you are on macOS, you can deploy NarratoAI using Docker Compose:

    1. Clone the repository.
    2. Run docker compose up -d to deploy.
    3. Access the application at http://localhost:8501 in your browser.
    git clone https://github.com/linyqh/NarratoAI.git
cd NarratoAI
docker compose up -d

  4. Quick Start: Install via Integrated Package (Recommended)

    main

    The easiest way to run NarratoAI is by using the pre-packaged integrated bundles. Download the version corresponding to your operating system from https://cutagent.online/ and extract it fully. Do not move the NarratoAI, runtime, or tools directories separately.

    Windows

    1. Open the extracted NarratoAI-windows-x64 directory.
    2. Double-click update-windows.bat and wait for the update to complete.
    3. Double-click start.bat to launch the application (keep the window open).
    4. Access the app in your browser at http://127.0.0.1:8501.

    macOS (Apple Silicon)

    1. Open the extracted NarratoAI-macos-arm64 directory.
    2. If the system blocks the scripts, run the following in Terminal (replace the path with your actual extraction path):
      xattr -cr "/path/to/NarratoAI-macos-arm64"
chmod +x "/path/to/NarratoAI-macos-arm64/"*.command
    3. Double-click update-macos.command and wait for completion.
    4. Double-click start-macos.command to launch (keep the terminal window open).
    5. Access the app in your browser at http://127.0.0.1:8501.
    xattr -cr "/path/to/NarratoAI-macos-arm64"
chmod +x "/path/to/NarratoAI-macos-arm64/"*.command

  5. Quick Start: Local Development Setup

    main

    To run NarratoAI locally from source, follow these steps:

    1. Clone the repository.
    2. Use uv to install dependencies.
    3. Copy the example configuration file to config.toml.
    4. Edit config.toml with your required API keys.
    5. Run the Streamlit application.
    6. Access the app at http://localhost:8501.
    git clone https://github.com/linyqh/NarratoAI.git
cd NarratoAI
uv sync
cp config.example.toml config.toml
uv run streamlit run webui.py --server.maxUploadSize=2048

  6. Configure Sonilo AI Background Music

    main

    NarratoAI supports AI-generated background music via Sonilo.

    • How to use: In the WebUI, select "AI Generated BGM (Sonilo)" as the background music source. The music is generated based on visual content and editing rhythm.
    • Requirement: You must configure a valid Sonilo API Key.
    • Limitations: Supports videos up to 6 minutes. If generation fails, the system automatically falls back to random background music to prevent task interruption.

  7. Configure TwelveLabs as a video-understanding backend

    main
    You can opt-in to use TwelveLabs Pegasus as a video-understanding backend. This allows the system to analyze footage natively to drive highlight selection and commentary. To enable this, set the vision_llm_provider key in your configuration to "twelvelabs".

  8. Configure TwelveLabs Video Understanding

    main

    You can use TwelveLabs Pegasus as an optional video understanding backend to analyze footage for highlights and script generation. To enable this, set the following configuration key in your settings:

    vision_llm_provider = "twelvelabs"

  9. Deploy NarratoAI using Docker Compose

    main

    You can deploy the NarratoAI WebUI using Docker Compose. The service maps port 8501 on the host to port 8501 in the container. It uses a local storage directory, a config.toml file, and a resource directory for persistent data and configuration.

    Required local files/directories:

    • ./storage (directory)
    • ./config.toml (file)
    • ./resource (directory, read-write)

    Environment Variables:

    • PYTHONUNBUFFERED=1: Ensures Python output is sent straight to the container logs.
    • TZ=Asia/Shanghai: Sets the container timezone to Asia/Shanghai.
    services:
  narratoai-webui:
    build:
      context: .
      dockerfile: Dockerfile
    image: narratoai:latest
    container_name: narratoai-webui
    ports:
      - "8501:8501"
    volumes:
      - ./storage:/NarratoAI/storage
      - ./config.toml:/NarratoAI/config.toml
      - ./resource:/NarratoAI/resource:rw
    environment:
      - PYTHONUNBUFFERED=1
      - TZ=Asia/Shanghai
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8501/_stcore/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  10. Configure NarratoAI Docker volumes and ports

    main

    When using the docker-compose.yml configuration, the following mappings are used to manage data and access the application:

    Ports

    • 8501:8501: Access the WebUI via http://localhost:8501.

    Volumes

    • ./storage:/NarratoAI/storage: Persistent storage for application data.
    • ./config.toml:/NarratoAI/config.toml: Main configuration file.
    • ./resource:/NarratoAI/resource:rw: Resource directory with read-write access.