Jellyfin API

Melodee provides a Jellyfin-compatible API that enables popular Jellyfin music clients to connect and stream your music library. This API implements the core Jellyfin media server endpoints required for music playback, browsing, and management.

Overview

The Jellyfin API allows clients designed for Jellyfin servers to work seamlessly with Melodee. This includes support for:

• Media Browsing: Artists, albums, songs, and playlists
• Streaming: Direct play and transcoding
• Library Management: Favorites, play states, and ratings
• Session Management: Playback reporting and scrobbling
• Playlist Operations: Create, edit, and manage playlists

Endpoint Structure

Jellyfin endpoints are available at the server root with automatic URL rewriting:

• Clients connect to: http://your-server:port/
• Internal routing: /api/jf/*

The middleware automatically detects Jellyfin client requests via the Authorization: MediaBrowser header and routes them appropriately.

Authentication

Server Discovery

Clients discover the server using:

GET /System/Info/Public

Response:

{
  "LocalAddress": "http://localhost:5157",
  "ServerName": "Melodee",
  "Version": "1.7.0",
  "ProductName": "Melodee",
  "OperatingSystem": "Unix",
  "Id": "c33ccd9320a17c12cfda124620290cae",
  "StartupWizardCompleted": true
}

User Authentication

Authenticate using username and password:

POST /Users/AuthenticateByName
Content-Type: application/json
X-Emby-Authorization: MediaBrowser Client="MyClient", Device="MyDevice", DeviceId="unique-id", Version="1.0"

{
  "Username": "your-username",
  "Pw": "your-password"
}

Response includes an access token:

{
  "User": {
    "Id": "user-guid",
    "Name": "username"
  },
  "AccessToken": "your-access-token"
}

Authenticated Requests

Include the token in subsequent requests:

Authorization: MediaBrowser Token="your-access-token", Client="MyClient", Device="MyDevice", DeviceId="unique-id", Version="1.0"

Core Endpoints

System

Users

Items (Library Browsing)

Query Parameters for /Items

Artists

Genres

Playlists

Favorites and Play State

Playback and Sessions

Streaming

Streaming Parameters

Images

Client Setup Guides

Finamp

Finamp is a popular open-source Jellyfin music client for iOS, Android, and Desktop.

1. Download Finamp from your app store or GitHub releases
2. Add Server:
   • Open Finamp and tap “Add Server”
   • Enter your Melodee server URL: http://your-server:port
   • Finamp will detect the server automatically
3. Login:
   • Enter your Melodee username and password
   • Finamp will authenticate and load your library
4. Configuration Tips:
   • Enable offline downloads for your favorite albums
   • Configure transcoding quality in settings
   • Set up lyrics display if your library has embedded lyrics

Feishin (Jellyfin Mode)

Feishin is a modern music client that supports both Jellyfin and Subsonic servers.

1. Download Feishin from GitHub releases
2. Add Server:
   • Click “Add Server”
   • Select “Jellyfin” as the server type
   • Enter your Melodee server URL: http://your-server:port
3. Login:
   • Enter your username and password
   • Feishin will connect and index your library
4. Features:
   • Modern, customizable interface
   • Gapless playback support
   • Queue management and playlists
   • Keyboard shortcuts for power users

Streamyfin

Streamyfin is a Jellyfin client focused on music streaming for iOS and Android.

1. Install Streamyfin from your app store
2. Add Server:
   • Tap “Add Server” on first launch
   • Enter: http://your-server:port
3. Authenticate with your Melodee credentials
4. Enjoy:
   • Browse your library by artist, album, or genre
   • Create and manage playlists
   • Stream with background playback support

Gelli

Gelli is an Android music player for Jellyfin servers.

1. Install Gelli from F-Droid or GitHub
2. Configure Server:
   • Open Settings → Server
   • Enter your Melodee URL
3. Login with your credentials
4. Start Streaming:
   • Browse artists and albums
   • Build your queue
   • Configure audio quality settings

Playback Reporting

Melodee tracks playback through session reporting endpoints. When clients report playback stopped, Melodee:

1. Records the play in the user’s history
2. Updates play counts
3. Scrobbles to Last.fm (if configured)
4. Updates “Recently Played” lists

Reporting Flow

Client starts playback → POST /Sessions/Playing
Client updates progress → POST /Sessions/Playing/Progress (periodic)
Client stops playback → POST /Sessions/Playing/Stopped (triggers scrobble)

Compatibility Notes

Supported Features

• ✅ Library browsing (artists, albums, songs)
• ✅ Audio streaming (direct play and transcoding)
• ✅ Playlist management
• ✅ Favorites and ratings
• ✅ Play state tracking
• ✅ Instant mix generation
• ✅ Similar items recommendations
• ✅ Search functionality
• ✅ Genre and year filtering
• ✅ Session management
• ✅ Scrobbling integration

Video and TV Features

Melodee is a music-focused server. Video-related Jellyfin features are not implemented:

• ❌ Video playback
• ❌ TV shows and movies
• ❌ Live TV
• ❌ Subtitles
• ❌ Video transcoding

Known Limitations

• Image types are limited to Primary and Album art
• Some advanced Jellyfin features may return empty results
• User management is handled through Melodee’s native interface

Troubleshooting

Client Can’t Connect

1. Verify the server URL is correct and accessible
2. Check that the Authorization: MediaBrowser header is being sent
3. Ensure no firewall is blocking the connection
4. Try accessing /System/Info/Public directly in a browser

Authentication Fails

1. Verify username and password are correct
2. Check that the user account is not locked
3. Ensure the client is sending proper MediaBrowser headers

Playback Issues

1. Check server logs for streaming errors
2. Verify the audio file format is supported
3. Try a different transcoding setting in the client
4. Check available disk space for transcoding cache

Missing Library Content

1. Ensure your music is properly indexed in Melodee
2. Check that albums have valid metadata
3. Run a library scan from Melodee’s admin interface
4. Verify the user has access to the library

API Testing

You can test Jellyfin API endpoints using curl:

# Server discovery
curl http://your-server:port/System/Info/Public

# Ping
curl http://your-server:port/System/Ping

# Authenticate (save token for subsequent requests)
curl -X POST http://your-server:port/Users/AuthenticateByName \
  -H "Content-Type: application/json" \
  -H "X-Emby-Authorization: MediaBrowser Client=\"curl\", Device=\"test\", DeviceId=\"test123\", Version=\"1.0\"" \
  -d '{"Username":"your-user","Pw":"your-password"}'

# Get albums (with token)
curl http://your-server:port/Items?includeItemTypes=MusicAlbum \
  -H "Authorization: MediaBrowser Token=\"YOUR_TOKEN\", Client=\"curl\", Device=\"test\", DeviceId=\"test123\", Version=\"1.0\""

For the complete Jellyfin API specification, refer to the Jellyfin API Documentation. Melodee implements the subset of endpoints relevant to music streaming.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.