DEV Community: Marius Vomir

Designing Reliable Jellyfin Voice Control with Identity Contracts

Marius Vomir — Wed, 12 Aug 2026 17:46:19 +0000

How fixed media slots, explicit destination rules, fail-closed routing, and visible state made voice control easier to reason about.

Smart Home Cinema – Voice Control is a Windows voice-control project designed to control movie playback in an existing Jellyfin setup. While adapting the control layer to Jellyfin, I ran into a design problem that was more important than command transport itself: every accepted phrase had to identify exactly what the system was allowed to act on.

A short command such as:

Play Movie Five

looks simple because most of its assumptions are hidden.

Which movie is “Five”? Which television should receive the command? Which Jellyfin user and live session belong to that television? What should happen if the target cannot be resolved safely?

I ended up treating each accepted voice command as an identity contract. Before execution, the system needs a defined media identity, a defined destination, an allowed action, and a clear failure rule.

At a high level:

accepted command
    → one media identity
    → one destination identity
    → one allowed action
    → one explicit failure rule

That model became the basis for the rest of the design.

Media Identity

A personal Jellyfin library may contain hundreds of films. Open-ended title search sounds natural, but it creates a large interpretation surface.

Consider:

Play Batman.

A library may contain several Batman films, alternate editions, remakes, collections, or user-specific versions. Speech recognition can add another uncertainty layer.

A conversational system could rank matches, remember context, ask follow-up questions, and use confidence thresholds. Supporting that behavior requires a different kind of control layer.

For deterministic playback, I used a dedicated Jellyfin playlist as the controlled media surface. Its first twenty positions became voice-accessible slots:

Position 1  → Play Movie One
Position 2  → Play Movie Two
Position 3  → Play Movie Three
...
Position 20 → Play Movie Twenty

Play Movie Five points to position five in the configured playlist. The user chooses which films occupy those positions; the control layer preserves the mapping between spoken number and playlist order.

The rule can be reduced to:

numbered voice command
    ↓
requested playlist position
    ↓
item stored at that position
    ↓
valid playable media?
    yes → continue
    no  → reject

This gives the command a stable media identity without searching the entire library.

The important invariant is simple:

As long as the media assignment for a playlist position remains unchanged, the same numbered command resolves to the same media item.

The vocabulary is deliberately smaller, but every accepted number has a precise meaning.

Visible State Must Match Media Identity

The television also needs to present the media in the same order used by the command layer.

The playlist stored by Jellyfin already contains the sequence used by the control layer. Some client views, however, can present the same films in another order, including alphabetical order.

That creates two different views of the same data:

command engine: playlist order
television UI:  displayed order

If the command layer treats one film as Movie Five while the fifth visible item on the television is another film, the user has no reliable way to know what the command means.

The solution was a generated Movie List built from the same playlist sequence used by the command engine:

1. Movie A
2. Movie B
3. Movie C
...
20. Movie T

The Movie List is part of the control model. It gives every numbered command a visible reference and lets the user confirm the current assignments directly on the television.

That produces a second invariant:

The order shown to the user must match the order used by the command layer.

Visible state and execution state need to describe the same system.

Destination Identity

Media identity answers one question: what should be controlled?

The identity contract also needs to define where the command should go.

A Jellyfin environment can contain multiple users, televisions, streaming devices, and active sessions. Selecting a destination by convenience alone can produce accidental success during testing and incorrect routing later.

One control mode uses an explicitly selected television:

Select TV Two
Play Movie Five
Pause Movie
Forward One Minute

After Select TV Two, subsequent commands remain associated with that destination until another television is selected.

This removes several runtime guesses. The system does not need to infer the intended room from microphone proximity, assume that the nearest active screen is correct, or switch targets simply because another client becomes active.

The selected destination becomes part of the command context.

When the Destination Becomes Part of the Command

Independent viewing areas require a stricter routing model.

Instead of keeping one shared selected target, the destination can be named directly in each command:

TV One Play Movie Five
TV Two Pause Movie
TV Three Open Movie List

