Emby-compatible API

Besides its own API, the server speaks the protocol of an Emby server, so players made for Emby (Infuse, SenPlayer, VidHub and others) can connect to it. This page is for people who build or test a client against it. If you only want to use a player, read Third-party players.

Which clients#

The compatibility layer follows the Emby Server 4.10.1.0 interface. It works with players made for Emby, such as Infuse, SenPlayer and VidHub. Other 3rd-party Emby clients usually work too; Emby’s own official apps cannot connect. A Jellyfin-style mode exists for Jellyfin 12.x clients; it is secondary, and Infuse's Library Mode (which needs a companion plugin) is not supported. Use Infuse's direct mode.

The server runs in one compatibility mode at a time (Emby, Jellyfin or off) on the same port, set in the admin console. In off, every Emby and Jellyfin path answers 404 and only the native apps work. Clients must sign in again after you change the mode.

Connect#

• Address: http://<host>:5797, the same port as everything else. The usual prefixes /emby and /mediabrowser work, and paths are not case sensitive.
• Sign in with POST /Users/AuthenticateByName and the member's name and password. A member who has only a PIN cannot sign in this way; give them a password for the player.
• Then send the token the server returns on every request. Any of these works: the X-Emby-Token header, the X-Emby-Authorization header with Token="..." (the usual MediaBrowser Client=..., Device=..., DeviceId=..., Version=..., Token=... form), or the api_key query parameter.
• API keys do not work here. A Kryspal API key (msk_...) gets 401 on this protocol. Tools that need an Emby API key cannot connect.
• Failed sign-ins share the limits described in Using the API.
• Players on the same network find the server by itself through discovery on UDP port 7359, once you turn it on in the compose file (see Install).

What works#

The usual client flows: sign in and member lists, libraries and views, item lists with filters and sorting, item details and images, search, resume and next up, favorites and played state, playback reporting (start, progress, stop), subtitles (including external text subtitles and online subtitle search), and a WebSocket for library and watched-state changes. Some admin functions are exposed with permission checks, such as refreshing or deleting an item and editing its metadata.

Only the members' own libraries are visible. An item a member may not see answers 404, not 403.

Limits#

• No video transcoding. Playback is direct play or direct stream. The server tells clients that it cannot transcode, so a player that cannot play a file as it is must be set to convert on its side. For clients that need HLS, the server offers a copy-only HLS stream (audio is copied too, so formats such as DTS, TrueHD and PCM cannot be served this way).
• Subtitles in text formats are converted inside the server where needed. Image subtitles (PGS, VobSub) are delivered as they are. Subtitles are never burned into the picture.
• One backdrop per item. Each item has a single backdrop image, so a client that rotates several backdrops shows just that one. Stills are not offered to these clients.
• Music, photos, books and playlists are not supported. A query for only those types returns an empty list.
• Skip intro and outro reaches these clients only when your plan includes it: as chapter markers for Emby clients, and as segments for Jellyfin clients.
• Plan limits (simultaneous streams, devices) apply to these clients as well.
• Endpoints the server does not implement answer 404. Some Emby endpoints are only partly implemented, or not at all, for example a few image and similar-title endpoints; a client that depends on them may show less than it would on a real Emby server.
• Emby Premiere checks are not simulated.