CineBot is an intelligent voice-driven movie discovery assistant powered by SignalWire AI Agents and The Movie Database (TMDB). Have natural conversations to explore movies, actors, and get personalized recommendations with a beautiful Netflix-style visual interface.
DEMO https://cinebot.signalwire.me/
- Natural Language Understanding: Talk to CineBot like you would a movie-loving friend
- Real-time Voice Response: Get instant spoken responses with ElevenLabs voice synthesis
- Video Presence: See CineBot's animated avatar during conversations
- Context-Aware Conversations: CineBot remembers what you're discussing and maintains context
- Smart Search: Search movies by title with automatic year filtering
- "Show me Pretty Woman from 1990"
- "Find Top Gun from 1986"
- Trending Movies: Discover what's popular this week or today
- Genre Browsing: Explore movies by genre (action, comedy, horror, drama, sci-fi, romance)
- Personalized Recommendations: Get similar movie suggestions based on what you're viewing
- Detailed Information:
- Cast and crew details with photos
- Plot summaries and taglines
- Release dates and runtimes
- User ratings from TMDB
- Content ratings (G, PG, PG-13, R, NC-17)
- Streaming availability (Netflix, Amazon Prime, Disney+, etc.)
- Actor/Director Search: Find information about actors, directors, and crew
- Complete Filmographies: Browse all movies a person has worked on
- Biography Information: Learn about the person's background
- Known For: See their most popular works
- Visual Profiles: High-quality photos and headshots
- ID-Based Selection: CineBot uses movie and person IDs for precise selection
- Multi-Result Handling: When multiple matches are found, CineBot presents options
- Watchlist Management: Add movies to your personal watchlist
- Automatic Trailers: Watch trailers directly in the interface
- Visual Placeholders: Elegant placeholders for missing images
- Netflix-Style Design: Beautiful dark theme with smooth animations
- Responsive Layouts: Adapts to different screen sizes
- Rich Media Display:
- High-quality movie posters
- Backdrop images with gradient overlays
- Cast photo carousels
- Streaming provider logos
- Smart Positioning: Agent video moves to corner when displaying content
- Clean Transitions: Smooth animations and display clearing between views
- SignalWire AI Agents SDK: Core framework for voice AI capabilities
- TMDB Integration: Complete movie database access via tmdbsimple
- Redis Caching: Fast response times with intelligent caching
- State Management: Context-aware conversation flow with state machines
- SWAIG Functions: Specialized functions for movie operations
- Event System: One-way event flow from backend to frontend
- WebRTC Video/Audio: Real-time communication with SignalWire
- Dynamic UI Updates: Event-driven interface updates
- Responsive Design: Mobile-friendly layouts
- Modern CSS: Custom properties, animations, and gradients
- Python 3.8+
- Redis server (optional, for caching)
- TMDB API key (get one at https://www.themoviedb.org/settings/api)
- SignalWire account (for production deployment)
- Clone the repository
git clone https://github.com/signalwire/sigmond-cinebot.git
cd sigmond-cinebot- Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- Install dependencies
pip install -r requirements.txt- Set environment variables
export TMDB_API_KEY="your_tmdb_api_key"
export REDIS_URL="redis://localhost:6379/0" # Optional
export PORT=3030 # Optional, defaults to 3030- Run the application
python cinebot_agent.py- Access the interface
Open your browser to
http://localhost:3030
- Click "Connect to CineBot" button
- Allow microphone and camera permissions
- Start talking to CineBot!
Finding Movies:
- "Show me trending movies"
- "Search for Pretty Woman from 1990"
- "Find action movies"
- "What movies are similar to Top Gun?"
Getting Details:
- "Tell me about the first one"
- "Show me more details"
- "Who's in the cast?"
- "Where can I watch this?"
Exploring People:
- "Search for Tom Cruise"
- "Show me movies with Julia Roberts"
- "Tell me about the director"
Navigation:
- "Go back to trending"
- "Clear the display"
- "Show me something else"
CineBot understands natural language, so speak naturally! The system recognizes:
- Direct requests: "Show me Star Wars"
- Contextual references: "Tell me about the second one"
- Follow-up questions: "Who directed it?"
- Navigation: "Go back", "Show trending again"
| Function | Description | Parameters |
|---|---|---|
search_movie |
Search for movies by title | query (with optional year) |
get_movie_details |
Get detailed movie information | movie_id, movie_title, or search_position |
search_person |
Search for actors/directors | query, person_id, or search_position |
get_trending |
Get trending movies | time_window (day/week) |
get_movies_by_genre |
Browse by genre | genre_name |
add_to_watchlist |
Add movie to watchlist | movie_id |
clear_display |
Clear the current display | None |
Events flow one-way from backend to frontend:
| Event | Description | Data |
|---|---|---|
movie_search_results |
Movie search results | TMDB search results |
movie_details |
Detailed movie info | Movie details + cast + providers |
person_details |
Person information | Person details + filmography |
person_search_results |
Person search results | TMDB person results |
trending_movies |
Trending movies list | TMDB trending results |
genre_movies |
Movies by genre | Genre name + movies |
clear_display |
Clear all displays | Empty |
| Variable | Description | Default |
|---|---|---|
TMDB_API_KEY |
TMDB API key (required) | None |
REDIS_URL |
Redis connection URL | redis://localhost:6379/0 |
REDIS_TTL |
Cache TTL in seconds | 3600 |
PORT |
Server port | 3030 |
HOST |
Server host | 0.0.0.0 |
SWML_BASIC_AUTH_USER |
Basic auth username | Auto-generated |
SWML_BASIC_AUTH_PASSWORD |
Basic auth password | Auto-generated |
Voice Settings (in cinebot_agent.py):
self.add_language(
name="English",
code="en-US",
voice="elevenlabs.adam" # Change voice here
)UI Theme (in web/styles.css):
- CSS custom properties for colors
- Easily customizable gradients and animations
- Responsive breakpoints
CineBot uses a state machine with four main states:
- greeting: Initial state, ready for first request
- browsing: Viewing search results or lists
- movie_details: Viewing specific movie information
- person_details: Viewing person information
Each state has specific allowed functions and valid transitions.
sigmond-cinebot/
├── cinebot_agent.py # Main AI agent implementation
├── tmdb_client.py # TMDB API client with caching
├── requirements.txt # Python dependencies
├── web/
│ ├── index.html # Main HTML interface
│ ├── app.js # Frontend JavaScript
│ └── styles.css # CSS styles
├── cinebot_idle.mp4 # Agent idle animation
├── cinebot_talking.mp4 # Agent talking animation
└── README.md # This file
- New SWAIG Function: Add to
_setup_functions()incinebot_agent.py - New Event Type: Add handler in
handleAgentEvent()inapp.js - New Display Mode: Create display function in
app.js - New State: Add to state machine in
cinebot_agent.py
# Run with debug logging
python cinebot_agent.py
# Test TMDB connection
python -c "from tmdb_client import TMDBClient; client = TMDBClient(); print(client.search_movie('Star Wars'))"
# Monitor Redis cache
redis-cli MONITOR- Set up SignalWire account
- Configure environment variables
- Deploy to SignalWire-compatible hosting
- Update webhook URLs in SignalWire dashboard
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "cinebot_agent.py"]"401 Unauthorized" errors
- Check basic auth credentials in startup logs
- Verify SignalWire configuration
No movies displaying
- Check browser console for JavaScript errors
- Verify TMDB API key is valid
- Check Redis connection
Voice not working
- Ensure microphone permissions granted
- Check WebRTC connection in browser console
- Verify SignalWire credentials
Display not clearing properly
- Hard refresh browser (Ctrl+Shift+R)
- Check for JavaScript errors
- Verify event handlers are registered
- Automatically parses year from queries like "Pretty Woman from 1990"
- Filters results to match the specified year
- Provides clear feedback when movies from specific years aren't found
- All search results now include movie/person IDs in the response text
- Format:
"id: 114 title: 'Pretty Woman' (1990)" - Enables precise selection without ambiguity
- All display functions properly clear previous content
- Prevents overlapping or stuck displays
- Smooth transitions between different views
- Proper basic auth setup with auto-generated credentials
- Credentials displayed on startup for easy access
- Secure WebRTC communication
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly
- Submit a pull request
MIT License - See LICENSE file for details
- SignalWire - AI Agent platform and WebRTC infrastructure
- The Movie Database (TMDB) - Movie data and images
- ElevenLabs - Voice synthesis
- Redis - Caching layer
- Holy Guacamole - Architecture inspiration
For issues, questions, or suggestions:
- Open an issue on GitHub
- Contact the development team
- Check the SignalWire documentation
Built with ❤️ for movie lovers everywhere