Each zone has its own configured destination profile and controlled media list. At runtime, the system resolves the eligible Jellyfin target for that profile and rejects the command if the destination is unavailable or ambiguous.

Conceptually:

zone named in the command
    ↓
configured destination profile
    ↓
eligible Jellyfin target
    ↓
exactly one valid match?
    yes → continue
    no  → reject

The visible zone name is useful to the person speaking. Routing depends on the configured identities behind that name.

This also means that Movie Five can legitimately refer to different films in different zones, because each zone can have its own controlled playlist.

The command remains deterministic because both identities are explicit:

media identity       = Movie Five
destination identity = TV Two

Longer commands are a reasonable cost when independent rooms must remain independent.

Fail Closed When Identity Is Incomplete

Suppose only one television is active during development. A rule such as “use the first available session” may appear reliable.

The ambiguity becomes visible as soon as another client connects.

For device control, a guessed destination can be worse than a rejected command. I therefore prefer fail-closed behavior when a required identity is missing or ambiguous:

missing playlist slot     → reject
unavailable selected TV   → reject
ambiguous client session  → reject
incomplete zone mapping   → reject

This makes configuration problems visible instead of hiding them behind an unrelated session that happened to be available.

The Contract Behind Each Command

Once the identities are explicit, the command vocabulary can be described as a set of contracts rather than a list of phrases.

Command	Media identity	Destination identity	Failure rule
`Play Movie Five`	Playlist position 5	Selected television	Reject if the slot or target is unavailable
`Pause Movie`	Current media session	Selected television	Reject if no eligible session matches
`TV Two Play Movie Five`	Zone Two playlist position 5	Zone Two configured destination	Reject if routing is missing or ambiguous
`TV Three Open Movie List`	Zone Three generated list	Zone Three device	Reject if the zone target is unavailable

The spoken phrase is the entry point. The contract defines the only meanings the phrase is allowed to have.

This way of thinking also helps when new commands are added. A command is incomplete until its identity source and failure behavior are defined.

Observable Success Belongs to the Contract Too

A command can be routed correctly and still depend on what the final Jellyfin client supports.

That matters because server acceptance and user-visible behavior are different layers of the system. The control model therefore treats the client as part of the execution path rather than assuming that a valid request guarantees a visible result.

Conceptually:

command
    + media identity
    + destination identity
    + eligible session
    + client capability
    = intended user-visible action

This does not require every Jellyfin client to expose identical capabilities. It requires the control layer to apply only actions that are supported for the target client.

The same contract idea still applies: support should be based on the behavior the user can actually rely on.

The Cost of Determinism

A deterministic interface gives up some flexibility.

The trade-offs are visible:

More flexible approach	Deterministic approach
Search the entire library by title	Use fixed playlist positions
Guess the intended television	Select or name the destination
Choose any available session	Require one exact eligible target
Hide incomplete configuration with fallbacks	Reject commands with unclear identity
Let the UI choose its own presentation order	Show the same order used by the command layer

The deterministic side asks the user to operate inside a smaller, more explicit model.

In return, the meaning of a valid command is easier to predict before it executes.

That is especially useful in home automation. The person speaking should not need to know which session the server currently considers active or why one client happened to win an internal selection rule.

What I Deliberately Left Outside the Contract

The current control model does not try to solve every voice-interface problem.

It does not attempt to provide:

unrestricted full-library title search;
conversational clarification between similar titles;
automatic room detection;
automatic destination selection;
identical capabilities on every Jellyfin client;
synchronized playback across several televisions.

Each of those features would require additional identity and state rules.

Full-library search would need ranking, pronunciation handling, confidence thresholds, and clarification. Automatic room detection would need a trustworthy relationship between microphones, users, rooms, and devices. Synchronized playback would introduce timing coordination and drift management.

Keeping them outside the current model makes the implemented behavior easier to explain and test.

Determinism Is a User-Facing Feature

Determinism may sound like an internal implementation detail. The user experiences it directly.

They experience it when:

Movie Five refers to the same position shown on the television;
Pause Movie reaches the selected target;
TV Two Play Movie Five cannot affect TV One;
an unavailable destination produces a clear failure instead of a command somewhere else;
the interface shows the same state the command engine uses.

