README.md

---
title: ChronoWeave
emoji: 🏆
colorFrom: red
colorTo: pink
sdk: streamlit
sdk_version: 1.44.1
app_file: app.py
pinned: false
---
# ChronoWeave - Interactive Multiverse Story Generation

[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](YOUR_SPACE_URL_HERE) # <-- Add your space URL later

This Streamlit application demonstrates the "ChronoWeave" concept: generating multiple, branching narrative timelines based on a core theme using Google's Gemini and Imagen APIs.

**Concept:**

Instead of a single linear story, ChronoWeave explores "what if" scenarios. You provide a theme, the number of scenes, the number of parallel timelines you want to explore, and optionally, a specific point or idea for divergence. The application then:

1.  Generates structured story data for multiple timelines using Gemini, ensuring narrative divergence.
2.  Generates images for each scene in each timeline using Imagen, potentially with subtle visual shifts.
3.  Generates narration audio for each scene using Gemini Live.
4.  Composes separate video files for each timeline using MoviePy.

**How to Use:**

1.  **API Key:** Ensure you have a Google API Key with access to the Gemini API (including v1alpha for Live) and Imagen. Add this key as a Secret named `GOOGLE_API_KEY` in your Hugging Face Space settings.
2.  **Inputs:**
    *   Enter a story `theme`.
    *   Select the `number of scenes` per timeline.
    *   Select the `number of timelines` to generate (e.g., 2 or 3).
    *   (Optional) Provide a `divergence prompt` hinting at how the timelines should differ (e.g., "What if the hero hesitated?", "Explore a path where they find a map").
3.  **Generate:** Click the "Generate ChronoWeave" button.
4.  **Wait:** Generation involves multiple API calls and video processing, which can take time. Status updates will be shown.
5.  **View:** Once complete, videos for each generated timeline will be displayed.

**Technology Stack:**

*   Streamlit (UI)
*   Google Gemini API (Story Generation, Audio Narration - v1alpha Live)
*   Google Imagen API (Image Generation)
*   MoviePy (Video Composition)
*   Hugging Face Spaces (Hosting)

**Based On:**

This application builds upon the concepts demonstrated in the "Gemini API: Animated Story Video Generation" Colab Notebook by Yousif Ahmed. Copyright 2025 Google LLC. Licensed under Apache License 2.0.

**Note:** Generation can be resource-intensive. Higher numbers of scenes or timelines may take longer or hit resource limits on Hugging Face Spaces free tier.
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference