193 lines
5.0 KiB
Markdown
193 lines
5.0 KiB
Markdown
# 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) |