Plex: Teaching HomeSeer Who’s Watching What

Available now in the HomeSeer plugin store.

A media server knows a surprising amount about what is happening in a house.

Someone is watching something.

On a particular device.

In a particular room.

It is playing, paused, stopped, or somewhere in between.

And once that information becomes a device inside HomeSeer, a whole collection of useful automations suddenly becomes obvious.

If someone starts a movie in the living room, dim the lights.

If playback pauses, bring them up a little.

If the last session in the house stops, shut down the AV equipment.

If nobody is watching anything, maybe that is finally a safe time to reboot something.

The media server already knows all of this.

The plugin just teaches HomeSeer how to listen.

Signing in without ever seeing the password

Plex supports authentication tokens, but the documented manual way of getting one is wonderfully hands-on.

Sign into Plex Web.

Open an item.

Choose Get Info.

Select View XML.

Then inspect the address bar and find the X-Plex-Token buried somewhere inside a URL considerably longer than the thing you actually want.

Copy the token.

Paste it into the plugin.

Done.

Technically.

It works, but it is several steps of carefully following instructions followed by an excellent opportunity to copy the wrong thing.

There had to be a better way.

Fortunately, Plex already invented one.

It is the same general linking mechanism used by its television applications, where typing a full account password with a remote control would be nobody’s idea of recreation.

The plugin asks Plex for a linking PIN.

Plex returns a four-character code.

You go to plex.tv/link on whatever phone, tablet, or computer is already nearby, enter the code, and approve it.

The plugin receives the resulting token.

Finished.

But convenience is not actually the part I like most about this.

The important part is what doesn’t happen.

The plugin never receives your Plex password.

It never stores it.

It never transmits it.

Authentication happens on Plex’s own page.

So your password travels:

You → Plex

not:

You → my plugin → Plex

That is a much better reason to use linking than merely saving a few copy-and-paste steps.

Credentials I never receive are credentials I never have to protect.

And sometimes you may not need a token

There is one qualification here worth getting right.

A claimed Plex Media Server requires authenticated access by default, including on the local network.

Plex does, however, allow an administrator to explicitly configure particular local IP addresses or networks that may connect without authentication.

So on an installation where that exception has deliberately been configured, the plugin may be able to read the local sessions endpoint without a token.

The plugin does not insist on authentication when the server itself says it is unnecessary.

But it also does not assume local means unauthenticated.

That distinction matters.

The normal case is authenticated access.

The no-token case is an explicit server configuration.

Which leads to another rule I like:

Ask for credentials when they are required, but do not collect them merely because you can.

Identity, and the pause button

This one is easy to get wrong in a way that may not show up until somebody actually uses the plugin for a while.

Plex reports both a playback session and the player on which that playback is happening.

Those are not the same kind of identity.

The session is transient.

The player is the durable thing a person actually recognizes.

During testing, I found that session identifiers could change as playback state changed. Keying HomeSeer devices to those temporary sessions would create exactly the wrong behavior.

A pause or resume could effectively become:

Congratulations. You have a new HomeSeer device.

Do that often enough and the device list becomes an archaeological record of previous playback sessions.

Worse, HomeSeer events written against one of those devices would be tied to an identity that no longer represents the player.

So the plugin does not use the playback session as its durable identity.

It uses the player’s machine identifier.

That represents something meaningful and persistent:

Living Room Roku

Bedroom Television

Kitchen Tablet

Sessions can come and go underneath it.

Movies can change.

Playback can stop and restart.

The HomeSeer device remains the same because the thing sitting in the room remains the same.

That distinction has become a recurring rule throughout these plugins:

Identify the durable thing, not the temporary conversation you happen to be having with it.

Discovery, and our old friend Windows Firewall

Plex has its own local discovery mechanism called GDM, short for “G’Day Mate.”

It broadcasts over UDP.

In theory, it is wonderfully simple.

Send one discovery packet.

Plex servers answer.

Done.

Except the answers are inbound UDP.

And on Windows, that can introduce an old friend:

