# 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](https://github.com/jellyfin/jellyfin-plugin-playbackreporting) installed
- Jellyfin API key

## Installation

### Using Poetry (Recommended)

```bash
# 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

```bash
# 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:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` and configure your Jellyfin settings:
   ```bash
   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:

```bash
# 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

```bash
poetry run pytest
```

### Code Formatting

```bash
# 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](https://textual.textualize.io/) - Modern TUI framework
- [httpx](https://www.python-httpx.org/) - Async HTTP client
- [Pydantic](https://pydantic-docs.helpmanual.io/) - Data validation
- [python-dotenv](https://github.com/theskumar/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](https://textual.textualize.io/)
- Integrates with [Jellyfin](https://jellyfin.org/)
- Uses the [Jellyfin Playback Reporting Plugin](https://github.com/jellyfin/jellyfin-plugin-playbackreporting)