🎬 Story2Screen - AI Movie Script Generator

Transform any story into a professional movie screenplay and trailer with AI-powered automation.

Story2Screen is an intelligent application that takes a narrative—whether it's a story idea, Reddit post, or creative concept—and automatically generates:

• ✨ A complete movie screenplay with proper formatting
• 🎥 A compelling movie trailer extracted from cinematic moments
• 📄 A downloadable PDF combining both outputs

---

🚀 Features

• Story-to-Screenplay Pipeline: Intelligent conversion from narrative text to professional screenplay format
• AI-Powered Analysis: Uses Google Gemini 2.5 Flash for creative and coherent story understanding
• Scene Extraction: Automatically identifies cinematic moments from the screenplay
• Trailer Generation: Creates an engaging trailer strictly from screenplay content
• PDF Export: Download scripts and trailers in professional PDF format
• Streamlit Web Interface: User-friendly web app with real-time processing feedback
• Modular Architecture: Clean separation of concerns for easy customization

---

📋 Workflow

Story Input
    ↓
Story Analysis (Analyze themes, characters, plot structure)
    ↓
Plot Building (Create detailed plot outline)
    ↓
Screenplay Writing (Generate formatted movie script)
    ↓
Scene Extraction (Identify key cinematic moments)
    ↓
Trailer Generation (Craft engaging trailer from scenes)
    ↓
PDF Export (Download as professional document)

---

💻 Tech Stack

• Backend: Python 3.8+
• UI Framework: Streamlit - Simple and elegant web interface
• AI/LLM: Google Generative AI (Gemini 2.5 Flash) - Fast creative text generation
• PDF Generation: fpdf - Professional document export
• Environment Management: python-dotenv - Secure API key handling

---

🔧 Installation

Prerequisites

• Python 3.8 or higher
• Google Gemini API key (get one free here)

Step 1: Clone the Repository

git clone <repository-url>
cd "AI Movie Script Generator"

Step 2: Create Virtual Environment (Optional but Recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Set Up Environment Variables

Create a .env file in the project root:

GEMINI_API_KEY=your_api_key_here

---

🎯 Quick Start

Running the Application

streamlit run app.py

The web interface will open at http://localhost:8501

Basic Usage

1. Paste your story in the text area (story idea, Reddit post, plot synopsis, etc.)
2. Click "🎥 Generate Script & Trailer"
3. Review the outputs:
   • Movie screenplay with proper formatting
   • Generated trailer
4. Download as PDF for sharing or printing

---

📁 Project Structure

AI Movie Script Generator/
├── app.py                      # Main Streamlit application
├── requirements.txt            # Python dependencies
├── verify_prompts.py          # Utility for validating prompt quality
│
├── config/
│   ├── settings.py            # Gemini API configuration
│   └── __pycache__/
│
├── core/                       # Core processing modules
│   ├── story_analyzer.py      # Analyzes narrative structure and themes
│   ├── plot_builder.py        # Creates detailed plot outlines
│   ├── script_writer.py       # Generates screenplay from plot
│   ├── scene_extractor.py     # Identifies cinematic moments
│   ├── trailer_generator.py   # Creates trailer from scenes
│   └── __pycache__/
│
├── utils/                      # Utility functions
│   ├── formatter.py           # Text formatting and parsing
│   ├── pdf_generator.py       # PDF document creation
│   └── __pycache__/
│
├── prompts/                    # AI prompt templates
│   ├── analysis.txt           # Story analysis prompts
│   ├── plot.txt               # Plot building prompts
│   ├── scene_extract.txt      # Scene identification prompts
│   ├── screenplay.txt         # Screenplay writing prompts
│   └── trailer.txt            # Trailer generation prompts
│
├── outputs/                    # Generated output directory
│   ├── scripts/               # Saved screenplays
│   └── trailers/              # Saved trailers
│
└── README.md                  # This file

---

🔑 Configuration

API Configuration

The application uses Google's Gemini 2.5 Flash model by default, configured in config/settings.py.

To use a different model:

MODEL_NAME = "gemini-pro"  # or another available model

Custom Prompts

Modify prompt templates in the prompts/ directory to customize:

• Story analysis approach
• Plot structure preferences
• Screenplay format
• Trailer tone and style

---

📚 How It Works

1. Story Analysis

The application analyzes the input story to extract:

• Main themes and messages
• Character profiles and arcs
• Plot structure and key turning points
• Emotional tone and pacing

2. Plot Building

Creates a structured outline including:

• Three-act structure breakdown
• Scene-by-scene progression
• Character development points
• Dialogue and action requirements

3. Screenplay Writing

Generates a professional screenplay with:

• Proper screenplay formatting (INT./EXT., action, dialogue)
• Scene headings and descriptions
• Character names and dialogue
• Parenthetical directions

4. Scene Extraction

Identifies the most cinematic and impactful moments from the screenplay based on:

• Visual interest
• Emotional impact
• Plot importance
• Entertainment value

5. Trailer Generation

Creates an engaging trailer that:

• Showcases the story's best moments
• Maintains narrative coherence
• Builds suspense and interest
• Stays true to screenplay content

---

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs and issues
• Suggest improvements
• Add new features
• Optimize existing code
• Enhance prompt templates

---

⚠️ Important Notes

• API Usage: Free tier of Google Gemini API may have rate limits. Check pricing details
• Output Quality: Results depend on story clarity and length. Well-structured input produces better screenplays
• Customization: Modify prompts and models for different genres and styles
• Dependencies: Ensure all packages in requirements.txt are installed

---

📝 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You are free to:

• Use, modify, and distribute this software
• Use it for both commercial and non-commercial purposes

Under the condition that you:

• Include a copy of the license with any distribution
• Disclose the source code
• Include a notice of modifications
• Use the same license for derivative works

For more details, see the GNU GPL v3.0 License.

---

🎓 Learning Resources

• Screenwriting Basics
• Streamlit Documentation
• Google Generative AI Guide
• PDF Generation with fpdf

---

🐛 Troubleshooting

Error: "GEMINI_API_KEY not found"

• Ensure .env file exists in project root
• Verify API key is correctly set: GEMINI_API_KEY=your_key
• Restart the Streamlit app

Slow Generation

• This is normal for longer stories (can take 1-3 minutes)
• Gemini 2.5 Flash prioritizes quality over speed
• Check internet connection

PDF Export Issues

• Ensure fpdf is installed: pip install fpdf
• Check write permissions in outputs directory

---

📧 Support

For issues, questions, or suggestions, please review the code documentation or check the prompts in the prompts/ directory for customization options.

---

Made with ❤️ for storytellers and screenwriters

Story2Screen - Because every great story deserves to be on screen.