-
Notifications
You must be signed in to change notification settings - Fork 33
Module: Emby
A simple (list navigation focused) Emby client for browsing and playback of content on a CRT TV.
Allows you to view content from a connected server and the libraries associated with one user. It requires network access to your Emby server, and authentication either directly against that server or via Emby Connect. It also requires a keyboard to enter your server details and credentials for initial auth.
Built using Emby's public API: https://swagger.emby.media/?staticview=true
Contributors: freemchr, anthonycaccese
Note
Single server, single user for this initial pass. Emby has no "Quick Connect" equivalent (that is a Jellyfin API), so sign-in is a username and password against your server, or Emby Connect.
Browse & Discover
- Supported library types:
movies, tvshows, homevideos, boxsets(Music and Photo libraries are not supported) - Library, collection and folder browsing
- Continue Watching and Next Up shelves, shown at the top of the library list only when they have something in them
- Show / Season / Episode browsing
- Alphabetical jump navigation
- Select which libraries appear
- List wraparound across every view
Playback (through MPV)
- Direct Playback or Transcode options
- Wide codec support: mpv plays nearly anything, so the module advertises a match-all profile and lets the server hand over the original file
- Audio track selection, and switching during playback
- Subtitle track selection, and switching during playback
- External/sidecar subtitles keep direct play instead of forcing a burn-in transcode
- Dolby Vision sources are transcoded to SDR so they play at all
- Progress sync and resume
- Intro and credit skip, from Emby's chapter markers
- Auto play next episode for TV libraries
Account
- Two sign-in methods: local server account, or Emby Connect
- Server picker when an Emby Connect account has more than one server
- Sign out revokes the token and removes the device from your server
| Option | Values | Info |
|---|---|---|
| Enabled | On/Off | Sets if the Emby module should display in the main module list when you start 240-MP. |
| Libraries | Dynamic (based on the connected server) | Allows you to select which libraries you would like to display when browsing the connected server. |
| Video Quality | Direct Playback and Transcoding Options | Direct playback will stream the video direct from your server to your device. On a Raspberry Pi 4 I've had success with 1080p HEVC files but depending on bitrate your mileage may vary. If you are trying to watch video that a Raspberry Pi can't natively decode then you can use this option to have your connected server transcode the content before sending to the Raspberry Pi for playback. |
| Resume Playback | Ask/Always |
Ask will present you with an option to restart playback or resume and Always will resume without asking. |
| Autoplay Next Episode | On/Off | Defaults to off, if turned on it will auto play the next episode from a given season until the end of a season. |
| Intro Skip | Off/Auto/Button | Uses Emby's intro chapter markers when the server has detected them. Auto skips for you, Button offers a prompt. |
| Credit Skip | Off/Auto/Button | Uses Emby's credit chapter markers when the server has detected them. |
| Sign Out | -- | Signs you out of Emby, revokes the access token and removes 240-MP from your server's device list. When you open the Emby module you will be asked to sign in again. |
Go to Settings > Emby and set Enabled to On
The sign-in screen asks you to choose the method first, because the two need different things from you.
Local Server. Enter your server URL (e.g. http://xxx.xx.x.xx:8096), your username and your password. This is your account on your own server.
Emby Connect. Enter the email address and password of your emby.media account. Connect only accepts the email, not a username, despite the API field being named nameOrEmail. There's no server URL to enter: Connect already knows which servers your account is linked to, and 240-MP fetches them. If your account has one server it goes straight in; if it has several you get a picker. Where a server publishes both a local and a remote address, the local one is preferred, since a device on a CRT usually shares a network with its server.
Direct Play (the auto quality setting) hands you the original file, untouched. mpv plays nearly everything, so the module tells the server it can accept anything rather than listing codecs. A codec whitelist just caused silent transcodes on exact-name misses (pcm_s16le vs pcm, webvtt vs vtt).
One Emby-specific wrinkle worth knowing, because it looks like a codec problem and isn't: Emby applies a default streaming bitrate cap when the client doesn't declare one, and silently refuses direct play for anything above it, reporting no direct play support and no reason why. In practice that denied almost everything past a couple of Mbps. The module declares an effectively unlimited cap for direct play, which fixed it across test files from 2.6 to 65 Mbps.
Transcoding. Picking any quality other than auto asks the server for an HLS stream (H.264 video, AAC/MP3 audio) capped to that tier:
| Setting | Max height | Max bitrate |
|---|---|---|
| 1080p | 1080 | 10 Mbps |
| 720p | 720 | 6 Mbps |
| 576p | 576 | 4.5 Mbps |
| 480p | 480 | 4 Mbps |
If a direct play fails at the mpv end, the module retries once as a transcode rather than just giving up.
Dolby Vision has special handling. mpv on both targets (macOS and the Pi) decodes DV but bails at video output with "Dolby Vision enhancement-layer playback is not supported", so the title flashes and exits. The module detects DV from the server's response and re-requests it as an SDR H.264 transcode, capped to 1080p/20 Mbps so the server can start promptly.
Warning
Smooth 4K Dolby Vision needs a server that can hardware transcode. Without it Emby software-transcodes at a handful of frames per second and stutters regardless of what the client does. That's server-side, not something the module can fix. Worth checking before assuming DV playback is broken, because some NAS models (Synology's AMD-based units, for instance) have no iGPU and can never hardware transcode, Premiere subscription or not.
Subtitle handling is the part that differs most from the Jellyfin module, because Emby only honours what the client explicitly declares.
- Text subtitles (SRT/ASS/SSA/VTT/mov_text) are fetched as a separate sidecar file and handed to mpv. This is true on both the direct play and transcode paths. On direct play it means selecting a subtitle no longer forces a transcode. The earlier behaviour, inherited from the Jellyfin port, declared only embedded delivery, so Emby had no permitted way to show an external subtitle except to burn it in, which is a full transcode. On the transcode path it means your subtitle survives, and the video transcodes untouched.
- Image subtitles (PGS/VOBSUB/DVB) have no text sidecar. On direct play mpv selects them out of the original stream. On a transcode they have to be burnt in, which is the one case where selecting a subtitle changes how the video is encoded.
On start-up speed: the module hands mpv only the subtitle you actually selected. Emby extracts each sidecar on the fly (the first one measured at around 27 seconds on a large remux), and mpv loads them synchronously before playing anything. Preloading every track meant a file with a few embedded subtitles stalled for half a minute, and one with twenty stalled for minutes, even with subtitles switched off. Non-selected embedded tracks are still reachable during playback, since they ride along in the direct-play stream.
If you have a subtitle-heavy library and playback used to take an age to start, that's what that was.
The module reads Emby's chapter markers: the IntroStart, IntroEnd and CreditsStart markers your server writes when it detects them. Intro skip covers the gap between the first two; credit skip runs from CreditsStart to the end of the file. Markers only exist once the server has actually detected them.
Continue Watching and Next Up appear as shelves at the top of the library list, and only when they have content. The module checks each before showing it, so you don't get an empty row.
Playback progress is reported to the server as you watch, so resume points stay in sync with your other Emby clients. Whether you're asked to resume or just resumed automatically is the Resume Playback setting.
Your server-side language preferences are honoured too: audio and subtitle language preference and subtitle mode are read from your Emby user configuration to pick default tracks, and whatever you last chose in 240-MP takes precedence after that.
Whichever way you sign in, the end state is the same: a per-server access token, saved to a file called emby_auth.json in the app's data directory alongside the server URL, your user id and display name, the server name, and a device id. The token is stored as-is (not additionally encrypted) and the file is created with owner-only read/write permissions (chmod 600) before the token is written to it.
This matches how the Plex and Jellyfin modules handles their tokens. See Module: Plex → Authentication Model for the long version.
In short though... 240-MP is a hobby project built for a dedicated device on a network you trust, so the things actually keeping your token safe are that you physically control the device and that it lives on your home network. File permissions sit on top of that as a layer that stops other user accounts on the same Pi reading the file. They don't protect against someone holding the SD card, or root on the machine. Encryption was considered and skipped for the same reason as Plex: on a headless Pi that boots straight into the app, there's nowhere genuinely safe to put the key.
240-MP never writes your password to disk and never keeps it after the sign-in request. It is used once, to get a token, and then discarded.
If your Emby server runs on plain HTTP, which is very common on a home LAN and is the default, your password crosses your network unencrypted. That's how the Emby API works rather than something 240-MP adds. But it's the single most important thing to know here, so: if that matters to you, put your server behind HTTPS, or use Emby Connect, where your password only ever goes to connect.emby.media over a verified TLS connection.
The Emby module only communicates with your Emby server, plus connect.emby.media if and only if you sign in with Emby Connect. There are no other communication paths to any other service, no tracking and no analytics, and the source code for the module is provided to help you validate that.
Emby Connect drops out of the path entirely once you're signed in. It's used to look up your servers and swap an access key for a normal per-server token; after that, every request goes to your server.
240-MP registers itself with your server under a device id generated at first sign-in, which is what makes it appear under Dashboard > Devices.
Signing out from Settings > Emby > Sign Out does three things: removes the device registration from your server, revokes the access token, then deletes emby_auth.json locally. A new device id is generated for the next sign-in, so you get one clean entry rather than an accumulating pile of stale ones.
The Emby access token does not expire on a rolling basis. It stays valid until something revokes it. So you can revoke 240-MP's access at any time from Dashboard > Devices on your server. The app handles that correctly, dropping you back to the sign-in screen the next time it talks to the server.
Your token stays protected as long as you keep the following in mind:
- Run your Pi with a real user account and a strong password (modern Raspberry Pi OS already makes you create one during imaging) and if you enable SSH, don't pair it with a weak password.
- Keep your Pi running 240-MP on your local home network.
- If your server is on plain HTTP, understand that your Emby password crosses your network in the clear when you sign in. Use HTTPS or Emby Connect if that's a concern for you.
- Don't share or copy the
emby_auth.jsonfile anywhere. - Remember that SD card backups/images contain the token too. If you image or clone your card to troubleshoot or hand it off, treat that image as if it contains your Emby login.
- If you lose access to your Pi for any reason, remove 240-MP from
Dashboard > Deviceson your server.