---
title: StoryLens
emoji: 🎬
colorFrom: green
colorTo: blue
sdk: streamlit
sdk_version: 1.53.0
app_file: app.py
pinned: false
license: apache-2.0
---

# 🎬 StoryLens

Professional video ad narrative structure analyzer powered by AI. Diagnose your ad's storytelling effectiveness in 60 seconds.

## ✨ Features

- **Multi-source Input**: Upload video files (MP4, MOV, AVI, WebM) or paste YouTube URL
- **AI-Powered Analysis**: MiniMax Vision for frame analysis, OpenAI Whisper for transcription
- **Functional Role Classification**: 21 roles across 5 categories (Opening, Problem, Product, Persuasive, Closure)
- **Story Arc Detection**: Identifies patterns like AIDA, PAS, HFBA, and more
- **Industry Benchmarks**: Recommendations based on Meta research (WWW 2026)
- **Actionable Insights**: Prioritized recommendations with expected performance uplift

## 🚀 Quick Start

1. Configure API keys in sidebar:
   - **MiniMax API Key** + Group ID (for vision & LLM)
   - **OpenAI API Key** (for Whisper transcription)
2. Select your **Industry** and **Campaign Goal**
3. Upload video file or paste YouTube URL
4. Click **"Analyze"**
5. Review narrative timeline, story arc, and recommendations

## 🔑 API Keys Required

- **MiniMax**: Get from [MiniMax Platform](https://platform.minimax.io/)
- **OpenAI**: Get from [OpenAI Platform](https://platform.openai.com/)

## 📊 Supported Industries

- Apparel & Accessories
- Beauty
- Food
- Beverages
- Other

## 🎯 Campaign Goals

- Retention (Dwell Rate)
- Click-Through (CTR)
- Conversions (CVR)

## 📚 Based On

Research paper: *MLLM-VADStory: Domain Knowledge-Driven Multimodal LLMs for Video Ad Storyline Insights* (Meta, WWW 2026)

## 🛡️ Privacy

- API keys never stored permanently
- Videos processed temporarily only
- No data retention

## 📄 License

Licensed under **Apache License 2.0**

## 👨‍💻 Author

**Marek Staniszewski**
**Heuristica**
🌐 [www.heuristica.pl](https://www.heuristica.pl)
📧 staniszewski@heuristica.pl

For questions, suggestions, or support, please contact the author.