Plex

localby ALYT

What it adds to a house

adds a music library.

How a person connects it

Method: form. Connect a Plex server reachable by this ALYT installation. Its token stays on the server; your speakers receive temporary links to the selected songs.

Field	Kind	Required
Plex server address (serverUrl)	text	yes
Plex token (token)	password, secret	yes

What it can look for

Yes: “Read the library again”.

What stops working when it is disconnected

Plex disappears from Media and existing audio links stop working. Your Plex files and playlists are kept.

The descriptor

Connection fields are served for a program at /connectors/plex.json.

{
  "source": "built-in",
  "visibility": "public",
  "listed": true,
  "version": "1.0.0",
  "kind": "PLEX",
  "name": "Plex",
  "icon": "music",
  "logo": {
    "url": "/integrations/logos/plex.svg",
    "color": "#EBAF00",
    "ratio": 1,
    "background": "#282828",
    "inset": 0.12,
    "scale": 1
  },
  "docsUrl": "https://developers.alyt.com/connectors/plex",
  "connectivity": "local",
  "brings": [],
  "author": {
    "kind": "alyt",
    "name": "ALYT",
    "url": "https://alyt.com"
  },
  "connect": {
    "method": "form",
    "help": "Connect a Plex server reachable by this ALYT installation. Its token stays on the server; your speakers receive temporary links to the selected songs.",
    "fields": [
      {
        "key": "serverUrl",
        "label": "Plex server address",
        "kind": "text",
        "secret": false,
        "required": true,
        "placeholder": "http://plex:32400",
        "help": "The address reachable by your ALYT server, approved in its deployment settings."
      },
      {
        "key": "token",
        "label": "Plex token",
        "kind": "password",
        "secret": true,
        "required": true,
        "help": "Your Plex authentication token. It grants access to the libraries you can see."
      }
    ]
  },
  "discovery": {
    "surface": "integrations",
    "verb": "Read the library again"
  },
  "library": {
    "verb": "Open the library"
  },
  "disconnect": {
    "consequence": "Plex disappears from Media and existing audio links stop working. Your Plex files and playlists are kept."
  }
}

The guide

Plex connects ALYT to a household’s own music library so Media clients can browse playlists, albums, artists, and songs already on that Plex server. It is a local connector: the ALYT installation must reach the Plex server directly, and the token you enter stays in the integration’s private configuration. Family members who can browse the home can read its connected music, so choose a token that only covers the libraries that home should share. Plex does not add client-specific branching, and it does not expose movie or television libraries.

Connect Plex

To connect, enter the Plex server address and a Plex token. The server address must be reachable by the ALYT server and approved in deployment settings. The token must be valid for that server and for the libraries you want this home to use. ALYT validates the token against the server, requires an accessible music library, and records the server’s stable machine identifier.

Use the server address as a route, not as the server’s identity. If the address changes, browse and playback depend on the new server still being reachable and authorized. If the token does not cover the music library, connection fails.

Browse the library

After a successful connection, Media clients use the existing library, search, and tracks API. Library pages show audio playlists first, then albums from music sections. Search works one type at a time: song, album, artist, or audio playlist. An album, playlist, or artist opens through the tracks route, and each song keeps its own stable plex:<serverId>:track:<ratingKey> URI.

Search pages show ten rows. Library and track pages show at most fifty items. Cursors are tied to the server, query, and collection, so a cursor from one result set does not carry to another.

Plex pagination depends on the X-Plex-Container-Start and X-Plex-Container-Size headers. Those names must be sent as headers, not query parameters, when listing playlists.

What playback does

Selecting music resolves the URI inside the speaker’s tenant, client, and exact home. A Plex server connected in another home is not enough. Hosted Sonos connections are rejected before any library resolution. The local Sonos connector queues validated audio files in order on the group coordinator, selects the first track, and starts playback. Volume stays as it was unless the caller asks to change it.

The audio path uses a direct local media relay. It does not require a second Plex sign-in in Sonos, and it does not implement Sonos Plex service URIs. Speakers fetch expiring ALYT links on the LAN, while artwork uses the same relay through the public gateway so a phone away from home can load images. Each signed link identifies one item, purpose, Plex server, tenant, and integration, and contains no Plex credentials. Links are rechecked on every request, so disconnecting revokes them and a changed server identity also invalidates them. HEAD and single-byte ranges support media probing and seeking. Streams stop when the caller disconnects.

Compatible MP3, AAC, ALAC, WAV, and FLAC files up to 48 kHz and 16 bits in mono or stereo play directly, including older Sonos players. Unsupported audio is not transcoded. One queue transfer accepts up to 200 songs; larger lists fail without starting a partial queue. Links expire after 24 hours.

What to check when it fails

If Plex will not connect, check that the server address is reachable from the ALYT server, that the token can see the intended libraries, and that the home has an explicitly bound local Plex runtime. A connected server in another home does not satisfy playback. If browse results are missing, confirm that the library contains audio sections, because movie and television sections are excluded.

If playback fails, confirm that the selected audio is in a supported format and that the speaker can fetch the expiring link on the LAN. If links stop working after a change, reconnect Plex and select music again to renew them. Disconnecting removes Plex from Media, and existing audio links stop working, but Plex files and playlists remain in place.