Jellycleanarr

A Terminal User Interface (TUI) for viewing Jellyfin media playback statistics. Jellycleanarr connects to your Jellyfin server and displays detailed analytics about media consumption across users, series, and libraries.

Features

• User Statistics: View most and least active users with play counts and watch duration
• Series Statistics: See which series and movies are most/least watched
• Library Statistics: Analyze playback activity across your media libraries
• Tabbed Interface: Easy navigation between different stat views
• Real-time Data: Refresh statistics on demand with a single keypress
• Modern TUI: Beautiful terminal interface powered by Textual

Requirements

• Python 3.10 or higher
• Jellyfin server with the Playback Reporting Plugin installed
• Jellyfin API key

Installation

Using Poetry (Recommended)

# Clone the repository
git clone https://github.com/yourusername/jellycleanarr.git
cd jellycleanarr

# Install dependencies
poetry install

# Run the application
poetry run jellycleanarr

Using pip

# Clone the repository
git clone https://github.com/yourusername/jellycleanarr.git
cd jellycleanarr

# Install dependencies
pip install -e .

# Run the application
jellycleanarr

Configuration

1. Copy the example environment file:

   cp .env.example .env
   

2. Edit .env and configure your Jellyfin settings:

   JELLYFIN_ADDRESS=https://your-jellyfin-server.com
   JELLYFIN_API_KEY=your_api_key_here
   

Getting a Jellyfin API Key

1. Open your Jellyfin web interface
2. Go to Dashboard → API Keys
3. Click "+" to create a new API key
4. Give it a name (e.g., "Jellycleanarr")
5. Copy the generated key to your .env file

Usage

Run the application:

# With Poetry
poetry run jellycleanarr

# With pip install
jellycleanarr

# As a Python module
python -m jellycleanarr

Keyboard Shortcuts

• 1 - Switch to User Statistics tab
• 2 - Switch to Series Statistics tab
• 3 - Switch to Library Statistics tab
• r - Refresh current tab data
• q - Quit application
• Tab - Navigate between tabs
• Arrow keys - Navigate within tables

Features by Tab

User Statistics Tab

• Most Active Users: Users with the highest play counts
• Least Active Users: Users with the lowest play counts
• Displays: Username, total plays, watch duration, unique items watched

Series Statistics Tab

• Most Watched Series: Series/movies with the highest play counts
• Least Watched Series: Series/movies with the lowest play counts
• Displays: Title, total plays, watch duration, unique users

Library Statistics Tab

• Most Active Libraries: Libraries with the highest playback activity
• Least Active Libraries: Libraries with the lowest playback activity
• Displays: Library name, total plays, watch duration, unique users, item count

Development

Project Structure

jellycleanarr/
├── src/jellycleanarr/
│   ├── api/              # Jellyfin API client
│   ├── models/           # Data models
│   ├── services/         # Business logic
│   ├── ui/               # TUI components
│   │   ├── screens/      # App screens
│   │   ├── widgets/      # UI widgets
│   │   └── styles/       # CSS styling
│   └── utils/            # Utility functions
├── tests/                # Test suite
└── pyproject.toml        # Project dependencies

Running Tests

poetry run pytest

Code Formatting

# Format code with Black
poetry run black src/

# Lint with Ruff
poetry run ruff check src/

# Type checking with mypy
poetry run mypy src/

Troubleshooting

Connection Errors

If you get connection errors:

1. Verify JELLYFIN_ADDRESS is correct and includes https:// or http://
2. Check that your Jellyfin server is accessible
3. Ensure the API key is valid

Authentication Errors

If authentication fails:

1. Verify your API key is correct
2. Check that the API key hasn't been revoked in Jellyfin
3. Try creating a new API key

No Data Displayed

If statistics don't show:

1. Ensure the Playback Reporting Plugin is installed and enabled
2. Check that there is playback activity recorded in your Jellyfin server
3. Try refreshing the data with the r key

Dependencies

• Textual - Modern TUI framework
• httpx - Async HTTP client
• Pydantic - Data validation
• python-dotenv - Environment variable management

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Built with Textual
• Integrates with Jellyfin
• Uses the Jellyfin Playback Reporting Plugin