The model can be summarized as:

explicit media identity
+ explicit destination identity
+ allowed action
+ explicit failure behavior
+ observable target behavior
= predictable control

The broader lesson applies beyond Jellyfin.

When software controls real devices, every accepted command should have a precise identity contract. The interface becomes easier to trust when the person speaking and the system executing the request share the same definition of what should happen next.

Building a Voice-Control Layer for Local Movie Playback on Windows

Marius Vomir — Tue, 28 Apr 2026 19:59:00 +0000

For a long time, watching local movies on a Windows PC has been technically easy, but not always comfortable.

If your PC is connected to a TV or monitor and you are watching from bed, a sofa, or across the room, simple actions can become surprisingly annoying: pause the movie, skip forward, go back, start the next movie, manage subtitles, or shut everything down at the end of the night.

Most of these actions are easy if you are sitting at the keyboard.

They are much less convenient when the PC is several meters away.

That was the starting point for Smart Home Cinema – Voice Control: not to build another media player, and not to build a streaming platform, but to create a local voice-control layer around an existing Windows movie playback workflow.

The idea was simple:

I wanted to control local movies by voice without turning my PC into a streaming server and without using a phone as a remote.

Update — Local Voice Edition

Since this article was published, Smart Home Cinema has expanded beyond the original Alexa / Google Assistant + TriggerCMD workflow described below.

The original workflow is now the Voice Assistant Edition. Smart Home Cinema also includes a Local Voice Edition, which uses a microphone connected to the Windows PC and a local voice engine for direct voice control.

With Local Voice Edition, normal movie playback control does not require Alexa, Google Assistant, TriggerCMD, Google Home, or a smart speaker. After trial or license activation, the local voice-control workflow can run offline for normal playback commands, except for specific online actions such as trial activation, license activation, license rebinding, or optional OpenSubtitles subtitle downloads.

The article below remains a useful look at the original voice-assistant workflow, the First File Rule, the subtitle workflow, and the local Windows automation model that still powers Smart Home Cinema.

The problem: local playback is still very manual

There are many ways to watch local movie files on Windows.

You can use VLC Media Player, PotPlayer, or other media players. You can connect the PC to a TV. You can use a wireless mouse, a keyboard, a media remote, or a phone remote app.

All of these work.

But they still assume that you are willing to reach for a device, unlock a screen, move a cursor, press keys, or interact manually with the PC.

For a normal desktop setup, that is fine.

For a living-room or bedroom setup, it feels unfinished.

The actual use case is very specific:

the movie files are local;
the PC is the playback machine;
the screen may be a TV or monitor;
the user is away from the keyboard and mouse;
the desired interaction is voice, not touch.

That is not exactly the same problem solved by a streaming service, a media server, or a generic remote-control app.

Why generic solutions were not enough

When you look for voice control on Windows, there are many adjacent solutions.

Some tools provide generic PC voice control. Some apps turn a phone into a remote. Some media-center systems organize or stream media libraries. Some automation tools can trigger commands on a computer.

Those are useful, but they do not directly solve the full movie-watching workflow.

For example:

a phone remote still requires the phone;
a media server changes the playback model;
a generic voice tool is not built around movies;
a tutorial can explain how to connect tools manually, but it is not a finished product;
a media player plays the file, but does not necessarily provide a full voice-driven session.

The goal of Smart Home Cinema was different.

It was designed as a ready-made Windows app focused specifically on controlling local movie playback by voice.

The product category: a local voice-control layer

Smart Home Cinema is best described as a local Windows voice-control layer for existing local movie playback.

That wording matters.

VLC Media Player or PotPlayer remains the actual playback engine. Smart Home Cinema does not try to replace them. Instead, it adds a voice-driven workflow around them.

The core idea is:

VLC or PotPlayer plays the movie. Smart Home Cinema controls the playback by voice.

This makes the product narrower than a media center, but also more focused.

It does not try to manage every possible media scenario. It focuses on one very specific one: controlling local movie playback on a Windows PC from a distance, using voice.

