Streamystats

Streamystats is a statistics service for Jellyfin, providing analytics and data visualization. 📈 Built with modern advanced frameworks.

This is a personal hobby project, so please don't expect rapid development. Even though I am a full-time experienced developer, this project is prone to bugs, and I am using AI-assisted development for tasks ranging from PR reviews to refactoring and coding new features.

Features

• Dashboard with overview statistics, live sessions, recommendations, and more
• User-specific watch history and statistics
• Library statistics
• Watch time graphs with advanced filtering
• Client statistics
• Multi-server and user support
• AI chat with your library and get watch recommendations
• Embedding supported watch recommendations
• Supported by Janitorr (beta)
• Import data from Jellystat and Playback Reporting Plugin to get started

Embeddings

Library items are embedded using OpenAI-compatible APIs if enabled, supporting multiple models and custom configurations. Embeddings are stored in vectorchord with support for any dimension, allowing you to use any embedding model. The system automatically creates vector indexes optimized for similarity search.

AI Chat

Interactive chat interface. Supports multiple providers out of the box with any OpenAI-compatible API.

The chat includes function calling with 13 specialized tools:

• Personalized recommendations based on watch history
• Semantic library search using embeddings
• Watch statistics and most-watched content
• Shared recommendations for multiple users
• Genre filtering and top-rated items
• Recently added content discovery

AI Recommendations

Recommendations use vector similarity (cosine distance) to find content similar to your watch history. The system analyzes your viewing patterns and suggests movies and series. Each recommendation includes explanations showing which watched items led to the suggestion.

Roadmap

• Individual item statistics
• More statistics
• Only sync certain libraries
• More AI tools for better chat

Getting started

Playback reporting plugin is no longer needed and Streamystats solely relies on the Jellyfin API for statistics.

Docker

1. Install Docker and Docker Compose if you haven't already.
2. Copy the docker-compose.yml file to your desired location. Use tag :latest (read more below in Version Tags).
3. Change any ports if needed. Default web port is 3000.
4. Change the SESSION_SECRET in the docker-compose.yml file to a random string. You can generate one with openssl rand -hex 64.
5. Start the application with docker-compose up -d
6. Open your browser and navigate to http://localhost:3000
7. Follow the setup wizard to connect your Jellyfin server.

First time load can take a while, depending on the size of your library.

Version Tags

Version tags (e.g., v1.2.3) are automatically generated on release. These tags provide stable, tested reference points for production use. I recommend pinning to specific version tags for stability.

The :latest tag always points to the latest commit on the main branch. It contains the most recent features and fixes. While typically stable, it may occasionally contain breaking changes.

Rollbacks / Downgrades (Docker)

Database migrations are automated and handled by the job-server container (it runs migrations on startup before becoming healthy).

Streamystats does not perform automatic rollbacks/downgrades of the database schema for Docker users.

• No Automatic Downgrade: If you downgrade the Docker image version (for example changing the tag from v1.95.0 back to v1.94.0), the database remains migrated to the newer version. The older application version will likely fail to start or behave incorrectly because it does not understand the newer schema.
• Recommended Strategy: The official and only supported method to “rollback” a deployment is to restore a database backup.
• Important: Always take a database backup before updating to a newer image version.

Dockerless

Docker is currently the easiest and recommended way to run streamystats. However you can also run without docker.

See the documentation

Screenshots

Tech Stack

• Frontend: Next.js, React, TypeScript
• Backend: Hono with Bun v1.3
• Database: vectorchord (used for embeddings)
• Containerization: Docker