README.md

---
title: CineeeeAi
emoji: 🚀
colorFrom: red
colorTo: red
sdk: docker
app_port: 8501
tags:
- streamlit
pinned: false
short_description: Streamlit template space
---

# 🎬 CineGen AI: Cinematic Video Generator 🚀

CineGen AI is your AI-powered pocket film studio, designed to transform your textual ideas into compelling cinematic concepts, storyboards, and preliminary animatics. Leveraging the multimodal understanding and generation capabilities of Google's Gemini, CineGen AI assists creators in rapidly visualizing narratives.

**Current Stage:** Alpha/Prototyping (Uses placeholder visuals, focuses on script and visual prompt generation with interactive editing)

## ✨ Key Features

*   **AI Story Generation:** Input a core idea, genre, and mood, and let Gemini craft a multi-scene story breakdown.
*   **Intelligent Scene Detailing:** Each scene includes:
    *   Setting descriptions
    *   Characters involved
    *   Key actions & dialogue snippets
    *   Visual style and camera angle suggestions
    *   Emotional beats
*   **Visual Concept Generation:** For each scene, CineGen AI (via Gemini) generates detailed prompts suitable for advanced AI image generators. (Currently visualizes these as placeholder images with text).
*   **Interactive Storyboarding:**
    *   **Script Regeneration:** Modify scene details (action, dialogue, mood) and have Gemini rewrite that specific part of the script.
    *   **Visual Regeneration:** Provide feedback on visual concepts, and Gemini will refine the image generation prompt.
*   **Conceptual Advanced Controls:**
    *   **Character Consistency (Foundation):** Define character descriptions to guide visual generation (prompt-based).
    *   **Style Transfer (Textual Foundation):** Apply textual descriptions of artistic styles to influence visuals.
    *   **Camera Angle Selection:** Basic camera angle choices to guide prompt generation.
*   **Animatic Video Creation:** Stitches generated (placeholder) images into a simple video sequence with `moviepy`.
*   **Modular Architecture:** Built with Python, Streamlit, and a clear separation of concerns for easier expansion.
*   **Dockerized:** Ready for deployment on platforms like Hugging Face Spaces.

## 🛠️ Tech Stack

*   **Core Logic:** Python
*   **LLM Backend:** Google Gemini API (via `google-generativeai`)
*   **UI Framework:** Streamlit
*   **Image Handling:** Pillow
*   **Video Assembly:** MoviePy
*   **Containerization:** Docker (for Hugging Face Spaces / portability)

## ⚙️ Setup & Installation

1.  **Clone the Repository:**
    ```bash
    git clone <your-repo-url>
    cd cinegen-ai
    ```

2.  **Create Python Virtual Environment (Recommended):**
    ```bash
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```

3.  **Install Dependencies:**
    ```bash
    pip install -r requirements.txt
    ```

4.  **Set Up API Key:**
    *   Create a `.streamlit/secrets.toml` file in the root of the project.
    *   Add your Google Gemini API key:
        ```toml
        GEMINI_API_KEY = "YOUR_ACTUAL_GEMINI_API_KEY"
        ```
    *   **IMPORTANT:** Do NOT commit your `secrets.toml` file if your repository is public. Add `.streamlit/secrets.toml` to your `.gitignore` file.

5.  **Font Requirement (for Placeholder Images):**
    *   The `visual_engine.py` currently tries to use "arial.ttf".
    *   Ensure this font is available on your system, or modify the `ImageFont.truetype("arial.ttf", 24)` line in `core/visual_engine.py` to point to a valid `.ttf` font file on your system, or let it fall back to `ImageFont.load_default()`.
    *   On Debian/Ubuntu, you can install common Microsoft fonts: `sudo apt-get update && sudo apt-get install ttf-mscorefonts-installer`

6.  **Run the Streamlit App:**
    ```bash
    streamlit run app.py
    ```

## 🐳 Docker & Hugging Face Spaces Deployment

1.  Ensure Docker is installed and running.
2.  Build the Docker image (optional, for local testing):
    ```bash
    docker build -t cinegen-ai .
    ```
3.  Run the Docker container (optional, for local testing):
    ```bash
    docker run -p 8501:8501 -e GEMINI_API_KEY="YOUR_ACTUAL_GEMINI_API_KEY" cinegen-ai
    ```
    (Note: Passing API key as env var for local Docker run. For HF Spaces, use their secrets management).
4.  **For Hugging Face Spaces:**
    *   Push your code (including the `Dockerfile`) to a GitHub repository.
    *   Create a new Space on Hugging Face, selecting "Docker" as the SDK.
    *   Link it to your GitHub repository.
    *   In the Space settings, add `GEMINI_API_KEY` as a secret.
    *   The Space will build and deploy your application.

## 🚀 Usage

1.  Open the app in your browser (usually `http://localhost:8501`).
2.  Use the sidebar to input your story idea, genre, mood, and number of scenes.
3.  Click "Generate Full Story Concept."
4.  Review the generated scenes and visual concepts.
5.  Use the "Edit Scene Script" and "Edit Scene Visuals" popovers within each scene to interactively refine content.
6.  (Optional) Define characters or styles in the sidebar for more guided generation.
7.  Once satisfied, click "Assemble Animatic Video."

## 🔮 Future Enhancements (Roadmap to "Wow")

*   **True AI Image Generation:** Integrate state-of-the-art text-to-image models (e.g., Stable Diffusion, DALL-E 3, Midjourney API) to replace placeholders.
*   **Advanced Character Consistency:** Implement techniques like LoRAs, textual inversion, or re-identification models for visually consistent characters across scenes.
*   **Image-Based Style Transfer:** Allow users to upload reference images to define artistic styles.
*   **AI Sound Design:** Generate or suggest sound effects and background music.
*   **Direct Video Snippets:** Integrate text-to-video models for dynamic short clips.
*   **Enhanced Camera Controls & Shot Design:** More granular control over virtual cinematography.
*   **User Accounts & Project Management.**
*   **Export Options:** PDF storyboards, FDX/script formats.

## 📄 License

Consider a license like MIT or Apache 2.0 if you plan for open collaboration or wish to be permissive. If this is a commercial product, consult with legal counsel for appropriate licensing.
For now, let's assume:
**MIT License** (Add the full MIT License text if you choose this)

---
Copyright (c) [Year] [Your Name/Company Name]