The command chain

Smart Home Cinema now supports two voice-control paths.

The Local Voice Edition uses a microphone connected to the Windows PC and a local voice engine for direct command recognition.

The simplified flow is:

User voice command
→ microphone connected to the Windows PC
→ local voice engine
→ Smart Home Cinema
→ VLC Media Player or PotPlayer

The Voice Assistant Edition keeps the original assistant-based workflow:

User voice command
→ Alexa or Google Assistant
→ TriggerCMD
→ Windows PC
→ Smart Home Cinema
→ VLC Media Player or PotPlayer

In both cases, Smart Home Cinema executes the local command logic on Windows.

VLC Media Player or PotPlayer remains the actual media player.

This separation is important. Smart Home Cinema does not replace VLC or PotPlayer. It adds a focused voice-control layer around them. In the Voice Assistant Edition, Alexa, Google Assistant, and TriggerCMD act as the external command path. In the Local Voice Edition, the command path is handled directly on the Windows PC through a local microphone-based voice engine.

What made this harder than it sounds

At first glance, voice-controlling a movie player sounds simple.

You might imagine that every command is just a shortcut:

pause the movie;
skip forward;
go back;
open the next file.

But a real viewing workflow is more complicated than that.

A voice command is not just a keypress. It is an intention.

When the user says something like “next movie”, the system has to translate that into a predictable local action. Depending on the workflow, that may involve closing the current player session, identifying the next file, moving the watched movie, launching the next one, and restoring the expected viewing state.

That is where the product becomes more than a list of shortcuts.

Smart Home Cinema needs to understand the local playback workflow, not just trigger random commands.

It also has to deal with the fact that VLC and PotPlayer are different applications with different control models. One player may expose a cleaner local interface for some actions. Another may require a different automation strategy. The user should not have to care about those differences while watching a movie.

The purpose of the app is to hide that complexity behind simple voice commands.

The First File Rule

One design choice that helped keep the system predictable is what I call the First File Rule.

Instead of trying to maintain a complex media database or playlist system, Smart Home Cinema treats the first playable video file in the selected movie folder as the current item.

That means the folder itself becomes the source of truth.

This is a simple rule, but it creates a stable workflow:

the user controls the first movie in the folder;
“Next Movie” advances the folder-based queue;
watched files can be moved out of the active folder;
the next file becomes the new current item;
no media library or database is required.

This approach is intentionally minimal.

It makes the behavior easy to understand, easy to reproduce, and less fragile.

In most cases, the user does not need to do anything special. Windows already displays files in a folder in a natural order, and Smart Home Cinema simply works with that order. For TV shows, episodes are usually already named sequentially, so episode 1 comes before episode 2, episode 2 comes before episode 3, and so on.

For standalone movies, the same folder-based order is usually enough. However, if the user wants to watch movies in a specific custom order, they can optionally rename the files with numeric prefixes such as 01, 02, 03, and so on.

That is not required for normal use. It is only a simple option for users who want full control over the viewing order.

For local playback, that kind of predictability matters more than having a complex library system.

Why local-first matters

A major design decision was to keep playback local.

The movie files stay on the user’s Windows PC or local storage. Smart Home Cinema does not upload the movie library to a cloud service. It does not stream the movie files from a remote server. It does not turn the product into a content platform. It does not track what the user watches.

That distinction matters because local movie playback is still a real use case.

Not every viewing setup is based on streaming platforms. Many users still keep movie files on a PC, external drive, or local folder.

For those users, the problem is not access to content.

The problem is convenient control.

Local Voice Edition strengthens this local-first model. After trial or license activation, normal playback commands can run without an internet connection. Internet is only needed for specific account or licensing actions, such as trial activation, license activation, or license rebinding. Optional online features, such as OpenSubtitles subtitle downloads, require internet only when the user chooses to use them.

Voice Assistant Edition still uses Alexa or Google Assistant through TriggerCMD as the external command path, but the movie files, media playback, and Smart Home Cinema command logic remain on the user’s Windows PC.

