Skip to content

Update SETTINGS.md #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
drolex2 wants to merge 3 commits into from
Closed

Update SETTINGS.md #8

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b263ce3
Update SETTINGS.md
drolex2 Aug 30, 2025
2063440
Update SETTINGS.md
drolex2 Aug 30, 2025
6e9c5db
Update SETTINGS.md
drolex2 Aug 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 47 additions & 33 deletions SETTINGS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,22 +36,31 @@ Override environment variables through the web interface at `http://localhost:50

## 🎯 Essential Settings

### Jellyfin Connection
### Jellyfin Server Configuration
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `JELLYFIN_URL` | Your Jellyfin server URL | ✅ Yes | - |
| `JELLYFIN_URL` | Your Jellyfin server URL | ✅ Yes | http://jellyfin:8096 |
| `JELLYFIN_API_KEY` | Jellyfin API key with media access | ✅ Yes | - |
| `PLAYLIST_DIR_HOST` | Path to Jellyfin playlists on host | ✅ Yes | ./jellyfin/config/data/playlists |
| `MUSIC_DIR_HOST` | Path to music on host | No | - |
| `MUSIC_DIR_CONTAINER` | Path to music in Jellyfin container | No | - |

**Example:**
```bash
JELLYFIN_URL=https://jellyfin.example.com
JELLYFIN_API_KEY=your_32_character_api_key_here
PLAYLIST_DIR_HOST=/host/path/to/jellyfin/config/data/playlists
MUSIC_DIR_HOST=/host/path/to/music
MUSIC_DIR_CONTAINER=/jellyfin/container/path/to/music
```
**Notes:**
- `PLAYLIST_DIR_HOST` - JellyJams needs direct R/W access to Jellyfin's playlists directory.
- `MUSIC_DIR_HOST` - Read-only access to you Jellyfin music library is needed if you want Jellyjams to pull artwork from there.
- `MUSIC_DIR_CONTAINER` - The music needs to be mapped to the same directory in the container as it is in Jellyfin. This is because JellyJams gets the path of music sub-directories from the Jellyfin API, which provides the path as it is in the Jellyfin container.

### Container Settings
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `PLAYLIST_FOLDER` | Container directory for playlists | No | `/app/playlists` |
| `ENABLE_WEB_UI` | Enable web interface | No | `true` |
| `WEB_PORT` | Web UI port | No | `5000` |
| `LOG_LEVEL` | Logging verbosity | No | `INFO` |
Expand Down Expand Up @@ -190,14 +199,6 @@ For artist playlists, JellyJams automatically generates professional covers:
| **Quality** | High-resolution PNG/JPG |
| **Color Analysis** | Automatic brightness detection for optimal contrast |

#### Music Directory Integration
JellyJams searches these paths for artist folders:
- `/mnt/user/media/data/music/[Artist]/` (Unraid)
- `/app/music/[Artist]/`
- `/music/[Artist]/`
- `/media/[Artist]/`
- `/data/music/[Artist]/`

#### Supported Cover Files
- `folder.jpg`, `folder.jpeg`, `folder.png`
- `cover.jpg`, `cover.jpeg`, `cover.png`
Expand All @@ -206,11 +207,11 @@ JellyJams searches these paths for artist folders:

### 📁 Predefined Custom Covers

Place custom images in your cover directory (mapped to `/app/cover/`):
Place custom images in your appdata/cover directory (mapped to `/data/cover/`):

#### Directory Structure Examples
```
/app/cover/
/data/cover/
├── Top Tracks - Jonas.jpg # Personal playlist (specific user)
├── Top Tracks - all.jpg # Personal playlist (generic fallback)
├── Discovery Mix - Sarah.webp # Personal playlist (specific user)
Expand All @@ -234,7 +235,7 @@ Place custom images in your cover directory (mapped to `/app/cover/`):

### 🔄 Update Covers Feature

Refresh cover art for existing playlists without regenerating them:
Refresh cover art for existing playlists without regenerating playlists:

#### Web UI Usage
1. Navigate to **Playlists** page (`/playlists`)
Expand All @@ -250,7 +251,7 @@ Refresh cover art for existing playlists without regenerating them:
- **Error Handling**: Graceful fallbacks with detailed logging

