Image Storyteller

Create immersive stories from a sequence of images and listen to an AI-generated narration. This Streamlit app connects visual inspiration with Google Gemini for storytelling and gTTS for speech synthesis, making it simple to turn your photo sets into narrated tales.

---

🚀 Features

• Interactive UI – Upload 1–10 images via the Streamlit sidebar and preview them in a responsive grid.
• Genre Control – Choose from Comedy, Thriller, Fairy Tale, Sci-Fi, Mystery, Adventure, or Morale to influence tone and structure.
• AI-Authored Stories – Calls Google Gemini (gemini-2.5-flash-lite) to weave a unified narrative that references every uploaded image.
• Audio Narration – Converts the generated story into a playable MP3 using gTTS.
• Genre-Specific Closers – Mystery, Thriller, and Morale stories append solution, twist, or moral sections automatically.

---

📂 Project Structure

.
├── app.py                # Streamlit front-end and user workflow
├── story_generator.py    # Story generation + narration helpers
├── requirements.txt      # Python dependencies
├── .env                  # Local environment variables (not tracked)
└── README.md             # Documentation

---

🧰 Prerequisites

• Python 3.9+
• Pip (latest version recommended)
• A Google Generative AI API key with access to gemini-2.5-flash-lite

---

🔑 Environment Variables

Create a .env file in the project root with one of the following keys:

# .env
GENAI_API_KEY=your_google_generative_ai_key
# or
GOOGLE_API_KEY=your_google_generative_ai_key

The app loads environment variables using python-dotenv. If neither key is set, the app raises an initialization error.

---

📦 Installation

1. Create and activate a virtual environment (recommended).
2. Install dependencies from requirements.txt:

   pip install -r requirements.txt

---

▶️ Running the App

1. Ensure your .env file is configured.
2. Launch Streamlit from the project root:

   streamlit run app.py

3. Open the Streamlit URL in your browser (usually http://localhost:8501).

---

📝 Usage

1. Upload between one and ten JPG/PNG images.
2. Select a storytelling style from the dropdown.
3. Click Generate Story and Narration.
4. Read the generated story and optionally play the narration audio.

If generation fails, check your API key and network connectivity—error messages are surfaced in the UI.

---

🎯 Customization Ideas

• Adjust the prompt in story_generator.py:create_advanced_prompt() to change persona, length, or tone.
• Swap gemini-2.5-flash-lite for another Gemini model if you need higher quality (note pricing/latency changes).
• Modify gTTS language or speed inside narrate_story() to localize narration.

---

🧪 Troubleshooting

• "API key not found" – Confirm your .env file is present and keys are spelled correctly.
• Narration not generated – gTTS requires internet access. Ensure outbound connectivity to Google services.
• Streamlit warnings about file types – The uploader accepts only png, jpg, and jpeg files.

Check the Streamlit logs in the terminal for additional stack traces when errors occur.

---

📜 License

This project currently has no explicit license. Add one if you plan to distribute or open-source the application.