Windows Firewall.

The plugin sends the discovery packet successfully.

The Plex server receives it.

The server answers.

Windows sees inbound UDP traffic headed toward an executable it does not have a rule for...

...and can quietly throw it away.

No useful exception reaches the plugin.

No warning explains what happened.

From the application’s point of view:

Nothing came back.

And unfortunately:

“There are no Plex servers on this network.”

and

“Windows discarded every discovery response.”

look remarkably similar.

I verified that GDM was enabled on the Plex server here while working through this, and the expected replies still were not reaching the plugin.

That was familiar.

I had already hit essentially the same discovery problem with Roku.

Same sort of failure.

Same silence.

Same practical answer.

Ask outbound instead

So the plugin also has an outbound discovery path.

Instead of broadcasting:

“Any Plex servers out there?”

and depending entirely on inbound UDP replies reaching the application, it probes the local network directly for Plex servers.

Those are outbound connections.

Windows Firewall is much less interested in interfering with them.

The servers answer.

Discovery continues.

This is not an argument against GDM.

GDM is cheap, elegant, and worth using.

It is an argument against making a single discovery mechanism the only way a user can find their server.

At this point I have run into the same broad Windows behavior enough times that it has become almost a reflex:

Roku SSDP finds nothing?

Check inbound UDP.

Plex GDM finds nothing?

Check inbound UDP.

Wemo SSDP finds nothing?

I have a suspicion about where to look.

One Windows behavior has now managed to contribute code to three unrelated plugins.

Efficiency through recurring annoyance.

One pattern, three media servers

Plex is also part of a larger family.

There are separate plugins for:

Plex

Jellyfin

Emby

Each works independently.

Each has its own authentication.

Its own discovery.

Its own API.

Its own particular collection of oddities.

But conceptually, they have nearly the same shape.

Discover the server.

Connect to it.

Find active sessions.

Identify the playback client.

Determine what is playing.

Expose that state to HomeSeer.

The APIs underneath are different.

The question HomeSeer is asking is not.

And from the HomeSeer side, I deliberately want those differences to disappear as much as possible.

A player should still look like a player.

Playing should still mean playing.

Paused should still mean paused.

The HomeSeer device model should not change just because somebody replaces Plex with Jellyfin.

That consistency also led naturally to another idea.

One skill, three plugins

There is an Alexa music-skill design sitting beside these three plugins.

From the user’s perspective, one skill makes much more sense than three.

They should not particularly care whether the album they want happens to live in Plex, Jellyfin, or Emby.

The natural request is:

“Play this.”

The house can worry about where it lives.

But one Alexa skill spanning three independent plugins creates an architectural question worth answering before writing the code.

One skill means:

One deployment.

One cloud-facing integration.

One set of credentials and configuration.

And potentially three different components that can affect whether the whole thing works.

If Plex is installed but Jellyfin is not, fine.

If all three are installed and one is unhealthy, what happens?

Who owns the shared configuration?

Where does account linking live?

Which component performs discovery?

What happens when one server API changes?

And most importantly:

Can each HomeSeer plugin still remain completely independent?

Those are not impossible problems.

They are simply much cheaper to answer while the design is still a document instead of a pile of working code people already depend on.

So for now, that idea exists mostly as design notes.

I have become increasingly fond of writing those while changing course is still inexpensive.

What I like about this one

The Plex plugin is not really about Plex.

It is about turning media activity into house state.

The media server already knows:

Someone is watching something.

Which room they are watching it in.

Which player they are using.

Whether it is playing or paused.

What the content is.

HomeSeer can now know those things too.

And once it does, the automations become the interesting part.

Dim the room when playback begins.

Bring the lights up when it pauses.

Avoid restarting the media server while somebody is using it.

Shut things down after the last session ends.

Or simply let another part of the house know:

Someone is watching something in here.

That is the piece I like.

The plugin is not inventing state.

It is taking state that already exists in one system and making it useful to the rest of the house.

Which is, increasingly, what I think the best home-automation integrations actually do.