#### When to Use
- After adding new cover art files to `/app/cover/`
- After adding new cover art files to `/data/cover/`
- When Spotify integration settings change
- After updating music library with new artist folders
- To fix missing or corrupted cover art
Expand Down Expand Up @@ -290,19 +291,19 @@ Refresh cover art for existing playlists without regenerating them:
```

#### Predefined Covers Not Loading
**Symptoms**: Custom covers in `/app/cover/` are ignored
**Symptoms**: Custom covers in `/data/cover/` are ignored

**Solutions**:
1. **Verify Docker Volume Mount**:
```yaml
volumes:
- /host/path/covers:/app/cover # Must be mounted
- /host/path/appdata:/data # Must be mounted
```

2. **Check File Permissions**:
```bash
# Ensure container can read cover files
ls -la /host/path/covers/
ls -la /host/path/appdata/covers/
```

3. **Verify Exact Naming**:
Expand Down Expand Up @@ -418,26 +419,32 @@ The web UI settings page (`/settings`) provides:
### Required Volumes
```yaml
volumes:
- /host/path/playlists:/app/playlists # Playlist storage
- /host/path/logs:/app/logs # Application logs
- /host/path/config:/app/config # Web UI settings
# JellyJames app data (config, logs, cover art)
- /host/path/appdata:/data
# Jellyfin playlists directory for playlist and art management
- ${PLAYLIST_DIR_HOST}:/playlists
```

### Optional Volumes
```yaml
volumes:
- /host/path/covers:/app/cover # Custom cover art
# Ready-only access to music directory for cover art generation
- ${MUSIC_DIR_HOST}:${MUSIC_DIR_CONTAINER}:ro
```

### Unraid Configuration
For Unraid users, use the provided `docker-compose-unraid.yml`:
For Unraid users, your volumes and associated variables may look something like this:

```yaml
volumes:
- /mnt/user/appdata/jellyjams/playlists:/app/playlists
- /mnt/user/appdata/jellyjams/logs:/app/logs
- /mnt/user/appdata/jellyjams/config:/app/config
- /mnt/user/appdata/jellyjams/cover:/app/cover
- /mnt/user/appdata/jellyjams:/data
- ${PLAYLIST_DIR_HOST}:/playlists
- ${MUSIC_DIR_HOST}:${MUSIC_DIR_CONTAINER}:ro
```
```.env
PLAYLIST_DIR_HOST=-/mnt/user/appdata/jellyfin/data/playlists
MUSIC_DIR_HOST=/mnt/user/media/data/music
MUSIC_DIR_CONTAINER=/mnt/user/media/data/music
```

## 📝 Examples
Expand All @@ -447,6 +454,7 @@ volumes:
# .env file for basic setup
JELLYFIN_URL=http://localhost:8096
JELLYFIN_API_KEY=your_api_key_here
PLAYLIST_DIR_HOST=/path/to/jellyfin/config/data/data/playlists
PLAYLIST_TYPES=Genre,Year,Artist
MAX_TRACKS_PER_PLAYLIST=50
MIN_TRACKS_PER_PLAYLIST=10
Expand All @@ -457,6 +465,9 @@ MIN_TRACKS_PER_PLAYLIST=10
# .env file for advanced setup
JELLYFIN_URL=https://jellyfin.example.com
JELLYFIN_API_KEY=your_api_key_here
PLAYLIST_DIR_HOST=/path/to/jellyfin/config/data/data/playlists
MUSIC_DIR_HOST=/host/path/to/music
MUSIC_DIR_CONTAINER=/jellyfin/container/path/to/music

# Playlist generation
PLAYLIST_TYPES=Genre,Year,Artist,Personal
Expand Down Expand Up @@ -503,20 +514,23 @@ EXCLUDED_GENRES=Classical,Opera,Spoken Word,Audiobook,Podcast
- Ensure `TRIGGER_LIBRARY_SCAN=true`
- Check Jellyfin API key permissions
- Verify playlist folder is accessible

2. **Playlists not appearing in JellyJams**
- Ensure `PLAYLIST_DIR_HOST` = your host path to the Jellyin playlists directory
- Verify Jellyfin playlists directory is mapped to /playlists

2. **Cover art not copying**
- Check Docker volume mount for `/app/cover`
- Verify file permissions on cover directory
3. **Cover art not copying**
- Verify file permissions on cover in your appdata directory
- Check logs for detailed error messages

3. **Personalized playlists empty**
4. **Personalized playlists empty**
- **Install Required Plugin**: Ensure [Jellyfin Playback Reporting Plugin](https://github.com/jellyfin/jellyfin-plugin-playbackreporting) is installed and enabled
- Increase `PERSONAL_PLAYLIST_MIN_USER_TRACKS`
- Check user has listening history in Jellyfin
- Verify user selection in settings
- Confirm plugin is collecting playback data

4. **Spotify integration not working**
5. **Spotify integration not working**
- Test connection in web UI settings
- Verify Client ID and Secret are correct
- Check Spotify app permissions
Expand All @@ -536,4 +550,4 @@ This provides comprehensive information about:

---

For additional help, check the application logs at `/app/logs/` or enable debug logging for detailed troubleshooting information.
For additional help, check the application logs at `/data/logs/` or enable debug logging for detailed troubleshooting information. You may also check the container logs using `docker logs jellyjams` from the host CLI.
Loading