TvGuide

A Jellyfin plugin that auto-generates virtual TV channels from your media library. Each genre in your library becomes a channel with a deterministic weekly schedule, giving you a classic channel-surfing experience.

Works with all Jellyfin clients out of the box!

How it works

• Scans your library for movies and TV episodes and groups them by genre
• Creates a virtual Live TV channel per genre (Action, Comedy, Drama, etc.)
• Generates a deterministic weekly schedule using a seeded shuffle — the same week always produces the same lineup, so the guide stays consistent across devices
• Streams the current item at the correct seek position via FFmpeg concat, so you drop into whatever is "on" right now

Configuration

All settings are in Dashboard > Plugins > TvGuide.

Bitrate

Setting	Default	Description
Video bitrate (kbps)	4000	H.264 bitrate for the HLS stream. Range: 500–40000.
Audio bitrate (kbps)	384	AAC stereo bitrate. Range: 64–512.

These control the source quality generated by the plugin. Jellyfin may still remux or transcode afterward depending on client capabilities.

Channels

Genre channels are auto-generated from your library. For each genre channel you can:

• Enable/disable — toggle the checkbox to include or exclude it from Live TV
• Rename — enter a display name to override the genre label
• Manage content — click "Content" to expand the item list; uncheck items to exclude them from the channel

Custom channels are manually curated:

• Click Add Channel to create a new custom channel
• Expand "Content" to search for and add Movies or Series
• Remove items with the X button

Library

Click Show Library to browse all Movies and Series with their current channel assignments. Click any item to expand checkboxes for assigning/unassigning it to channels.

OpenAI Suggestions

AI-powered suggestions for assigning unassigned library items to custom channels.

Setting	Default	Description
OpenAI API Key	(empty)	Your OpenAI API key. Required for suggestions.
OpenAI Model	gpt-5-mini	The model to use for suggestions.

To use:

1. Enter your OpenAI API key and click Save
2. Create at least one custom channel
3. Click Get Suggestions — the plugin sends your custom channel names and unassigned library items to OpenAI and returns recommendations
4. Each suggestion shows the item, target channel, and reasoning
5. Click the checkmark to accept a suggestion (adds the item to the channel) or X to reject it
6. Accept All applies all remaining suggestions at once
7. Click Save to persist accepted changes

Items already in a genre channel or custom channel are excluded from suggestions.

Schedule

The weekly schedule is deterministic — the same seed produces the same lineup. To get a fresh shuffle:

1. Go to Dashboard > Plugins > TvGuide
2. Scroll to the Schedule section
3. Click Reshuffle Schedule

This increments the schedule seed, clears all cached schedules, and stops active HLS streams. Any viewers will reconnect to the new schedule automatically. The schedule epoch is saved in the plugin configuration, so it persists across restarts.

Build

Requires Bazel 9+.

bazel build //:TvGuide //:runtime_deps

The output DLLs are at bazel-bin/TvGuide/net9.0/TvGuide.dll and bazel-bin/runtime_deps_out/.

Install

From plugin repository

1. In Jellyfin, go to Dashboard > Plugins > Repositories
2. Add a new repository with the URL:

   https://raw.githubusercontent.com/mattboardman/TvGuide/main/manifest.json
   

3. Go to Catalog, find TvGuide under Live TV, and install it
4. Restart Jellyfin
5. Go to Dashboard > Scheduled Tasks > Live TV > Refresh Guide and run it — your genre channels will appear under Live TV > Guide

Manual install

1. Build the plugin (see above)
2. Copy the DLLs and meta.json into your Jellyfin plugins directory:

mkdir -p /var/lib/jellyfin/data/plugins/TvGuide_1.0.0.0
cp bazel-bin/TvGuide/net9.0/TvGuide.dll /var/lib/jellyfin/data/plugins/TvGuide_1.0.0.0/
cp bazel-bin/runtime_deps_out/*.dll /var/lib/jellyfin/data/plugins/TvGuide_1.0.0.0/
cp meta.json /var/lib/jellyfin/data/plugins/TvGuide_1.0.0.0/

3. Restart Jellyfin
4. Go to Dashboard > Scheduled Tasks > Live TV > Refresh Guide and run it — your genre channels will appear under Live TV > Guide

Development

Updating Jellyfin version

1. Update the Jellyfin package versions in paket.dependencies
2. Run paket update to resolve the new versions and regenerate paket.lock:

   bazel-$(basename $(pwd))/external/rules_dotnet++dotnet+dotnet_x86_64-unknown-linux-gnu/dotnet tool run paket update --group tvguide_deps

3. Regenerate the Bazel dependency file from the updated lock:

   bazel run @rules_dotnet//tools/paket2bazel:paket2bazel -- \
     --dependencies-file $(pwd)/paket.dependencies \
     --output-folder $(pwd)

4. Update targetAbi in meta.json and TARGET_ABI in .github/workflows/release.yml
5. Verify the build:

   bazel build //:TvGuide

License

GPLv3