📺 Background TV Genie

Smart TV show recommendations designed specifically for background viewing. Tell the app what you're doing (laundry, coding, cooking, etc.) and it will recommend the perfect shows based on your mood, available time, and streaming subscriptions.

Features

• Smart Text Analysis: Automatically detects mood and viewing constraints from natural language input
• TMDB Integration: Leverages The Movie Database API for comprehensive TV show data
• Streaming Integration: Filters recommendations by your streaming subscriptions
• Intelligent Caching: Reduces API calls with SQLite-based caching (24-hour TTL)
• User Feedback: Learn from your preferences with thumbs up/down voting
• Modern UI: Clean, responsive interface built with Tailwind CSS

Tech Stack

• Backend: FastAPI (Python 3.11+)
• Database: SQLite with SQLModel ORM
• Frontend: Jinja2 templates + Tailwind CSS (CDN)
• External API: TMDB (The Movie Database)
• HTTP Client: httpx with async support

Quick Start

1. Prerequisites

• Python 3.11 or higher
• TMDB API key (free) - Get one here

2. Installation

# Clone or download this repository
cd background-tv-genie

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

# Install dependencies
pip install -r requirements.txt

3. Configuration

# Copy the example environment file
cp .env.example .env

# Edit .env and add your TMDB API key
# TMDB_API_KEY=your_actual_api_key_here

To get a TMDB API key:

1. Create a free account at TMDB
2. Go to Settings > API
3. Request an API key (choose "Developer" option)
4. Copy the "API Read Access Token" or "API Key (v3 auth)"

4. Run the Application

# Start the development server
uvicorn app.main:app --reload

# Or using Python directly
python -m app.main

The app will be available at: http://localhost:8000

5. Verify Your Streaming Services (Optional)

# Test that your subscriptions are correctly configured
python -m scripts.verify_providers

# This will show which providers TMDB recognizes

Usage

First Time Setup

1. Navigate to Settings (top right navigation)
2. Select your streaming subscriptions (Netflix, Hulu, YouTube TV, Paramount Plus, Prime Video, Discovery Plus, Max)
3. Choose your region (default: US)
4. Click Save Settings

Note: The app supports flexible provider name matching. For example, "HBO Max" and "Max" are recognized as the same service, and "Amazon Prime Video" is matched to "Prime Video".

Getting Recommendations

1. On the home page, describe what you're doing in the text box:

   • "doing laundry"
   • "cooking dinner tonight"
   • "need something cozy while I work"
   • "background noise for deep work"

2. Optionally adjust the filters:

   • Mood: cozy, comfort, focus, energy, tech, spooky-chill
   • Noise Level: low, medium
   • Episode Length: short (<25m), standard (25-45m), long (45m+)

3. Click Find My Show

4. Browse recommendations and use 👍/👎 to provide feedback

Supported Streaming Services

• Netflix
• Hulu
• Max (HBO Max)
• Prime Video (Amazon)
• Disney Plus
• Peacock
• Paramount Plus
• Apple TV Plus
• YouTube TV
• Discovery Plus

How It Works

Recommendation Algorithm

The app uses a weighted scoring system (0.0 - 1.0):

• Genre Match (35%): How well show genres align with detected mood
• Vibe Score (20%): Popularity adjusted for desired noise level
• Episode Length (15%): Match with preferred episode duration
• Provider Availability (15%): Bonus for your subscriptions
• Popularity (10%): General show popularity
• Feedback Bias (5%): Your historical thumbs up/down votes

Mood Detection

The app analyzes your input text for keywords and activities:

• Cozy/Comfort: Comedy, reality, animation
• Focus: Documentary, reality (low noise)
• Energy: Reality, talk shows, comedy
• Tech: Documentary, talk shows
• Spooky-chill: Mystery, reality, sci-fi/fantasy

Activity-Based Hints

Certain activities automatically set optimal parameters:

Activity	Episode Length	Noise Level
Laundry	Standard	Low
Email	Short	Low
Writing	Short	Low
Cooking	Standard	Medium
Deep Work	Long	Low

Project Structure

background-tv-genie/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app and routes
│   ├── config.py            # Settings and environment variables
│   ├── db.py                # Database connection
│   ├── deps.py              # FastAPI dependencies
│   ├── models.py            # SQLModel database models
│   ├── schemas.py           # Pydantic request/response schemas
│   ├── recs.py              # Recommendation logic
│   ├── tmdb_client.py       # TMDB API client with caching
│   ├── static/
│   │   └── site.js          # Frontend JavaScript
│   └── templates/
│       ├── base.html        # Base template
│       ├── index.html       # Home page
│       ├── results.html     # Recommendations display
│       └── settings.html    # Settings page
├── tests/
│   ├── __init__.py
│   └── test_recs.py         # Recommendation logic tests
├── .env.example             # Environment variables template
├── requirements.txt         # Python dependencies
├── Dockerfile              # Docker configuration
└── README.md               # This file

Running Tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_recs.py

Docker Deployment

# Build the image
docker build -t background-tv-genie .

# Run the container
docker run -p 8000:8000 --env-file .env background-tv-genie

# Or using docker-compose
docker-compose up

API Endpoints

• GET / - Home page with recommendation form
• POST /recommend - Submit request and get recommendations
• GET /settings - Settings page
• POST /settings - Update user preferences
• POST /feedback - Submit thumbs up/down feedback (JSON)

Rate Limiting & Caching

• TMDB API: Free tier allows 10,000 requests per day
• Caching: All TMDB responses cached for 24 hours in SQLite
• Provider Map: Loaded once at startup and cached

To adjust cache TTL, modify CACHE_TTL_HOURS in .env

Development

Adding New Moods

Edit app/recs.py:

MOOD_TO_GENRES = {
    "your-mood": [genre_id_1, genre_id_2],
    # ...
}

MOOD_KEYWORDS = {
    "your-mood": ["keyword1", "keyword2"],
    # ...
}

TMDB Genre IDs:

• 35: Comedy
• 99: Documentary
• 10764: Reality
• 10767: Talk
• 16: Animation
• 9648: Mystery
• 10765: Sci-Fi & Fantasy

Adding Task Hints

TASK_HINTS = {
    "your-task": {"episode_len": "standard", "noise_level": "low"},
    # ...
}

Troubleshooting

"TMDB API key not configured"

• Ensure your .env file exists and has TMDB_API_KEY=your_key
• Restart the server after adding the key

No recommendations returned

• Check that your TMDB API key is valid
• Ensure you have an internet connection
• Check server logs for API errors
• Run python -m scripts.verify_providers to check provider configuration

Streaming service not showing up

• Run the provider verification script: python -m scripts.verify_providers
• Check if TMDB lists your provider for your region
• Provider names must match TMDB's naming (e.g., "Max" not "HBO Max")
• Some providers may not be available in TMDB's database for certain regions

Database errors

• Delete data.db file and restart (will reset all preferences)
• Check file permissions for SQLite database

License

This is a demonstration project. Please comply with TMDB Terms of Use when using their API.

Acknowledgments

• The Movie Database (TMDB) for comprehensive TV data
• FastAPI for the excellent web framework
• Tailwind CSS for beautiful styling

---

Built with ❤️ for those who need the perfect background companion.