Mercurio Help Center
Build scheduled channels in the web admin, then watch them through the Mercurio guide on Apple TV or Mac. IPTV remains a separate provider-based guide inside the Apple apps.
The core scheduled-channel flow is: Settings Create Channel Add Slots Create Playout Generate Guide / Plex
- Start Here explains how the backend, web admin, and Apple apps fit together.
- Web sections retain the detailed channel-building reference.
- Apple, IPTV, and Playback cover setup, controls, and platform limits.
- Troubleshooting maps symptoms to the fastest source of evidence.
How Mercurio Fits Together
The existing backend is the sole authority for channels, schedules, program timing, and resolved scheduled media. The web admin builds that schedule. The tvOS and macOS apps consume it as an electronic program guide; they do not generate schedules or expose a Plex library browser.
Connect Plex, create channels and slots, generate playouts, publish guide data, and operate the network.
Browse scheduled channels from the backend, join the current program live, or start the current program from its beginning.
Use separately configured provider, M3U, and XMLTV sources. IPTV does not become part of the Plex-backed Mercurio schedule.
Use the official Plex app for normal Plex browsing. Mercurio asks the backend only for the media resolved for a scheduled program.
Your First Successful Build
Connect Plex in Settings
Fill in Server URL and Authentication Token, then click Test Node. Pick default TV, movie, and filler libraries so future forms open with sensible defaults.
Create a Channel
Set a Channel Name, choose the Plex Source Library, optionally assign Genres, and start with Weighted Slots unless you have a more rigid schedule in mind.
Add Slots from Media Library
Use single add for one-off tuning or bulk add when building a network fast. Keep early settings simple: Weight = `1`, Min Eps = `1`, Max Eps = `1`, and no strict time limits until you see a successful lineup.
Create a Stable Playout
Give it a Playout Name, keep Output Type = `Stable`, and set either Schedule Duration (Days) or Item Count. Turn on Show in Plex and Show in Guide if you want full publishing.
Generate and Inspect
Generate the playout, then inspect the result in the Network Guide, the playout Schedule page, and the Dashboard. If the result is empty, go straight to Why Slots Were Blocked.
Layer on automation later
Once the channel proves it can generate once, add Generation Mode, weekly rules, quiet hours, webhook triggers, and Now child playouts.
First-Day Checklist
- Plex connection passes `Test Node`.
- At least one channel exists and is enabled.
- That channel has slots.
- At least one playout exists and is enabled.
- The playout has generated once without failing.
- The guide or Plex playlist shows the result you expected.
One channel, one Stable playout, and one Now child is the sweet spot if you want both reliable resume behavior and a live-ish guide.
- Channel method: Weighted Slots
- Stable target: 3 to 7 days
- Now child: Start near Virtual Now
- Automation: daily Stable plus interval Now
Core Vocabulary
Channels decide eligibility. Slots decide source behavior. Playouts decide output and automation. When something goes wrong, debug in that order.
Mercurio for Apple TV and Mac
The native clients require tvOS 26 or later or macOS 26 or later. Both expose the same three destinations: Mercurio for backend-scheduled channels, IPTV for separate provider sources, and Settings.
The Apple apps do not create channels, regenerate schedules, browse a Plex library, or guess media URLs from artwork or metadata. They consume the backend guide and ask the backend to resolve scheduled playback.
Connect an Apple App
Make the backend reachable
The device must be able to reach Mercurio over the network. For a LAN install, use the backend computer's local hostname or address—not localhost on Apple TV. Prefer HTTPS when the backend is reachable outside your trusted local network.
Enter the URL manually
Open Settings -> Mercurio, enter the backend base URL, then choose Save URL. There is no automatic server discovery.
Test before opening the guide
Choose Test Connection. Mercurio verifies that it can reach a compatible guide response and reports authentication, TLS, timeout, unreachable-host, and incompatible-response failures in user-readable form.
Backend URL Rules
- Use an
http://orhttps://base URL with a valid host. - Do not include a username, password, query string, or fragment.
- Plain HTTP is accepted only for a local-network host.
- A saved manual URL overrides the optional local development default.
- Choose Clear URL to return to that configured default, when one exists.
Local defaults belong in the ignored local configuration file. Do not place credentials, Plex tokens, or personal network details in committed configuration.
Using the Mercurio Guide
Use Earlier and Later to move the visible window. Now returns the guide to the current time and current-program indicator.
Use genre, sort, and search controls. Recent channels provide a quick way back to what you watched most recently.
Selecting a channel name or logo immediately joins that channel's currently airing program live. There is no separate Mercurio channel-details screen in version 1.
A current program offers Watch Live and Start From Beginning. Past and future programs show details only and cannot be played in version 1.
Mercurio restores the guide position and focus after playback exits. Use Return to Now whenever you want to recenter on the live window.
Platform Differences
| Task | Apple TV | Mac |
|---|---|---|
| Guide movement | Directional Siri Remote focus | Arrow keys or pointer |
| Activate | Select/click | Return/Enter or click |
| Change destination | Choose Mercurio, IPTV, or Settings in the tab bar | Command-1 Mercurio, Command-2 IPTV, Command-, Settings |
| Close or go back | Menu/Back | Escape |
IPTV Is a Separate Guide
The IPTV tab uses separately configured service, M3U playlist, and optional XMLTV guide sources. Its channel catalog, program data, stream choices, favorites, and reminders are independent of the Plex-backed schedules in the Mercurio tab.
Adding an IPTV source does not add it to a Mercurio channel or Plex playout. Likewise, a generated Mercurio playout is not an IPTV provider source.
Add a Source
- Open Settings -> IPTV and choose the source-management action.
- Enter a service or M3U URL and, when available, a matching XMLTV URL.
- Save the source, refresh it, and confirm its channels appear.
- Choose default providers, enable or disable sources, and set guide preferences.
Source URLs must use HTTP or HTTPS and include a valid host. Avoid embedding usernames, passwords, or access tokens in URLs.
Find Channels
- Filter by provider and genre.
- Move through time with Earlier, Now, and Later.
- Show enriched-guide channels only, or turn that filter off when program metadata is sparse.
- Use favorites, search, jump, source management, and recent channels.
- Use channel hiding to keep unwanted entries out of the normal guide.
Channel and Program Actions
Select or click a channel to start its primary live stream. Press and hold a channel to open its action menu.
Channel details let you favorite or hide a channel and choose automatic or manual primary stream and EPG matches. Available fallback streams can also be selected.
A current program can offer Watch Now. Program details show ended, on-now, or upcoming status and let you add or remove a reminder.
Catch-Up, Rewind, and Local DVR
Start Over, rewind, and Go Live are conditional. They appear only when Mercurio has a provider catch-up URL, a compatible native DVR path, or enough data in its temporary on-device live buffer.
- Provider catch-up rules and retention windows vary.
- A local buffer starts only after playback begins; it cannot rewind to content the device never buffered.
- Changing streams, closing playback, or clearing app data can discard local buffer history.
- Mercurio does not guarantee catch-up for every IPTV provider, channel, codec, or stream.
Direct-Original First, Plex Fallback When Needed
For a scheduled Mercurio program, the app first prefers a backend-classified Direct Original source. If the active on-device playback engine rejects that source, Mercurio can request the separately classified, backend-owned Plex Fallback. The fallback may use Plex-native transcoding, while Plex tokens and authorization details remain hidden behind backend routes.
The backend identifies the scheduled item, timing, required headers, direct-original source, and whether a Plex fallback exists.
Automatic selects an appropriate on-device engine and remembers source-specific rejection evidence. It does not infer a URL from display metadata.
After a real direct rejection, Mercurio retries the available Plex fallback. If neither classified path is playable, it reports an explicit error.
The backend remains the schedule and resolution authority. Compatibility fallback is generated by Plex and proxied through backend-owned routes; Mercurio does not add a custom backend FFmpeg, remux, or segment-generation service.
Scheduled Playback Actions
- Watch Live calculates and clamps the offset from backend schedule timing.
- Start From Beginning starts the current program at its beginning.
- Start Over and Go Live remain available from playback options when the session supports them.
- Plex Fallback is enabled only when the resolver supplied a valid fallback.
- Browse Guide opens the guide over playback; Return to Guide exits cleanly and restores guide state.
Tracks and Presentation
- Choose preferred audio and subtitle languages and whether subtitles turn on automatically.
- Switch available audio and subtitle tracks from playback options.
- Use Fit to preserve the full image or Fill to crop into the display.
- HDR and codec results depend on the resolved media, active engine, OS, display chain, and any Plex fallback.
Playback Controls
| Action | Apple TV | Mac |
|---|---|---|
| Play or pause | Play/Pause | Space or Return/Enter, depending on focused control |
| Seek | Short Left/Right seeks 30 seconds; hold to accelerate | Left/Right; holding steps through faster rates |
| Show options | Up or Down | Up opens options; Down closes them |
| Show playback HUD | Select | Return/Enter |
| Close or exit | Menu/Back | Escape; from Browse Guide the first Escape returns to the channel and the next exits full screen |
Automated tests cover source classification, fallback selection, timing, redaction, and control commands. They do not prove every codec/display combination or physical Siri Remote behavior. Validate important media on the real Apple TV, receiver, and display chain.
Apple App Settings
Save, clear, and test the manually entered backend URL. The client does not discover servers or administer channels.
Manage sources, default providers, enabled state, favorites, and enriched-guide preferences.
Choose Automatic, AVPlayer First, or Plex Fallback First; set language, subtitles, scaling, and startup behavior.
Choose theme, density, focus style, guide style, and guide sorting preferences.
Inspect connection and playback details, reset playback learning, and inspect or purge backend playback cache entries.
Automatic is the normal direct-first policy. Other startup modes are troubleshooting preferences, not guarantees that unsupported media will play.
Token and Log Safety
- Plex tokens and authorization details remain behind backend-owned playback routes.
- Playback URLs exposed to the app must be classified as Direct Original or Plex Fallback.
- Logs redact tokens, authorization headers, sensitive URL fields, hosts, and media paths.
- Diagnostics should show classification and useful media facts without revealing a reusable credential.
What Is Stored Locally
The backend URL, IPTV source information, favorites, guide preferences, and playback preferences are stored as standard local app preferences. Do not treat those fields as a password vault.
- Do not embed credentials or access tokens in backend or IPTV URLs.
- Apple-local subtitle and playback caches support only the currently resolved media.
- Cache features do not expose a general filesystem or Plex library browser.
Current Limitations
- The Apple apps do not edit channels, schedules, Plex libraries, or backend settings beyond their connection URL.
- Past and future Mercurio programs are details-only in version 1.
- IPTV EPG quality, stream availability, fallback streams, catch-up, and DVR behavior depend on the provider and device buffer.
- Plain HTTP backend URLs are limited to local-network hosts; use HTTPS for non-local deployments.
- If Direct Original and Plex Fallback are both unavailable or rejected, playback fails explicitly.
- Real-device codec, HDR, audio-chain, and Siri Remote compatibility require real-device validation.
Personal Preferences
- UI Mode switches the interface between dark and light rendering.
- UI Theme changes the overall palette.
- Custom Accent overrides the accent color per browser user.
- These preferences are user-specific, so another browser or device can look different.
If you choose a green custom accent here, that accent should carry through shared UI surfaces like buttons, chips, and guide highlights for your current browser user.
Plex Infrastructure
- Server URL should be a reachable Plex address such as
http://192.168.1.100:32400. - Authentication Token is the Plex token the app uses for browsing libraries and writing playlists.
- Test Node is your first health check after changing either field.
- Default libraries only prefill forms. They do not lock every channel to those libraries forever.
Copy the webhook URL shown in Settings into Plex when you want live Dashboard sessions, analytics, Sync Guide alignment, and webhook-triggered playout regeneration.
Timezone affects schedule generation windows, guide clock labels, dayparts, seasonal windows, diagnostics, and analytics. If the guide looks right but starts at the wrong hour, this is the first place to verify.
Time Format switches between `12h` and `24h`. The app now uses 12-hour labels extensively in user-facing schedule and daypart displays when you pick that format.
Default Seasonal Preset provides a starting point for new channels that enable smart seasonal awareness.
- Prioritize Seasonal % and Prioritize Non-Seasonal % define the default mix when a channel uses `Prioritize` mode.
- These values matter most when the channel keeps Use Global Prioritize Ratio enabled.
- If you keep building seasonal channels, saving a solid global default here prevents repetitive channel-by-channel setup.
Global dayparts are reusable named time windows you can attach to any slot in any channel.
- Use Preset Name for a human-friendly label like `Prime Time`, `After School`, or `Weekend Morning`.
- Use Notes to explain why the preset exists.
- Each preset can contain multiple rules with Days, Start, End, and Any time.
- Enabled lets you keep a preset saved without offering it to slots.
Create `Prime Time` with Monday through Sunday, `7:00 PM` to `10:30 PM`, then assign it to multiple sitcom and prestige-drama slots instead of duplicating the same time rules repeatedly.
- Verbose Console Logging increases debug output. Turn it on when investigating hard-to-reproduce schedule issues.
- Decouple Guide Channel Order allows the Network Guide to have its own order independent from Dashboard channel order.
- Plex Profile Targeting unlocks per-playout profile targeting controls so a playout can target all Plex profiles or only selected ones.
If you turn the feature on globally, each playout gains a `Profile Scope` and `Plex Profile Names` section. Leave the scope on `all profiles` unless you specifically want a playlist to sync only to named Plex profiles.
Genres created here are the labels available on the Channel edit page and the values used by Guide genre filters.
- Create a new genre with the New genre name... field.
- Assign genres to channels, not to individual slots.
- If the Guide filter seems incomplete, the missing piece is often that the channel never received the genre tag here.
Media Library Browser
- The Library page is the fastest way to convert Plex media into slots.
- Use the library selector first, then narrow with the search box.
- Collections, playlists, and direct media items can all become channel slots.
- Refresh is useful after Plex finishes a scan or after you add new content.
- Selected cards can be batch-added without leaving the page.
If a library is huge, search before you scroll. Pulling one filtered section is usually faster and easier than browsing the entire source visually.
Single Add vs Bulk Add
- Add to Channel is best when one source needs custom rules.
- Bulk Add to Channel is best when many titles should share the same weight, order mode, filler rules, or time rules.
- Bulk Add exposes reusable time-rule creation so you can stamp the same schedule behavior across many selected items.
Single Add Modal
- Target Channel chooses where the new slot will live.
- Order Mode, Weight, and episode count controls shape how often and how long this source appears.
- Max Picks Per Playlist (Limit) is especially useful for movies or special features that should only appear a fixed number of times.
- Cooldown (H:M:S) forces a rest period before the same slot can return.
- Random Start initializes eligible episodic content at a random point rather than episode one.
- Pre-filler Settings and Post-filler Settings let you attach bumper lists directly while creating the slot.
- Time & Day Programming lets you choose a custom rule, a global preset, or a channel daypart immediately.
Add a sitcom to a weekday afternoon block by setting `Target Channel`, `Weight = 1`, `Random Start = on`, and `Rule Source = Use Global Preset` with a preset like `After School`.
Bulk Add Modal
- Bulk Add repeats the same slot defaults across all selected items.
- Use it for initial channel construction, seasonal blocks, or rebuilding a network quickly.
- You can add one or more custom bulk time rules with Add Rule.
- Rule Source can still point to a global preset instead of bespoke rules if you prefer reuse.
- The resulting slots can be individually edited later from the Slots page.
A good pattern is to bulk-add a whole genre with shared defaults, then hand-edit the few standout slots that need special treatment.
Requests / Overseerr
- The Requests page embeds Overseerr so you can request missing media without leaving Mercurio.
- If the iframe refuses to load, use Open in New Tab.
- Requested media will not appear in the Library page until Plex imports and scans it.
- For fresh-content channels, pair Requests with a playout that has Regenerate when new items are found (Webhook) enabled.
Mercurio AI Features
Mercurio includes two optional AI tools powered by a local Ollama model: AI Search for natural-language Media Library discovery and Programming Director for bounded channel-programming guidance. They are helpers around the existing Plex integration and deterministic scheduler, not replacements for either one.
Describe the kind of show or movie you want in the Media Library. The local model turns the request into bounded metadata hints, Plex supplies candidates, and Mercurio ranks the results.
Read the AI Search workflowGive a channel a brief, analyze selected Plex metadata, review a plan, and optionally let bounded preferences reorder eligible shuffle content through the existing scheduler.
Read the Programming Director workflowPlex remains the source of media metadata. The existing backend scheduler remains the source of truth for channels, eligibility, timing, hard rules, rotation, media resolution, and playout generation. AI can provide bounded hints or soft ranking preferences, but it cannot invent a schedule, create media, or become a second scheduler.
Before You Start
Make Plex and Mercurio healthy
Confirm the backend can reach Plex, the token can read the libraries you need, and the Media Library shows current metadata. AI does not replace a missing Plex connection or an incomplete Plex scan.
Install the local model runtime
The supported Windows setup path is backend\install_program_director.bat. It installs or starts Ollama and downloads the supported local models. The initial download requires network access.
Check the local runtime
Open Programming Director and look for Local model ready. Choose a model that fits the machine: qwen3:4b is the default balanced option, while gemma4:e2b and gemma4:e4b provide smaller and larger Gemma 4 choices. The Executive Console exposes thinking controls for compatible models and keeps them off by default.
Start with the least powerful mode
Use AI Search by turning it on for one library query. For channel programming, begin in Advisory mode, review a preview, and only then consider Semi-autonomous or Autonomous operation.
The normal installer path leaves the global switch off and uses Advisory as the default. Confirm the global switch in Settings, then choose the mode for each channel executive in its channel editor. Advisory mode can prepare recommendations without changing scheduler ordering.
What the Model Sees
- AI Search receives the search request and media type so it can suggest bounded Plex metadata terms.
- Programming Director can receive selected Plex metadata and the channel brief or plan context needed for classification and recommendations.
- The model is not asked to return media URLs, file paths, Plex rating keys for Search, code, or schedule instructions.
- Director profiles, plans, feedback, and campaigns are stored locally by the backend for later ranking and review.
The application uses a loopback Ollama endpoint and rejects remote model endpoints, but local state is still retained on the backend machine. Protect that machine and its application data like other administrative data.
AI Search: Find Media by Description
AI Search is an opt-in switch beside the normal Media Library search field. It is useful when you know the mood, era, subject, or type of media you want but do not know an exact title. For example: hopeful space exploration from the 1980s.
Search Workflow
Open Media Library
Choose a Plex library and the media type you want to browse. AI Search is not available for the playlist browser.
Describe the result
Enter a natural-language request in the search box. Include useful clues such as a title or franchise, genre, studio, collection, themes, content rating, or release period.
Turn on AI Search
Enable the AI Search switch. The request is sent to the local model for a retrieval plan, then Plex is queried for metadata candidates and the results are ranked.
Inspect and add normally
Review the result notice and titles. Add individual items or select several for Bulk Add just as you would with standard search. AI Search does not add a slot or change a channel by itself.
What It Can Plan
- Likely title or franchise phrase.
- Descriptive keywords and summary terms.
- Plex genres, studios, and collections.
- Explicit content ratings.
- Optional release-year bounds.
Try a clear request such as family-friendly animated adventure, funny but not scary, from the 1990s. More specific clues give Plex more useful metadata to retrieve.
It creates a bounded query plan, uses the existing Plex metadata search paths, combines candidates, applies the requested year and rating constraints, and produces a stable ranked result list.
It does not search the contents of video files, inspect a frame for meaning, browse Plex outside the selected library, return playable URLs, alter Plex, create slots, change schedules, or guarantee that every natural-language nuance will match.
If the local model is unavailable, returns invalid structured data, produces no useful hints, or produces no Plex candidates, Mercurio falls back to its existing deterministic metadata search. A fallback notice is evidence that the library search still worked; it is not a claim that the model ranked the final results.
Programming Director: Guide a Channel
Programming Director is a local, reviewable advisor for the existing scheduler. It can classify metadata into semantic profiles, turn a natural-language channel brief into a preference policy, generate a reviewable plan, explain recommendations, learn from feedback, and run dated campaigns. When active, it affects soft ordering of already eligible shuffle candidates rather than deciding whether an item is legal to schedule.
Recommended Setup
Configure the global runtime
In Settings or the AI Executive Director, choose the local model and decide whether the global master switch is enabled. Configure each channel executive's mode and Allow AI cooldown bypass policy in its channel editor while evaluating the feature.
Choose a channel and write a brief
Open Programming Director, select an enabled channel, and describe its identity, audience, tone, energy, pacing, balance, or event goals. Save the brief as the channel policy.
Analyze missing profiles
Choose Analyze Missing Profiles to classify uncached items from that channel's enabled slots. This is not a scan of the entire Plex library. Re-analyze cached items only when you have a reason to refresh them.
Preview before applying
Use Preview Lineup to compare baseline and Director ordering. The preview is non-persisting: it does not write playlist, history, rotation, or media state. From the result, create a playout for the channel or generate an existing playout's schedule. A programming plan is guidance; the existing playout scheduler creates the actual Plex playlist.
Review the plan and choose a mode
Prepare a lightweight approval plan from the saved Executive Policy. It preserves pacing and balance preferences, and converts clear reviewed time-and-energy instructions such as “after 10 PM, use chiller episodes” or “weekday prime time should be high-energy” into bounded runtime guidance. Semi-autonomous plans need approval; Autonomous may publish the latest non-disabled plan automatically.
Regenerate through the normal path
After a plan is approved or published in an active mode, the existing scheduled and Both playouts can be queued. The normal Scheduler Engine and Playlist Writer still generate and sync the output.
Useful Director Tools
- Explain shows why a cached profile fits or conflicts with a policy.
- Human Feedback changes future preference scoring for a profile.
- Temporary Campaign creates a dated event brief, such as a holiday weekend, that must be approved before it influences ranking.
- Channel transition preferences can prefer gradual tone or energy changes in eligible shuffle ordering.
- Program Director Override on a slot can opt Semi-autonomous mode into weighted priority or normal Shuffle item ranking; sequential episode order remains protected.
A saved policy or profile cache is not itself a new playlist. Generate or approve the plan, then let the existing playout generation path produce the next result.
Operating Modes
Creates profiles, briefs, plans, previews, explanations, feedback, and recommendations. It supplies no Director context to the scheduler, so ordering remains unchanged.
Uses approved plans, cached profiles, feedback, pacing preferences, and approved campaigns. Weighted priority or normal Shuffle ranking also require the relevant slot override; sequential episode order remains protected. New plans remain pending until approval.
May use the latest non-disabled plan, including a pending plan, and apply bounded soft ordering without a separate plan approval step. A generated plan is published and existing scheduled or Both playouts can be queued.
What Director Can Influence
- The order of already eligible shuffle candidates.
- Soft weighted slot priority when the active mode allows it.
- Ordered Shuffle item order when the slot scope is enabled or Autonomous mode permits it.
- Tone, energy, pacing, balance, campaign, and feedback-informed preference scores.
- The existing playout output indirectly, when a plan causes the normal generation path to run.
What Director Cannot Override
- Channel and slot eligibility, time restrictions, seasonal filters, or max-pick limits.
- Explicit no-same-show or no-same-season windows, watch-state rules, chronology, or rotation state.
- Media resolution, playlist persistence, or the existing scheduler's hard-order paths.
- Plex metadata authority, media creation, file paths, playback URLs, or a general Plex browser.
- The rule that a model preference is a ranking signal, not a guaranteed exclusion or content-safety filter.
This channel executive setting is off by default. A channel can inherit the global default or explicitly allow it. When it is on and an active Semi-autonomous or Autonomous context exists, the scheduler may bypass slot item-count cooldowns, elapsed-time cooldowns, and the cooldown-derived immediate same-show guard.
It does not apply in Advisory mode and it does not let the model set exact cooldown values. Eligibility, time, seasonal, max-pick, explicit no-same-show and no-same-season windows, watch-state, chronology, rotation, and media-resolution safeguards remain outside this opt-in.
Local Runtime and Data
- Model requests use the loopback Ollama service configured by Mercurio; remote model endpoints are not accepted by the runtime configuration.
- Installing Ollama and downloading a model requires network access once. Runtime inference is intended to stay on the configured local machine.
- Director profile data and related plans, feedback, and campaigns are retained under the backend's local application data so later scheduler runs can reuse them.
- AI Search requests still use the existing web library route and Plex metadata path. Do not put credentials or tokens into search text.
Local inference is not a promise that nothing is logged, retained, or encrypted. Review access to the backend machine, Ollama installation, application logs, and local instance data according to your deployment.
When AI Does Not Respond
- Open Programming Director and check whether the model is ready or the runtime is offline.
- Confirm the selected model is installed and that Ollama is running on the backend machine.
- For AI Search, verify Plex connectivity, the selected library, and the fallback/status notice above the results.
- For Director, verify the global switch, channel executive, saved policy, profile analysis, mode, plan approval, and slot override requirements.
- Check backend Logs for timeout or Plex errors. A larger model may be more capable but slower on a low-memory or busy machine.
AI Search returns to standard metadata search when its local planning path cannot help. Director scheduling keeps the original ordering when profiles, plans, or the local model cannot provide valid guidance.
AI Features FAQ
These answers describe the current bounded implementation. If a result looks surprising, preserve the visible status message and inspect the relevant runtime, scheduler, or Plex evidence before changing settings.
Basics and Visibility
- Channel Name is the human-facing identity of the network.
- Genres feed Network Guide filters.
- Plex Source Library defines where this channel primarily searches for media.
- Programming Method changes how eligible slots compete.
- Quick Template (Optional) can prefill starting behavior.
- Channel Enabled is the master switch for the recipe itself.
- Show in Guide / Generate XMLTV controls whether this channel can contribute guide data.
- Show New Release Badges in Guide marks items as new when release dates are within the last 7 days or up to 14 days ahead, since Plex can future-date episodes that are already available.
- Enable Scheduled Background Generation allows the app to maintain this channel automatically.
Programming Methods
Enable Smart Seasonal Awareness unlocks channel-wide holiday and event logic.
- Seasonal Mode: `Prioritize` boosts seasonal items, `Restrict` tries to filter to them, and `Override` can effectively turn the channel into seasonal-only programming during active windows.
- Prioritize Seasonal % and Prioritize Non-Seasonal % define the ratio when prioritize mode is active.
- Built-in Seasonal Preset can prefill keywords and behavior quickly.
- Seasonal Fallback decides what to do when a seasonal filter would otherwise leave nothing eligible.
- Time Restriction Fallback controls how time and seasonal logic interact when both are strict.
- Use Global Prioritize Ratio makes the channel inherit the percentages defined in Settings.
- Seasonal Rules define recurring windows and keywords.
- Seasonal Exceptions are one-off or date-specific overrides.
A Halloween channel can use a recurring rule from `10-24` to `10-31` with keywords like `halloween, witch, monster`, then add a single-date exception for `10-31` that forces a stronger takeover on the holiday itself.
Enable New Release Prioritization Boost prioritizes newly released episodes on this channel and relaxes cooldowns to allow higher rerun frequency.
- New Release Window (days): Specifies the age threshold since release (e.g.
7days). Episodes released within this window, or future-dated by Plex up to 14 days ahead, are considered newly released. - Target Reruns (count): The number of times a new episode will receive the prioritization boost (e.g.
3plays) before losing its boost status. - Relax Cooldowns for New Releases: When enabled, new release episodes automatically bypass back-to-back same-show restrictions, same-season filters, slot cooldowns, and playlist pick limits to ensure they play immediately.
For slots configured in Shuffle order, any qualifying new release episode is automatically bubbled to the very top of the slot's shuffle pool, ensuring new drops play first.
- Dayparts are reusable time windows that belong only to this channel.
- Import Preset: Click the **Import Preset** button next to "Add Daypart" to immediately copy any of your **Global Daypart Presets** into the channel. Once copied, it becomes a local, independent daypart that you can customize freely.
- Each daypart has a Name, Enabled toggle, optional Notes, and one or more day/time rules.
- Special Events are date-ranged windows that can prioritize or take over only slots with matching Slot Tags.
- Use special events when you want a themed block without turning the entire channel seasonal.
Create a channel daypart called `Late Night` for Friday and Saturday evenings, then create a special event called `Halloween Weekend` with slot tags like `halloween, movie-night` so only tagged slots respond during that event.
Enable Daypart-Specific Weights Mode is an advanced scheduling option that allows a channel to dynamically adjust slot probability ratios throughout the day.
- When active, the virtual clock time is matched against the active dayparts to determine which weights apply.
- Global Daypart Fallback Inheritance: If a channel has this mode active but has no local dayparts defined, the system **automatically falls back to your Global Daypart Presets**. This allows you to manage time segments globally once and use them instantly to balance weights on any channel!
- Natural Schedule Blackouts: By balancing a slot's weight to exactly
0%for a daypart, the slot is naturally avoided and will not schedule during those hours, acting as an easy, visual scheduled blackout window without complex time constraints.
During playout generation, if the virtual time is 8:30 AM, and your active daypart is "Morning Cartoons", the scheduler swaps to use the exact probability weight percentages configured for that daypart, returning to "General" weights outside of active dayparts.
- No Same Show Within X Items spreads repeated series apart.
- No Same Season Within X Items pushes a show to vary seasons before returning.
- No Repeat Episode Days blocks the same specific episode from returning too soon.
- Allow Back-to-Back Movies determines whether a movie slot can follow another movie slot directly.
- These rules operate above slot-level rules, so a slot can still be blocked even when the slot itself looks valid.
- Channel Default Filler List is the general fallback source when filler is enabled.
- Enable Pre-roll (Head of Block) inserts bumpers before blocks.
- Enable Post-roll (Tail of Block) inserts bumpers after blocks.
- Enable Interstitials (Between every X videos) inserts filler between normal content after a configured frequency.
- Allowed Packs can restrict which scanned filler packs are available.
- Channel-level filler rules only work when filler is enabled for the channel.
Use one list for station IDs as pre-roll, one list for outro stingers as post-roll, and a third list for commercials or short promos as interstitials every 3 or 4 normal items.
Slot Types
- Show / series slots from your main library
- Movie slots
- Plex playlist slots
- Collection slots
- Movie Sequence (Manual Pool) for a fixed movie marathon
- Specific Episode(s) (Manual Pool) for a curated episode stack
- Filler List (Collection) when the filler list itself is a primary source
Core Slot Controls
Slot weights determine how often different programs play when a channel is set to Weighted Slots mode.
- Base Weight: High weights mean the slot wins selection competition more frequently. A slot with weight
2is twice as likely to be selected as a slot with weight1. - The Balance Weights Modal: Accessed from the Slots edit page, this workspace helps you visually align all slots' relative probability percentages to sum up to exactly
100%. - Direct Text Input Mode Toggle: Within the modal, you can toggle a text input mode to type percentage values directly. When active:
- Sliders automatically update to reflect your typed percentages.
- Other slots' weights will not automatically shift while typing, allowing you to set precise percentage allocations without friction.
- The form validates that the total percentages sum up to exactly
100%before saving.
- Daypart Weight Grids: If the channel has Daypart-Specific Weights Mode enabled, the balancing modal renders interactive tabs at the top (General, Morning, Prime Time, etc.). This lets you balance slot probabilities independently per daypart!
When Daypart-Specific Weights are active, the slots table shows modern, hoverable tooltip badges (e.g. 🌅 70% | 🌇 30% | 🌃 0%) instead of a single static number, giving you an instant overview of your channel's programming across the entire day.
- Shuffle randomizes eligible items.
- Strict Chronology advances in order and remembers progress.
- Ordered Cycle plays in exact listed order, then repeats from the top.
- Ordered Shuffle preserves a deterministic order through a shuffled cycle.
- Random Season, Then Ordered is useful when you want variety across seasons but continuity inside each picked run.
- Initialize at Random Point is persistent. It picks a random starting episode when a slot is first added or reset.
- Movie Sequence (Manual Pool) is ideal for marathons. When it uses Ordered Cycle, the selected movies play in that exact order.
On a movie sequence slot, Play movies back-to-back overrides the channel-level `Allow Back-to-Back Movies` setting for that slot only.
- Pre-filler Chance % and Pre-filler Count control whether fillers run before the slot content and how many run.
- Pre-filler Lists (with Role) lets you attach multiple lists and choose their role behavior.
- Post-filler Chance % and Post-filler Count do the same after content.
- Post-filler Placement decides whether post-fillers attach after each item or at the tail of a block, depending on the slot and content pattern.
- These slot-level fillers can coexist with channel-level filler rules.
A late-night anime block might use short pre-roll IDs before each show and a post-roll promo only at the end of a multi-episode block.
Behavior (Slot Default) controls how strongly time rules matter by default:
- No Time Restriction makes the slot always eligible.
- Only Play During Matching Rules (Strict) gates the slot entirely.
- Prefer Matching Rules (Weighted) boosts it during matching windows but still allows it outside them.
- Strict & Prioritize Matching Rules both gates and boosts during the match.
Rule Source chooses where the rules come from:
- Slot-Specific Rules for fully custom concurrent windows on this slot only.
- Use Global Preset to reuse a setting-defined daypart across many channels.
- Use Channel Daypart to reuse a channel-local daypart.
Custom Day/Time Rules: Under custom rules, click Add Day/Time Rule to configure multiple concurrent rules. Each rule can have its own days, time window (or Any Time), and independent Rule Behavior override:
- Use Slot Default: Inherits the slot-level master Behavior setting.
- No Restriction / No Prioritize: Slot plays normally on these days/hours without prioritization.
- Only Play During This Rule (Strict): Strictly gated to this rule's window.
- Prefer This Rule (Weighted): Grants a 20x weight boost during this window.
- Strict & Prioritize This Rule: Strictly gated to this window and boosted 20x inside of it.
- Avoid / Block This Rule (Blackout): Prevents this slot from being scheduled during this defined window, creating a localized schedule blackout.
If a slot has multiple rules with restrictive behavior (Strict), they act as an OR gate: the slot is eligible if the current time matches any restrictive rule, and is blocked only if it misses all of them. Prioritization boosts apply whenever a rule matching the current time has prioritize enabled.
Play sitcoms on a strict prime-time schedule on weekdays (Rule 1: Mon-Fri, 7:00 PM to 10:00 PM, Strict & Prioritize), while allowing them to play anytime on weekends with normal priority (Rule 2: Sat-Sun, All Day, No Restriction).
Time exceptions are date-specific overrides and are great for single holidays, finales, or short event blocks.
- Behavior decides whether the slot inherits channel seasonal behavior, always participates, opts out, or uses a special override.
- Keyword Override replaces the channel seasonal keywords for this slot only.
- Special Event Tags connects the slot to channel-level special events using comma-separated tags like `halloween, marathon, movie-night`.
A normal horror slot can carry the tags `halloween, movie-night` so it only gets prioritized during the matching channel event, while the rest of the year it behaves like a standard slot.
Users often add strict time rules, season filters, cooldowns, and max-pick caps all at once. If a channel generates empty, simplify the slot first, prove generation works, then add restrictions back in one layer at a time.
Stable
Best for normal viewing and resume behavior. Use it when you want a longer playlist that can cover several days or a deep item count.
Now
Best for live-ish windows. Often linked to a Stable parent and refreshed more often so the visible lineup stays near the current virtual clock.
Custom
Best for experiments, guide-only outputs, special schedules, or anything that does not neatly fit the Stable/Now pairing.
- Playout Name is the local app name.
- Plex Playlist Name is the name written to Plex when sync is enabled.
- Output Type chooses Stable, Now, or Custom behavior.
- Schedule Duration (Days) generates enough material to cover a date span and overrides item count.
- Item Count caps the lineup by count instead of duration.
- All Eligible tries to exhaust the eligible source pool.
- Linked Parent (Optional) is most often used by Now playouts so they can derive from a Stable source lineup.
- Playout Poster can come from a web URL or uploaded file.
- Start near Virtual Now (Live-ish) is especially useful for Now playouts.
- Show in Plex controls playlist publishing. Show in Guide controls guide publishing.
A classic setup is `Channel Name - Full` as Stable and `Channel Name - Live` as Now, with the Live playout linked to the Full parent.
This section only appears when global Plex Profile Targeting is enabled in Settings.
- Profile Scope decides whether the playout targets all profiles or only selected ones.
- Plex Profile Names accepts one profile name per line.
- If you choose selected profiles, keep the names clean and exact so downstream sync logic can target the intended recipients.
- Generation Mode decides whether the playout is manual, scheduled, or both.
- Interval is ideal for Now outputs that need regular refreshes.
- Daily Time (HH:MM) is ideal for Stable outputs that should refresh once per day.
- Weekly / Multi-Time Rules allow multiple labeled schedule moments with days, times, and notes.
- Quiet Hours define windows where automatic work should avoid running unless forced.
A weekday refresh pattern might regenerate a Stable playout every morning at `03:00`, while a linked Now child refreshes every `60` minutes outside overnight quiet hours.
- Regenerate once schedule is exhausted keeps a playout from running dry.
- Generate Before End creates a safety buffer such as `120` minutes before exhaustion.
- Generate Under is an item-count trigger that helps when runtime lengths vary a lot.
- Regenerate when new items are found (Webhook) reacts to new Plex content for shows used in the playout.
- Webhook Cooldown prevents repeated webhook events from spamming the same output.
- Refresh All regenerates parent schedules and syncs linked live playouts.
- Select visible powers batch actions.
- Generate Selected queues only the chosen playouts.
- Gen & Sync Selected respects parent-child relationships and uses the chain path so linked children are not queued twice.
- Generation Jobs separates active jobs from recent history and supports cancel/retry actions.
- The playout Schedule page is your best debugging page. It shows `Next Scheduled Runs`, `Latest Generation`, `Scheduler Diagnostics`, `Why Slots Were Blocked`, `Slot Notes`, and available diagnostic fixes.
Do not guess. Open the Schedule page, read the block reasons, look for automatic fixes, and only then change slot or channel rules.
Favorites
Favorite channels from the Dashboard to make the `favorites` guide filter immediately useful.
List and EPG Views
List view is best for detailed inspection. EPG view is best for a cable-guide timeline feel.
Live Updates
The page refreshes guide content automatically, and browser-side status updates keep clocks and live indicators fresh.
Guide Tools Explained
- Search in List view asks the server for matching lineup content.
- Filter loaded channels is client-side and only narrows what is already on the page.
- All and Favorites switch the main channel filter.
- Genre filters come from channel genres defined in Settings and assigned on the Channel edit page.
- Guide restores saved display order. A-Z temporarily sorts loaded entries client-side.
- Jump to now centers the EPG near the current moment.
- Guide Setup manages independent guide order when `Decouple Guide Channel Order` is enabled.
- Filler items stay hidden in EPG view for readability. Use List view when you need the full sequence.
How visibility works
- The channel must allow guide generation with Show in Guide / Generate XMLTV.
- The playout must also have Show in Guide enabled.
- The playout must have a generated lineup.
- Your active guide filters must not hide it.
When a user says, "The guide looks empty," walk this exact sequence:
- Confirm the playout generated successfully.
- Confirm the playout `Show in Guide` toggle is on.
- Confirm the channel `Show in Guide / Generate XMLTV` toggle is on.
- Switch the guide filter from `Favorites` to `All`.
- Check whether the channel is missing because guide order is decoupled or filtered by genre.
Filler Manager
- Set the default filler library in Settings before you do anything else.
- Scan Filler Library imports the current filler media so the app can track titles, duration, category, packs, and Plex keys.
- A Plex `Other Videos` library is usually the cleanest source for bumpers, commercials, promos, and station IDs.
- Rescan after adding, removing, or renaming filler media in Plex.
Filler Lists
- Create a list with a List Name and optional description.
- Use Select Filtered and Deselect Filtered to manage large lists faster.
- Attach lists at the channel level, the slot level, or use a filler list as a primary slot source.
- Multiple lists let you separate station IDs, trailers, ads, holiday bumpers, and sponsor blocks cleanly.
How Fillers Fit Into Scheduling
- Channel default filler acts as a global fallback.
- Pre-roll and Post-roll create head/tail branding.
- Interstitials create cadence between normal content blocks.
- Slot pre/post fillers are ideal for per-show bumpers or tailored ad pods.
- Repeated identical media files may be deduplicated by Plex in some playlist scenarios, so use distinct files when repeated variants truly matter.
For a retro network, use a station-ID list as channel pre-roll, an ad-pod list as interstitials every 3 items, and a next-on bumper list as slot post-roll for a few marquee shows.
Dashboard / Network Hub
- The Dashboard shows health, configured sources, channel cards, playout status, and next actions.
- Favorite toggles on channel cards feed the Guide favorites filter.
- Each playout card exposes fast actions like Generate and Config.
- Webhook-fed active sessions appear here so you can see what people are actually watching.
- Dismissed setup actions are user-specific reminders that help keep the dashboard focused.
Analytics
- Pick a channel and a window such as `7`, `30`, `90`, or `180` days.
- Viewer Signals summarizes watch time, devices, users, titles, and active windows.
- Tuning Assistant translates those signals into programming guidance.
- Playout Health helps compare outputs and stability.
- Slot Analytics tells you which sources contribute, which are blocked, and which deserve tuning.
State & History
- Show Pointers (Strict Chronology) shows where ordered sources currently sit.
- Reset on a single pointer restarts that source.
- Reset All States is the nuclear option when you intentionally want all chronology pointers reset.
- Recent episode and filler history explains why anti-repeat logic may be blocking something.
Logs, Requests, and Shutdown
- System Logs helps you confirm write errors, webhook events, and automation failures.
- The Requests page is your built-in Overseerr bridge.
- Shutdown Server intentionally stops the local app process, including the background scheduler and queue.
- If something feels off globally, compare Dashboard health, Logs, and the affected playout Schedule page before making wide changes.
Dashboard for high-level health, Schedule for slot-by-slot reasons, State for chronology pointers, Analytics for long-term behavior, and Logs for raw application events.
Comfort Comedy Channel
A low-maintenance starter setup that feels like a classic rerun network.
- Create a channel with `Weighted Slots` and a TV library.
- Add 10 to 20 comedy shows from Media Library with `Weight` = `1` and `Order Mode` = `Strict Chronology` or `Ordered Cycle`.
- Set `No Same Show Within X Items` to spread repeats out naturally.
- Create one Stable playout for `3` to `7` days and turn on `Show in Plex` and `Show in Guide`.
- Optionally create a linked Now child playout with `Start near Virtual Now` enabled.
When a user asks for the easiest reliable network, this is usually the safest first build.
Holiday Takeover Channel
A normal channel that automatically swings seasonal when a holiday window becomes active.
- Enable `Smart Seasonal Awareness` on the channel.
- Choose `Seasonal Mode` = `Prioritize`, `Restrict`, or `Override` depending on how aggressive the takeover should be.
- Use a built-in preset or add custom `Seasonal Rules` like `12-20` to `12-26` with keywords such as `christmas, santa, holiday`.
- Give slots seasonal override keywords or `Special Event Tags` if only certain slots should react.
- Use Schedule diagnostics after a test generation to confirm seasonal matches are being found.
Use `Override` only when you truly want the entire channel to become seasonal-only during the window.
Movie Night Channel
A movie-heavy channel with controlled repetition and optional back-to-back play.
- Use movie slots, collections, or `Movie Sequence (Manual Pool)` slots.
- Set `Max Picks Per Playlist (Limit)` for big tentpole movies you only want once per cycle.
- Use `Allow Back-to-Back Movies` at the channel level when you want uninterrupted movie blocks.
- If only one slot should ignore that rule, enable `Play movies back-to-back` on that slot.
- Add pre-roll or interstitial filler for trailers, rating bumpers, or idents.
Movie Sequence manual pools are especially useful for marathons, trilogy nights, and custom event ordering.
Guide-Only Test Channel
A safe setup for experiments where you want local lineups and guide data without touching Plex playlists.
- Create the channel and slots normally.
- Create a playout with `Show in Plex` turned off.
- Leave `Show in Guide` enabled if you still want it to appear in the Network Guide.
- Generate locally, inspect the results in Guide and Schedule, then turn on Plex sync later if you like the output.
This is ideal for testing, diagnostics, analytics experiments, or channels you do not want published to Plex yet.
FAQ and Troubleshooting
Start with the layer that owns the failing behavior. Preserve the exact user-readable error and source classification before resetting anything.
Run Test Connection. Fix invalid URL, authentication, TLS, timeout, unreachable-host, or incompatible-backend errors first.
Confirm the backend generated a guide-visible playout with current coverage. The client will not repair or recreate a missing schedule.
Inspect engine, timing, source classification, range support, codec, HDR, and whether a Plex Fallback was actually supplied.
Reset playback learning or purge a cache only after recording the failure. A reset removes evidence and does not create a missing source.
Check source refresh, provider and genre filters, Enriched Only, XMLTV matching, primary/fallback stream selection, and provider catch-up support. A healthy Mercurio schedule does not prove an IPTV provider is healthy.