CineBot 🎬

A modern Android application that combines Jellyfin media server integration with AI-powered movie recommendations. CineBot allows users to search and discover movies from their Jellyfin library using natural language queries and voice search capabilities.

Features

🎯 Core Functionality

• Jellyfin Integration: Connect to your Jellyfin media server to browse your movie library
• AI-Powered Search: Use natural language queries to find movies with intelligent recommendations
• Voice Search: Search for movies using voice commands
• Smart Filtering: Advanced filtering and search capabilities with AI assistance
• Direct Playback: Start playing movies directly on your Jellyfin devices

🎨 User Interface

• Modern Material Design 3: Beautiful, intuitive interface following Material Design principles
• Dark/Light Mode: Toggle between dark and light themes
• Multilingual Support: Available in English and Spanish
• Responsive Design: Optimized for various screen sizes and orientations
• Classical Styling: Elegant gradient backgrounds and typography

⚡ Performance Features

• Intelligent Caching: Movies are cached locally for faster loading
• Memory Optimization: Efficient memory management with automatic cache clearing
• Background Processing: Non-blocking UI with coroutines for smooth performance
• Optimized Network Calls: Efficient API communication with proper error handling

Screenshots

Main Interface

Configuration Screen

Technical Stack

🛠️ Technologies Used

• Kotlin: Primary programming language
• Jetpack Compose: Modern declarative UI framework
• Material Design 3: Latest Material Design components
• OkHttp: HTTP client for API communication
• Gson: JSON parsing and serialization
• Coroutines: Asynchronous programming
• SharedPreferences: Local data persistence

📱 Platform Requirements

• Minimum SDK: API 26 (Android 8.0)
• Target SDK: API 36 (Android 14)
• Compile SDK: API 36
• Java Version: 17

Setup & Configuration

Prerequisites

1. Jellyfin Server: A running Jellyfin media server
2. OpenRouter API Key: For AI-powered recommendations
3. Android Device: Running Android 8.0 or higher

Installation

1. Clone the repository
2. Open the project in Android Studio
3. Build and run the application

Configuration Steps

1. Jellyfin Setup

1. Open the app and navigate to Settings
2. Enter your Jellyfin server URL (e.g., http://192.168.1.100:8096)
3. Add your Jellyfin API key
4. Test the connection

2. OpenRouter AI Setup

1. Get an API key from OpenRouter
2. Enter the API key in the settings
3. Select your preferred AI model (default: deepseek/deepseek-chat:free)

3. Device Selection

1. Choose your preferred Jellyfin playback device
2. The app will automatically detect available devices

Usage

Basic Search

1. Use the search bar to enter movie queries
2. Type natural language descriptions like "sci-fi movies from the 80s"
3. View AI-powered recommendations

Voice Search

1. Tap the microphone icon
2. Speak your movie request
3. The app will process your voice input and search accordingly

Movie Playback

1. Select a movie from the search results
2. Choose your playback device
3. Tap the play button to start streaming

Advanced Features

• Refresh: Pull to refresh your movie library
• Load More: Infinite scrolling for large libraries
• Filtering: Use AI to filter movies by genre, year, or other criteria

Architecture

Project Structure

app/src/main/java/pe/canica/cinebot/
├── components/          # Reusable UI components
├── screens/            # Main application screens
├── ui/theme/           # Theme and styling
├── utils/              # Utility functions
├── JellyfinService.kt  # Jellyfin API integration
├── OpenRouterService.kt # AI service integration
├── Movie.kt           # Data models
└── MainActivity.kt    # Main activity

Key Components

Services

• JellyfinService: Handles communication with Jellyfin server
• OpenRouterService: Manages AI-powered recommendations
• SpeechRecognitionHelper: Voice search functionality

Screens

• MovieSearchScreen: Main search and discovery interface
• ConfigurationScreen: Settings and configuration management

State Management

• MovieSearchState: Manages search state and movie data
• Reactive UI: Real-time updates using Compose state

Permissions

The application requires the following permissions:

• Internet: For API communication with Jellyfin and OpenRouter
• Record Audio: For voice search functionality

Performance Optimizations

Caching Strategy

• Movies are cached locally for 1 hour
• Automatic cache invalidation on memory pressure
• Efficient JSON serialization with Gson

Memory Management

• Hardware acceleration enabled
• Automatic cache clearing on low memory
• Optimized image loading and display

Network Optimization

• Connection timeouts configured
• Efficient API field selection
• Error handling and retry mechanisms

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and feature requests, please create an issue in the repository.