Update README.md

README.md

@@ -8,5 +8,44 @@ 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