Jellyfin
Included with Macro DeckControl Jellyfin apps and TVs from your deck, show what plays and react when playback starts or stops.
Two Music Player widgets playing a track, one in the Full cover style and one in the Small cover style, both with the Jellyfin name and logo in the header
- Control playback and volume on Jellyfin apps, browsers and TVs
- Search for a movie, episode, song or album and start it
- Triggers when playback starts, pauses, resumes or stops
- Music Player and Jellyfin Sessions widgets
- Connect several servers, each with its own variables
The Jellyfin integration connects Macro Deck to one or more Jellyfin media servers and works with the sessions on them: the Jellyfin apps, browsers and TVs that are signed in and playing. It does not need a Jellyfin plugin. You sign in with an API key, which lets Macro Deck see and control every session on the server, or with a username and password, which limits it to the sessions that account may control.
What you can do
- Play, pause, stop, skip, seek to a position or jump forward and back by a number of seconds.
- Set the volume, mute and unmute, and set shuffle and repeat on a client.
- Search the server for a movie, episode, song or album and start it on a device with Play media.
- Show a message with a heading on a Jellyfin client.
- Show what plays in the Music Player widget, or the playback on your servers in the Jellyfin Sessions widget.
- Start an automation when playback starts, pauses, resumes or stops, when the item changes, or when a client connects.
Some example setups:
- A Toggle Play/Pause button for the living room TV, with Seek backward next to it to repeat the last 10 seconds.
- An automation on Playback started for your TV that dims the lights when
{{ event.itemType }}isMovie, and a second one on Playback stopped that turns them up again. - A button that shows "Dinner is ready" on the TV with Show message.
Servers and devices
Each server you add appears in two forms wherever you pick a player. The server name follows whichever session played something most recently. Server · Device, for example Home · Living Room TV, always targets that device and shows as not connected while the device is off. Macro Deck remembers devices for 30 days after it last saw them.
Macro Deck follows a server live through its WebSocket on Jellyfin 10.11 and later. When a server does not send live updates, it asks for the sessions every two seconds instead. When a server goes away, Macro Deck keeps retrying in the background and reports it on the Jellyfin page under Integrations after a few failed attempts. Not every Jellyfin client supports every command: a command the client cannot carry out fails with a message.
What you need
- A Jellyfin server that the computer running Macro Deck can reach over the network.
- An API key from the Jellyfin dashboard (recommended), or a Jellyfin username and password.
- Jellyfin 10.11 or later for live updates. Without them, Macro Deck asks for the sessions every two seconds.
Set it up
Step 1: Create an API key in Jellyfin
Open the Jellyfin dashboard and go to API Keys. Create a new key and copy it. If you prefer to sign in with a user account, skip this step.
Step 2: Add a configuration in Macro Deck
In Macro Deck, click Integrations in the sidebar and click Jellyfin. On the Overview tab, click Add configuration in the Configuration section. Turning on the switch at the top right opens the same dialog, and the integration is turned on once the setup is done.
Step 3: Enter the server details
In the Connect to Jellyfin dialog, fill in:
- Configuration name: a name for this server, for example
Home. It is used in player names and variables. - Server address: the address with its port and any base path, for example
http://192.168.1.10:8096. - Sign in with: API key or Username and password, then enter the API key, or the Username and Password.
Click Continue. Macro Deck checks the connection before it saves.
- Configuration name: a name for this server, for example
Step 4: Check the connection
The new configuration shows Connected in the Configuration section of the Jellyfin page. Repeat the steps for each further server.
Step 5: Add an action to a button
On the Deck page, click the button you want to use. The deck must be unlocked: when the button at the top right reads Lock, it is unlocked. The editor opens with Short Press selected. Click + Add action, select Jellyfin on the left of the Add action dialog and pick an action such as Toggle Play/Pause. Choose the server or the device it controls, then click Save.
Step 6: Press the button
Start something on the Jellyfin client and press the button on your deck. Playback pauses or resumes on that client.
Actions20
Put these on a button or run them from a flow.
- Play
- Resumes playback on the client.
- Pause
- Pauses playback on the client.
- Toggle Play/Pause
- Switches between play and pause, and shows the playback state on the button.
- Stop
- Stops playback on the client.
- Next Track
- Skips to the next item.
- Previous Track
- Skips to the previous item.
- Refresh State
- Reads the current playback state right away.
- Seek
- Jumps to a position in the current item, in seconds.
- Seek forward
- Jumps ahead in the current item, 30 seconds by default.
- Seek backward
- Jumps back in the current item, 10 seconds by default.
- Set Volume
- Sets the client's volume, from 0 to 100%.
- Volume Up
- Raises the volume by 10%.
- Volume Down
- Lowers the volume by 10%.
- Mute
- Mutes the client.
- Unmute
- Turns the sound of the client back on.
- Toggle mute
- Mutes or unmutes the client.
- Toggle Shuffle
- Turns shuffle on, off, or switches it.
- Set Repeat Mode
- Sets repeat to Off, Repeat Track or Repeat Album/Playlist.
- Show message
- Shows a message with a heading on the client for a number of seconds.
- Play media
- Searches for a movie, episode, song or album and starts it on the client, replacing what plays there.
Triggers9
A button or flow can react to these events.
- Playback started
- A session started playing something.
- Playback paused
- Playback was paused on a session.
- Playback resumed
- Paused playback continued on a session.
- Playback stopped
- A session stopped playing.
- Playing item changed
- A session moved on to a different movie, episode or track.
- Session connected
- A Jellyfin client opened a session on the server.
- Session disconnected
- The server closed a client's session.
- Connected
- Macro Deck connected to the server.
- Disconnected
- Macro Deck lost the connection to the server.
Variables7
Show these values on buttons and widgets, or use them in conditions.
jellyfin_active_sessions- Sessions playing or paused on all servers together.
jellyfin_<server>_is_connected,jellyfin_<server>_active_sessions- Whether Macro Deck reaches each server and how many sessions play there.
jellyfin_<server>_<device>_is_playing,jellyfin_<server>_<device>_is_paused,jellyfin_<server>_<device>_is_active- Whether something plays, is paused or is loaded on the device. Writing to the playing or paused variable plays or pauses.
jellyfin_<server>_<device>_title,jellyfin_<server>_<device>_series,jellyfin_<server>_<device>_album,jellyfin_<server>_<device>_media_type- The title, series, album (or season) and media type of the item on each device.
jellyfin_<server>_<device>_position,jellyfin_<server>_<device>_duration,jellyfin_<server>_<device>_progress_percent- The position and duration in seconds and the progress in percent. Writing to the position or the progress jumps to that point.
jellyfin_<server>_<device>_user,jellyfin_<server>_<device>_client,jellyfin_<server>_<device>_device,jellyfin_<server>_<device>_is_transcoding- The user, client and device of each session, and whether the server converts the media.
jellyfin_<server>_<device>_volume,jellyfin_<server>_<device>_is_muted- The volume and mute state of each device, where it reports them. Writing to them sets the volume or mutes.
Widgets2
Add these to your deck from the widget picker.
- Music Player
- Shows what plays on a server or device, with artwork, progress and play, pause and skip buttons. The lines adapt to songs, episodes and movies.
- Jellyfin Sessions
- Shows what plays on one or all of your servers, with cover or poster, who plays it, on which device and how far along it is.
Frequently asked questions
Should I use an API key or a username and password?
An API key is recommended: Macro Deck then sees and controls every session on the server. With a username and password, it only sees the sessions that account may control. The password is used once to sign in and is not stored; Macro Deck keeps only the access token Jellyfin hands out.
Can I connect more than one server?
Yes. Add one configuration per server. Each one has its own variables, named after the configuration, and shows whether it is connected.
Why does a command fail on my TV or in the browser?
Not every Jellyfin client supports every command. Macro Deck only sends what the client reports it can do, so a command it cannot carry out fails with a message. Volume and mute usually work only in the Jellyfin apps, not in a browser tab.
What happens when the server is offline?
Macro Deck keeps retrying in the background and shows the issue Jellyfin server unreachable on the Jellyfin page under Integrations after a few failed attempts. Actions for that server fail with a message until it is back.
Should I use the Jellyfin triggers or the Music Player triggers?
The Music Player triggers, such as Playback Started under Music Player, also fire for Jellyfin, once for the server and once for the device. For automations, the Jellyfin triggers are the better choice: they fire once per device and carry the user and the type of media.
More in Music and audio
Spotify
Included with Macro DeckControl Spotify playback, like songs, manage playlists and show what is playing on your deck.
YouTube Music Desktop App
Included with Macro DeckControl YouTube Music Desktop App from your deck: playback, volume, ratings and what is playing.
WebNowPlaying
Included with Macro DeckControl music and videos playing in your browser and show what is playing, through the WebNowPlaying extension.
SoundPad
Included with Macro DeckPlay sounds from your SoundPad list, control recordings and show the playing sound on your deck.
Voicemeeter
Included with Macro DeckControl the gain, mute, routing and macro buttons of Voicemeeter, Banana or Potato from your deck.