updates

2026-02-12 00:05:42 -05:00
parent 7d86d37dea
commit 49edd5ba84
47 changed files with 4502 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,193 @@
 # Jellycleanarr

-A tui that allows you to see and delete old media
+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)