jellyfin tagger script v1
This commit is contained in:
264
README.md
Normal file
264
README.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# 🎵 Jellyfin Auto-Tagging Script
|
||||
|
||||
A Python CLI tool for tagging Jellyfin artists and albums recursively using the Jellyfin API.
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
- [Overview](#-overview)
|
||||
- [Features](#-features)
|
||||
- [Requirements](#-requirements)
|
||||
- [Installation](#-installation)
|
||||
- [Usage](#-usage)
|
||||
- [Examples](#-examples)
|
||||
- [Technical Details](#-technical-details)
|
||||
- [Troubleshooting](#-troubleshooting)
|
||||
- [License](#-license)
|
||||
- [Authors](#-authors)
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
This script automates the process of adding tags to Jellyfin music artists and their albums. It's designed to be simple, efficient, and safe, with a dry-run mode to preview changes before applying them.
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- **Recursive Tagging**: Tags an artist and all their albums with a single command
|
||||
- **Dry Run Mode**: Preview changes without making modifications
|
||||
- **Tag Preservation**: Merges new tags with existing ones (no duplicates)
|
||||
- **Username/Password Auth**: Uses Jellyfin credentials (no API key required)
|
||||
- **Comprehensive Error Handling**: Clear success/failure reporting
|
||||
- **Minimal Dependencies**: Only requires Python and `requests` library
|
||||
|
||||
## 📦 Requirements
|
||||
|
||||
- Python 3.6+
|
||||
- `requests` library (`pip install requests`)
|
||||
- Jellyfin Server 10.11.5+
|
||||
- User account with write permissions
|
||||
|
||||
## 🔧 Installation
|
||||
|
||||
### 1. Clone or Download
|
||||
|
||||
```bash
|
||||
# Clone the repository (if available)
|
||||
git clone https://github.com/your-repo/jellyfin-autotag.git
|
||||
cd jellyfin-autotag
|
||||
|
||||
# Or download just the script
|
||||
wget https://raw.githubusercontent.com/your-repo/jellyfin-autotag/main/tag_artist.py
|
||||
chmod +x tag_artist.py
|
||||
```
|
||||
|
||||
### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
pip install requests
|
||||
```
|
||||
|
||||
### 3. Make Executable
|
||||
|
||||
```bash
|
||||
chmod +x tag_artist.py
|
||||
```
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
```bash
|
||||
./tag_artist.py --server SERVER_URL --username USERNAME --password PASSWORD \
|
||||
--artist-id ARTIST_ID --tag TAG_NAME [--dry-run]
|
||||
```
|
||||
|
||||
### Command Line Arguments
|
||||
|
||||
| Argument | Required | Description | Example |
|
||||
|----------|----------|-------------|---------|
|
||||
| `--server` | ✅ Yes | Jellyfin server URL | `http://localhost:8096` |
|
||||
| `--username` | ✅ Yes | Jellyfin username | `username` |
|
||||
| `--password` | ✅ Yes | Jellyfin password | `password123` |
|
||||
| `--artist-id` | ✅ Yes | Artist ID to tag | `artistidxxxxxxxxxxxxxxxxxx` |
|
||||
| `--tag` | ✅ Yes | Tag to apply | `yourtag` |
|
||||
| `--dry-run` | ❌ No | Dry run mode (no changes) | (flag only) |
|
||||
|
||||
## 📚 Examples
|
||||
|
||||
### 1. Dry Run (Safe Preview)
|
||||
|
||||
```bash
|
||||
./tag_artist.py --server http://10.11.12.13:8096 \
|
||||
--username admin \
|
||||
--password hBBOmvfsRYvgn0DIfd34 \
|
||||
--artist-id b32224387e37aae08d962f71f7272c6c \
|
||||
--tag "electronic-favorite" \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
🎯 Jellyfin Artist Tagger
|
||||
📡 Server: http://10.11.12.13:8096
|
||||
👤 Artist ID: b32224387e37aae08d962f71f7272c6c
|
||||
🏷️ Tag: electronic-favorite
|
||||
🔄 DRY RUN MODE - No changes will be made
|
||||
|
||||
🎵 Fetching artist information...
|
||||
🎤 Artist: Goldfrapp
|
||||
🏷️ Tagging artist...
|
||||
[DRY RUN] Would tag artist 'Goldfrapp' with 'electronic-favorite'
|
||||
💿 Fetching albums...
|
||||
📚 Found 10 albums:
|
||||
[DRY RUN] Would tag album 'Silver Eye' with 'electronic-favorite'
|
||||
[DRY RUN] Would tag album 'Seventh Tree' with 'electronic-favorite'
|
||||
...
|
||||
🎉 Dry run completed! Would tag artist and 10 albums with 'electronic-favorite'
|
||||
```
|
||||
|
||||
### 2. Actual Tagging
|
||||
|
||||
```bash
|
||||
./tag_artist.py --server http://your.jellyfin.url \
|
||||
--username yourusername \
|
||||
--password yourpassword \
|
||||
--artist-id artistidxxxxxxxxxxxxxx \
|
||||
--tag "yourtag"
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
🎯 Jellyfin Artist Tagger
|
||||
📡 Server: http://your.jellyfin.url
|
||||
👤 Artist ID: artistidxxxxxxxxxxxxxx
|
||||
🏷️ Tag: yourtag
|
||||
⚠️ LIVE MODE - Changes will be made
|
||||
|
||||
🎵 Fetching artist information...
|
||||
🎤 Artist: Artist name
|
||||
🏷️ Tagging artist...
|
||||
✅ Tagged artist 'Goldfrapp' with 'yourtag'
|
||||
💿 Fetching albums...
|
||||
📚 Found 10 albums:
|
||||
✅ Tagged album 'Album name' with 'yourtag'
|
||||
✅ Tagged album 'Album name 2' with 'yourtag'
|
||||
...
|
||||
🎉 Completed! Tagged artist and 10/10 albums with 'yourtag'
|
||||
```
|
||||
|
||||
## 🔍 Technical Details
|
||||
|
||||
### Authentication
|
||||
|
||||
The script uses Jellyfin's username/password authentication to obtain an access token:
|
||||
|
||||
```python
|
||||
# Authentication flow
|
||||
1. POST to /Users/AuthenticateByName with username/password
|
||||
2. Receive access token and user ID
|
||||
3. Use token for all subsequent API calls
|
||||
```
|
||||
|
||||
### API Endpoints Used
|
||||
|
||||
- `POST /Users/AuthenticateByName` - Authentication
|
||||
- `GET /Items/{id}` - Fetch artist/album details
|
||||
- `POST /Items/{id}` - Update tags
|
||||
|
||||
### Data Format
|
||||
|
||||
The script sends complete artist/album objects matching the Jellyfin UI format:
|
||||
|
||||
```json
|
||||
{
|
||||
"Id": "artist-id",
|
||||
"Name": "Artist Name",
|
||||
"Tags": ["tag1", "tag2"],
|
||||
"Genres": ["Genre1", "Genre2"],
|
||||
"ProviderIds": {},
|
||||
"DateCreated": "2019-01-08T09:19:41.000Z",
|
||||
"LockData": false,
|
||||
"LockedFields": []
|
||||
// ... all other metadata fields
|
||||
}
|
||||
```
|
||||
|
||||
### Tag Merging Logic
|
||||
|
||||
```python
|
||||
# Preserve existing tags and add new ones
|
||||
existing_tags = set(current_item.get('Tags', []))
|
||||
new_tags = set(tags)
|
||||
merged_tags = list(existing_tags.union(new_tags))
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### 1. Authentication Failed
|
||||
|
||||
**Error:** `❌ Authentication failed: 401 Unauthorized`
|
||||
|
||||
**Solution:**
|
||||
- Verify username and password
|
||||
- Check if user has API access permissions
|
||||
- Ensure server URL is correct
|
||||
|
||||
#### 2. Artist Not Found
|
||||
|
||||
**Error:** `❌ Could not fetch artist information`
|
||||
|
||||
**Solution:**
|
||||
- Verify artist ID is correct
|
||||
- Check if artist exists in your library
|
||||
- Use dry run to test connectivity
|
||||
|
||||
#### 3. Tagging Failed
|
||||
|
||||
**Error:** `❌ Failed to tag artist/album`
|
||||
|
||||
**Solution:**
|
||||
- Check Jellyfin server logs for details
|
||||
- Ensure user has write permissions
|
||||
- Verify Jellyfin version compatibility
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
1. **Use dry run first**: Always test with `--dry-run` before making changes
|
||||
2. **Check server logs**: Look for detailed error information
|
||||
3. **Test with different artists**: Rule out data-specific issues
|
||||
4. **Verify network connectivity**: Ensure script can reach the server
|
||||
|
||||
## 📜 License
|
||||
|
||||
This project is open-source and available under the **MIT License**.
|
||||
|
||||
## 👥 Authors
|
||||
|
||||
**Bach** - Initial development and implementation
|
||||
|
||||
**Mistral AI** - Assistance and optimization
|
||||
|
||||
## 🎉 Success Story
|
||||
|
||||
This script was developed to automate the tedious process of manually tagging artists and albums in Jellyfin. What started as a simple Python CLI tool evolved into a robust solution that:
|
||||
|
||||
- ✅ Successfully tags artists and albums recursively
|
||||
- ✅ Preserves all existing metadata
|
||||
- ✅ Provides safe dry-run functionality
|
||||
- ✅ Handles errors gracefully
|
||||
- ✅ Matches Jellyfin UI behavior exactly
|
||||
|
||||
**Result:** A production-ready tool that saves hours of manual tagging work! 🎊
|
||||
|
||||
## 📬 Contact
|
||||
|
||||
For questions, issues, or contributions, please open an issue on the GitHub repository.
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- Jellyfin team for creating an amazing media server
|
||||
- Python community for the excellent `requests` library
|
||||
- All open-source contributors who make tools like this possible
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** February 13, 2026
|
||||
**Version:** 1.0.0
|
||||
Reference in New Issue
Block a user