Why VLC and PotPlayer

VLC Media Player and PotPlayer are widely used Windows media players.

Smart Home Cinema currently supports them as playback engines because they are already strong at what they do: opening and playing local media files.

Instead of replacing them, Smart Home Cinema adds a voice-control workflow around them.

This keeps the responsibilities clear:

VLC or PotPlayer handles playback;
Smart Home Cinema handles the local command logic and playback workflow;
Local Voice Edition handles direct microphone-based voice control on the Windows PC;
Voice Assistant Edition uses Alexa or Google Assistant through TriggerCMD as the external command path.

That architecture avoids building another media player just to solve a control problem.

It also keeps the user in a familiar environment. They can continue using the player they already know, while adding a voice-controlled workflow on top.

The important point is that VLC and PotPlayer remain the media players. Smart Home Cinema is the control layer that makes the local playback setup easier to use from bed, sofa, or across the room.

The full viewing workflow

A useful voice-control system needs more than play and pause.

A real movie session includes many small actions:

starting playback;
pausing and resuming;
skipping forward or backward;
moving to the next movie;
showing progress;
managing subtitles;
switching display workflows;
opening the movie folder;
stopping playback;
shutting down the PC at the end.

Smart Home Cinema currently includes 25 voice commands organized into movie commands, subtitle commands, and system commands.

The goal is to support a complete local viewing session without returning to the keyboard or mouse.

One of the most important commands is “Stop Everything”. In the intended TV-viewing workflow, this can stop playback, move the display workflow back to the PC, and shut down the computer, allowing the user to end the session by voice.

That is the kind of workflow detail that separates a dedicated product from a generic automation shortcut.

Subtitle workflow

Subtitles are another part of the real-world movie experience.

Searching for subtitles one movie at a time can be slow and repetitive, especially when a folder contains many movies or episodes.

Smart Home Cinema includes a batch subtitle workflow for local movie folders.

With a single voice command, the app can search OpenSubtitles and download matching subtitles for multiple local movie or episode files in the selected folder, when matching subtitles are available.

It also includes subtitle synchronization and cleanup commands, so subtitle handling becomes part of the same local voice-controlled workflow.

The goal is not just to control playback, but to reduce the manual work around the full movie session.

What this is not

To avoid confusion, Smart Home Cinema should not be classified as:

a streaming service;
a media player;
a cloud media platform;
a movie provider;
a media library server;
a Plex, Kodi, or Jellyfin replacement;
a smartphone remote app;
only a DIY automation tutorial.

It is a narrower product than those categories.

It focuses on one specific problem: controlling local movie playback on Windows by voice.

What I learned from building it

One of the most interesting lessons was that automation is not only about triggering commands.

Good automation needs context.

A command like “pause” is simple. But a command like “next movie”, “download subtitles”, or “stop everything” belongs to a larger session. It has to respect the user’s local setup, the current player, the selected folder, the display workflow, and the expected final state.

Another lesson was that local-first software still has a place.

A lot of modern entertainment software assumes cloud accounts, streaming platforms, mobile apps, or media servers. Those are useful, but they are not the only model.

Sometimes the user already has the content, the player, and the screen.

The missing piece is the control layer.

Why this matters

Voice control is often discussed in the context of smart homes, speakers, lights, thermostats, or streaming services.

But local PC workflows still exist.

A Windows PC connected to a TV is still a common and powerful home entertainment setup. The missing piece is often not playback capability, but comfortable control from a distance.

Smart Home Cinema was built around that missing layer.

It is not trying to replace media players or streaming platforms. It is trying to make an existing local movie setup feel more natural, hands-free, and complete.

Links

Official website:

https://voicehomecinema.com/

What Smart Home Cinema is:

https://voicehomecinema.com/pages/what-is-smart-home-cinema

Public GitHub information page:

https://github.com/voicehomecinema/smart-home-cinema-info

Final thought

Sometimes a useful software product is not about replacing everything.

Sometimes it is about connecting existing tools in a way that finally matches how people actually use them.

For local movie playback on Windows, voice control is that missing layer.