BeatTeller revolutionizes the way we experience music through the power of storytelling. This innovative platform combines cutting-edge artificial intelligence with Qloo's taste expertise to transform musical preferences into compelling narratives. Developed specifically for the Qloo LLM Hackathon 2025, BeatTeller demonstrates the seamless integration between the Qloo API and Gemini AI's creative text generation capabilities.
The application goes beyond traditional music recommendation by creating a unique storytelling experience where every beat tells a story. By analyzing users' musical tastes and preferences, BeatTeller crafts personalized narratives that bring their musical journey to life, creating an emotional connection between listeners and their favorite tracks.
BeatTeller's core engine leverages the sophisticated Qloo API to analyze and understand users' musical DNA. The system transcends simple genre matching by examining the subtle nuances of musical preferences, including emotional resonance, listening context, and thematic connections. This deep analysis enables the discovery of tracks that truly align with each user's unique musical identity.
Through integration with Gemini AI, BeatTeller transforms music selections into rich, personalized narratives. These aren't just descriptions—they're creative stories that explore the emotional threads connecting different musical pieces. Each narrative is tailored to the user's preferred storytelling style, whether it's an epic adventure, a romantic journey, or a contemplative reflection.
One of BeatTeller's most innovative features is its ability to weave connections between music and other cultural experiences. By harnessing the depth of the Qloo API, the application can recommend movies, books, dining experiences, or other cultural touchpoints that harmonize with users' musical tastes, creating a cohesive storytelling ecosystem.
BeatTeller's interface has been crafted with a focus on immersive storytelling. It features cinematic animations, atmospheric visual effects, and an adaptive theme system that enhances the narrative experience. The responsive design ensures optimal storytelling across all devices, from desktop theaters to mobile story readers.
The application offers a comprehensive visual storytelling system with dark, light, and system modes. Each theme has been designed to enhance the narrative atmosphere while maintaining accessibility and readability, with smooth transitions that complement the storytelling experience.
BeatTeller's backend is built on a robust Flask architecture designed to efficiently orchestrate interactions between AI services while maintaining optimal performance for storytelling workflows. The architecture follows modular design principles, enabling seamless story generation and music discovery.
Framework and Technologies
- Flask: Lightweight web framework optimized for AI service integration
- Flask-CORS: Cross-origin request management for seamless frontend-backend communication
- SQLAlchemy: Database ORM for user story and preference management
- Python-dotenv: Secure environment variable management for API keys
AI Service Integrations
- Qloo API: Advanced taste intelligence and personalized music recommendations
- Google Gemini AI: Creative storytelling and narrative generation
- Error Handling: Robust fallback system ensuring continuous storytelling experience
Core API Endpoints
/api/discover: Music discovery based on storytelling preferences/api/story: Personalized narrative generation from music selections/api/recommendations: Similar tracks and cross-domain story connections/api/trending: Current musical trends and popular stories/api/profile: User musical taste and story preference profile/api/mood-analysis: Mood-based story theme analysis/api/playlist-generator: Thematic playlist creation for storytelling
The frontend utilizes React with Vite for modern development and optimized storytelling performance. The component architecture is designed around narrative flow with efficient state management and immersive user interactions.
Technologies and Frameworks
- React 19: Modern JavaScript framework for interactive storytelling interfaces
- Vite: Fast build tool optimized for development workflow
- Tailwind CSS: Utility-first CSS framework for consistent storytelling aesthetics
- shadcn/ui: Modern, accessible UI components for enhanced user experience
- Framer Motion: Cinematic animations and storytelling transitions
Core Components
- ThemeProvider: Global theme management for storytelling atmosphere
- BackgroundImageManager: Dynamic visual storytelling backgrounds
- ResultsDisplay: Immersive display of music discoveries and stories
- MusicCard: Interactive music cards with storytelling integration
Before installing BeatTeller, ensure your system meets these requirements:
- Python 3.11+: Modern Python version with AI library support
- Node.js 20+: Current JavaScript runtime environment
- pnpm: High-performance package manager
- API Keys: Access credentials for Qloo and Gemini AI APIs
# Clone the BeatTeller project
git clone <repository-url>
cd beatteller_project
# Create Python virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or venv\Scripts\activate # Windows
# Install backend dependencies
cd backend
pip install -r requirements.txtCreate a .env file in the backend/ directory:
# API Keys for AI Services
QLOO_API_KEY=your_qloo_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here
# Flask Application Configuration
FLASK_ENV=development
FLASK_DEBUG=True
FLASK_HOST=0.0.0.0
FLASK_PORT=5001
# Database Configuration
DATABASE_URL=sqlite:///src/database/beatteller.db# Navigate to frontend directory
cd ../frontend
# Install dependencies
pnpm install
# Approve build scripts if prompted
pnpm approve-buildsTerminal 1 - Backend Services:
cd backend
python src/main.pyTerminal 2 - Frontend Application:
cd frontend
pnpm run devAccess BeatTeller at:
- Frontend Interface: http://localhost:5173
- Backend API: http://localhost:5001
- Enter Your Musical Journey: Describe your musical preferences or current mood in the main text field
- Set the Scene: Choose from predefined mood options to set your story's tone
- Genre Selection: Optionally specify musical genres to guide your story
- Begin Discovery: Click "Discover Music" to start your personalized musical storytelling experience
- Select Your Soundtrack: Choose multiple tracks from your discovery results
- Personalize Your Story: Enter your name and select your preferred narrative style
- Generate Your Tale: Let Gemini AI craft a unique story based on your musical selections
- Find Similar Stories: Click the search icon on any track to discover related musical narratives
- Trending Tales: Explore the "Trending" section for popular musical stories
- Cross-Cultural Connections: Discover how your music connects to movies, books, and experiences
- Visual Themes: Use the theme toggle to switch between dark, light, and system modes for optimal reading
- Dynamic Backgrounds: Enable atmospheric backgrounds that enhance your storytelling experience
- Responsive Storytelling: The interface adapts seamlessly to your device for optimal narrative flow
BeatTeller was created specifically for the Qloo LLM Hackathon 2025, showcasing innovative applications at the intersection of AI storytelling and music discovery. This project demonstrates breakthrough integration between:
- AI Synergy: Novel combination of Qloo's taste intelligence with Gemini AI's storytelling capabilities
- Narrative UX: Storytelling-first interface that makes AI accessible and emotionally engaging
- Scalable Architecture: Modular design enabling future expansion of storytelling features
- Emotional Engagement: Transforms data into meaningful narrative experiences
- Personalized Storytelling: Each user receives unique stories based on their musical DNA
- Cultural Bridge-Building: Creates unexpected connections between different forms of artistic expression
- Music Streaming Evolution: New paradigm for music discovery through storytelling
- Content Creation: Model for AI-assisted creative content generation
- Cultural Recommendation: Framework for cross-domain cultural discovery
beatteller_project/
├── backend/ # Flask Backend Services
│ ├── src/
│ │ ├── routes/
│ │ │ ├── storytelling.py # Main storytelling and discovery routes
│ │ │ └── user.py # User profile and preference routes
│ │ ├── models/
│ │ │ └── user.py # User data models
│ │ ├── database/
│ │ │ └── beatteller.db # SQLite database
│ │ ├── static/ # Static storytelling assets
│ │ └── main.py # Application entry point
│ ├── qloo_api.py # Qloo API integration wrapper
│ ├── requirements.txt # Python dependencies
│ └── .env # Environment configuration
├── frontend/ # React Frontend Application
│ ├── src/
│ │ ├── components/
│ │ │ ├── ui/ # shadcn UI components
│ │ │ ├── ThemeProvider.jsx # Theme management system
│ │ │ ├── ThemeToggle.jsx # Theme switching component
│ │ │ ├── ResultsDisplay.jsx # Story and music results display
│ │ │ └── BackgroundImageManager.jsx # Dynamic background system
│ │ ├── App.jsx # Main application component
│ │ ├── App.css # Custom storytelling styles
│ │ └── main.jsx # React application entry
│ ├── public/
│ │ └── images/ # Visual assets and illustrations
│ ├── package.json # Node.js dependencies
│ └── vite.config.js # Vite build configuration
├── README.md # This comprehensive documentation
└── IMPROVEMENTS.md # Future enhancements roadmap
BeatTeller adopts a narrative-centered design approach, prioritizing emotional engagement and immersive storytelling. The interface combines cinematic visual elements with intuitive navigation, creating an experience that feels like stepping into a personalized musical story.
The visual identity uses advanced OKLCH color technology for precise, emotionally resonant colors:
Dark Theme (Night Mode Storytelling):
- Primary Background: oklch(0.04 0.015 240) - Deep midnight with mystical undertones
- Story Accent: oklch(0.65 0.18 280) - Enchanting purple for magical narratives
- Highlight Color: oklch(0.72 0.15 320) - Warm pink-purple for emotional moments
Light Theme (Daylight Reading):
- Primary Background: oklch(0.98 0.005 240) - Clean white for comfortable reading
- Story Accent: oklch(0.55 0.18 280) - Readable purple for daytime stories
- Highlight Color: oklch(0.62 0.15 320) - Balanced pink-purple for gentle emphasis
- Story Transitions: Smooth animations that guide users through their musical narrative
- Hover Storytelling: Interactive elements that reveal story details on interaction
- Entrance Animations: Components appear with story-like timing and elegance
- Micro-Narratives: Small details that contribute to the overall storytelling experience
The interface provides optimal storytelling across all platforms:
- Desktop Theater: Full-screen storytelling experience with rich visuals
- Tablet Reading: Comfortable narrative consumption on medium screens
- Mobile Stories: Touch-optimized storytelling for on-the-go users
BeatTeller implements sophisticated caching for enhanced storytelling performance:
- Narrative Cache: Stores generated stories for quick retrieval
- Music Discovery Cache: Reduces API calls while maintaining fresh recommendations
- Smart Invalidation: Updates cached content based on user preference evolution
Comprehensive error management ensures uninterrupted storytelling:
- Graceful Degradation: Alternative experiences when services are unavailable
- User Communication: Clear, story-themed error messages and recovery options
- Detailed Logging: Comprehensive tracking for continuous improvement
- API Key Protection: Secure storage of sensitive credentials
- Input Validation: Protection against malicious inputs and story injection
- CORS Configuration: Secure communication between frontend and backend services
- High Contrast: WCAG-compliant color schemes for all reading conditions
- Keyboard Navigation: Full story navigation without mouse dependency
- Screen Reader Support: Optimized experience for assistive technologies
- Focus Indicators: Clear visual guides for keyboard-based story navigation
- Story Load Time: < 2 seconds for complete narrative experiences
- First Contentful Paint: < 1.5 seconds for immediate engagement
- Largest Contentful Paint: < 2.5 seconds for full story display
- Cumulative Layout Shift: < 0.1 for stable reading experience
- Story Generation: < 3 seconds for complete AI-generated narratives
- Music Discovery: < 500ms for personalized recommendations
- Concurrent Users: Optimized for multiple simultaneous storytelling sessions
- Lazy Story Loading: Stories load as users scroll through results
- Bundle Splitting: Optimized JavaScript delivery for faster interactions
- Asset Compression: Minimized file sizes for quicker story experiences
- CDN Ready: Prepared for global content distribution
# Core API Configuration
QLOO_API_KEY=your_qloo_api_key
QLOO_API_BASE=https://api.qloo.com
GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-pro
# Flask Application Settings
FLASK_ENV=production
FLASK_DEBUG=False
FLASK_HOST=0.0.0.0
FLASK_PORT=5001
SECRET_KEY=your_secure_secret_key
# Database Configuration
DATABASE_URL=sqlite:///src/database/beatteller.db
DATABASE_POOL_SIZE=10
DATABASE_TIMEOUT=30
# Caching Configuration
CACHE_TYPE=simple
CACHE_DEFAULT_TIMEOUT=300
# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=beatteller.log
# Security Configuration
CORS_ORIGINS=http://localhost:5173,https://yourdomain.com
RATE_LIMIT=100 per hour
# Storytelling Configuration
MAX_STORY_LENGTH=2000
DEFAULT_STORY_STYLE=adventure
STORY_GENERATION_TIMEOUT=30Backend Optimization:
- PostgreSQL or MySQL for production database
- Gunicorn WSGI server for better performance
- Redis for advanced caching and session management
- Comprehensive monitoring and logging system
Frontend Optimization:
- Production build with
pnpm run build - CDN configuration for static assets
- Gzip compression for faster loading
- Optimized cache headers for storytelling assets
# Backend services
cd backend
python src/main.py
# Frontend application (new terminal)
cd frontend
pnpm run devDocker Deployment (Recommended):
# Build application images
docker build -t beatteller-backend ./backend
docker build -t beatteller-frontend ./frontend
# Deploy with Docker Compose
docker-compose up -dTraditional Server Deployment:
# Backend with Gunicorn
cd backend
gunicorn -w 4 -b 0.0.0.0:5001 src.main:app
# Frontend static build
cd frontend
pnpm run build
# Serve dist/ directory with nginx or apache- Vercel: Optimized for React applications with seamless deployment
- Heroku: Simple deployment with git-based workflow
- DigitalOcean: Full control with App Platform
- AWS: Enterprise-grade scalability with EC2/ECS
cd backend
python -m pytest tests/ -v --cov=src/cd frontend
pnpm run test
pnpm run e2e # End-to-end storytelling flow tests# Backend linting and formatting
cd backend
flake8 src/
black src/
mypy src/
# Frontend linting and formatting
cd frontend
pnpm run lint
pnpm run format
pnpm run type-check# Backend security analysis
cd backend
safety check
bandit -r src/
# Frontend security audit
cd frontend
pnpm audit- Voice Narration: AI-powered voice reading of generated stories
- Story Themes: Expanded narrative styles (sci-fi, romance, mystery, etc.)
- Interactive Stories: Choose-your-own-adventure style musical narratives
- Story Collections: Curated collections of related musical stories
- Story Sharing: Share generated stories with friends and community
- Collaborative Narratives: Co-create stories with other users
- Story Competitions: Community challenges for best musical narratives
- Story Analytics: Insights into popular story themes and preferences
- Spotify Integration: Direct playback with synchronized storytelling
- Podcast Integration: Generate story-driven music podcasts
- Visual Storytelling: AI-generated images to accompany musical narratives
- Multi-language Support: Stories in multiple languages
- GraphQL API: More efficient data fetching for complex stories
- Real-time Collaboration: WebSocket-based live story editing
- Progressive Web App: Offline story reading and music discovery
- Machine Learning: Improved story personalization over time
- Fork the repository and create a feature branch
- Follow coding standards and storytelling design principles
- Test thoroughly, especially storytelling workflows
- Document changes with clear, narrative-style descriptions
- Submit pull requests with compelling story about the improvement
- Python: PEP 8, comprehensive type hints, storytelling-focused docstrings
- JavaScript: ESLint, Prettier, JSDoc with narrative descriptions
- CSS: Tailwind utilities with storytelling-themed custom classes
- Git: Conventional commits with descriptive storytelling metaphors
# Install development tools
pip install pre-commit
pre-commit install
# Recommended IDE: VS Code with extensions:
# - Python, React, Tailwind CSS
# - Storytelling-focused extensions for markdown and documentationBeatTeller is developed for the Qloo LLM Hackathon 2025. Please refer to the hackathon terms and conditions for specific licensing and usage guidelines.
- Qloo: For providing the revolutionary taste intelligence API that powers our music discovery
- Google: For Gemini AI capabilities that bring our musical stories to life
- Open Source Community: For the incredible libraries and tools that make BeatTeller possible
- shadcn/ui: For elegant, accessible UI components that enhance our storytelling interface
- Tailwind CSS: For the utility-first CSS framework that styles our narratives
- Backend: Python, Flask, SQLAlchemy, Requests, AI integration libraries
- Frontend: React, Vite, Tailwind CSS, Framer Motion, shadcn/ui
- AI Services: Qloo API for music intelligence, Google Gemini AI for storytelling
- Development Tools: Git, pnpm, ESLint, Prettier, pytest, Docker
BeatTeller - Where Every Beat Tells a Story 🎵📖✨
Crafted with passion for the Qloo LLM Hackathon 2025
Transform your musical journey into unforgettable stories. Discover the narrative thread that connects your favorite beats, and let AI weave them into tales that resonate with your soul.