| No active streams |
PrismCast captures live video from web-based TV players by driving a real Chrome browser. It navigates to streaming sites, captures the screen and audio output, and serves the result as HLS streams over HTTP. For TV Everywhere sites that deliver non-DRMed streams, PrismCast can also bypass screen capture entirely and consume the stream directly at full service quality with significantly lower CPU usage. Think of it as a virtual TV tuner for web-based content — it lets Channels DVR (and other applications) record and watch content from streaming sites that do not offer direct video URLs.
PrismCast is built around three priorities, in order:
The ordering is intentional. PrismCast will always choose the reliable path over the fast one.
PrismCast delivers H.264 video with AAC stereo audio at configurable quality presets ranging from 480p to 1080p. Quality presets can be changed in the Configuration tab.
For screen-captured channels, this is not a replacement for native 4K, HDR, Dolby Vision, or surround sound — PrismCast captures directly from Chrome's media pipeline with no video transcoding, which is why tuning is fast and CPU usage stays low. For channels using native HLS streaming (TV Everywhere sites with non-DRMed streams), PrismCast delivers the service's original stream quality without screen capture limitations. The result is good quality video that works well for everyday viewing and DVR recording. PrismCast is designed for content you cannot get any other way in Channels DVR: network streaming sites, free ad-supported TV, and live channels that only exist on the web.
To add PrismCast channels to Channels DVR:
https://prismcast.nfxnicaragua.com/playlist
Individual channels can also be streamed directly using HLS URLs like https://prismcast.nfxnicaragua.com/hls/nbc/stream.m3u8.
PrismCast includes builtin HDHomeRun emulation, allowing Plex to use it as a network tuner for live TV and DVR recording.
192.168.1.100:5004).HDHomeRun emulation is enabled by default and can be configured in the HDHomeRun / Plex configuration tab.
When a client requests a channel, PrismCast navigates Chrome to the streaming site, locates the video player, starts capture, and serves the first HLS segment. How long this takes depends on the channel type:
Sites where PrismCast navigates directly to a player page and video starts automatically. Examples: NBC, ABC, Paramount+, USA Network.
Sites where PrismCast navigates a live TV guide to find and select the channel. The first tune for a given channel is slower because the guide grid must be searched. Examples: Cox Contour TV, DirecTV Stream, Fox, HBO Max, Hulu, Sling TV, Spectrum TV, Xfinity Stream, YouTube TV.
Note: Cox Contour TV and Xfinity Stream players are slow to initialize — expect 15–30 seconds for channel changes. This is a limitation of the web player, not PrismCast.
After the first tune, PrismCast caches channel data for DirecTV Stream, Fox, HBO Max, Hulu, Sling TV, Spectrum TV, YouTube TV. Subsequent tunes skip guide navigation entirely and are comparable to direct URL channels. If cached data becomes stale, PrismCast falls back to guide navigation transparently. Cox Contour TV and Xfinity Stream do not benefit from this optimization — each tune requires a full page load of the player.
Streams stay alive for 30 seconds after the last client disconnects (configurable in the Configuration tab). This means channel surfing in Channels DVR is instant for recently-viewed channels — no re-tuning is needed. Combined with channel caching, the system gets faster the more you use it.
Many streaming channels require TV provider authentication before content can be accessed. To authenticate:
Your login credentials are saved in the browser profile and persist across restarts. You only need to authenticate once per TV provider. The Channels tab shows green and red indicators next to each channel reflecting the last tune result, and authentication badges that confirm which services have active sessions. Some TV providers periodically expire sessions on their end, requiring re-authentication. This is a service limitation, not a PrismCast issue — simply click Login again to re-authenticate.
If PrismCast is running headless or on a remote server, use a VNC client to access the browser for authentication.
PrismCast ships with channels across multiple streaming services, maintained and updated with each release. You can disable any channels you do not need from the Channels tab. The predefined set covers common networks and is a good starting point — enable what you watch and disable the rest. You can also override any predefined channel with your own custom definition (see Overriding Predefined Channels below).
Some channels (Comedy Central, Fox, NBC, etc.) are available from multiple streaming services. The service dropdown on each channel lets you choose which service to use for that channel. Different services may offer different tuning performance.
If you only subscribe to certain streaming services, use the service filter on the
Channels tab toolbar to show only relevant channels. This filter also controls which channels appear in the playlist
that Channels DVR imports — set it before adding the playlist source in the Quick Start. You can also filter
programmatically using the ?service= query parameter on the playlist URL.
The Set all channels to dropdown on the Channels tab toolbar switches every multi-service channel to a single service at once. This is useful when you want all channels routed through one streaming service. The operation can be undone by switching individual channels back or selecting a different service from the same dropdown.
You can add custom channels for any streaming site. Provide a URL, select a site profile, and PrismCast will capture it. For sites with multiple live channels (like a live TV service), the Channel Selector field tells PrismCast which channel to tune to — the expected value depends on the service. When adding or editing a channel, select a profile to see the Profile Reference section with site-specific guidance, including expected channel selector formats for known services.
You can add support for streaming sites that PrismCast does not have builtin support for. The Custom Profiles tab includes a step-by-step wizard that guides you through creating a custom site profile — defining how to enter fullscreen, handle iframes, and interact with the player. You can also export your profiles as service packs to share with other PrismCast users, and import packs that others have created.
To override a predefined channel, create a user-defined channel with the same channel key. Both versions will appear in the service dropdown — yours labeled Custom and the original with its service name. You can switch between them at any time.
For automation and integration with other workflows, see the API Reference tab for the full HTTP API.
See the Help tab for platform-specific requirements and troubleshooting.
Define and manage streaming channels for the playlist. Customized channels are highlighted.
Tip: Use the service filter above to show only channels from services you subscribe to — this also controls which channels Channels DVR sees in the playlist. Use the service dropdown on any multi-service channel to choose which streaming service delivers it (e.g., Comedy Central via Hulu vs Sling). Click the edit icon to customize any channel's name, Gracenote station ID, URL, or other properties.
Define custom site profiles and domain mappings to add support for streaming services not built into PrismCast.
Tip: Use the Profile Builder wizard to create new profiles step by step, or Import a pre-made service pack shared by others. User profiles extend builtin profiles and can override specific behaviors like channel selection strategy or playback controls.
No custom services installed
Custom services let you add support for streaming sites not built into PrismCast. Click New Profile to create one using the step-by-step wizard, or Import a service pack shared by another user.
Export and import configuration and channel data. See the Backup and Migration section in the Help tab for details on what is included, what is not, and how to migrate to a new machine.
Download your current server configuration as a JSON file. This includes all settings (server, browser, streaming, playback, etc.) but does not include channel definitions.
Import a previously saved settings file. After importing, you will need to restart PrismCast for changes to take effect.
Download your custom channel definitions as a JSON file. This includes only user-defined channels, not the predefined channels built into PrismCast.
Import channel definitions from a previously saved file. This will replace all existing user channels.
/root/.prismcast/config.jsonPrismCast provides a RESTful HTTP API for streaming, management, and diagnostics.
POST /config/channels
PUT /config/channels/:key
DELETE /config/channels/:key
GET /config/channels/export
POST /config/channels/import
GET /services/:slug/channels
PUT /config/channels/:key/service
POST /config/service-filter
GET /config/profiles
POST /config/profiles
POST /config/profiles/import
GET /config/profiles/export
GET /channels
GET /streams
DELETE /streams/:id
POST /config
GET /config/export
POST /config/import
| Endpoint | Description |
|---|---|
GET /hls/:name/stream.m3u8 |
HLS playlist for a named channel. Example: /hls/nbc/stream.m3u8 |
GET /hls/:name/init.mp4 |
fMP4 initialization segment containing codec configuration. |
GET /hls/:name/:segment.m4s |
fMP4 media segment containing audio/video data. |
GET /play |
Stream any URL without creating a channel definition. Pass the URL as ?url=<url>. Advanced: &profile= overrides auto-detection, &selector= picks a channel on multi-channel sites, &clickToPlay=true clicks the video to start playback, &clickSelector= specifies a play button element to click (implies clickToPlay). |
GET /stream/:name |
MPEG-TS stream for HDHomeRun-compatible clients (e.g., Plex). Remuxes fMP4 to MPEG-TS with codec copy. |
| Endpoint | Description |
|---|---|
GET /playlist |
M3U playlist of all channels in Channels DVR format. Use this URL when adding PrismCast as a custom channel source. Optional query parameters: ?service= filters by streaming service (?service=yttv, ?service=yttv,sling, ?service=-hulu). ?sort= overrides sort field (name, key, channelNumber, service,profile, stationId, channelSelector). ?direction= overrides sort direction (asc or desc). All parameters are optional and can be combined. Service filter only controls which channels appear in the playlist, not which service is used for tuning. |
Channel definitions, import/export, and predefined channel management.
| Endpoint | Description |
|---|---|
POST /config/channels |
Create a new user channel. Body is the channel object (key, name, url, and optional fields). Returns a channel table patch and a serviceWarning when the new channel's service isn't in the active filter. |
PUT /config/channels/:key |
Replace an existing channel. Body is the full channel object. For predefined channels, the handler computes a delta against the canonical definition; submitting values matching the canonical or a sibling variant implicitly reverts the override. |
PATCH /config/channels/:key |
Partial update from inline cell edits. Body contains exactly one of channelNumber, hdhrEnabled, stationId, or tags. A typed value sets the field; null clears it. |
DELETE /config/channels/:key |
Delete a user channel. Fails if the key is not a user-defined channel. If a predefined version exists with the same key, the returned patch replaces the row with the predefined original. |
POST /config/channels/:key/revert |
Remove a predefined channel override, restoring the predefined defaults. |
GET /config/channels/export |
Export user-defined channels as a JSON file download. |
POST /config/channels/import |
Import channels from JSON, replacing all existing user channels. |
POST /config/channels/import-m3u |
Import channels from M3U playlist. Body: { "content": "...", "conflictMode": "skip" | "replace" } |
POST /config/channels/toggle-predefined |
Enable or disable a single predefined channel. Body: { "key": "nbc", "enabled": true }. Response includes counts with enabled/total for all, east, and pacific scopes. |
POST /config/channels/bulk-toggle-predefined |
Enable or disable predefined channels by scope. Body: { "enabled": true, "scope": "all" | "pacific" | "east" }. Response includes counts with enabled/total for all, east, and pacific scopes. |
POST /config/channels/display-prefs |
Update channel table display preferences: sort field, sort direction, and visible optional columns. Body: { "sortField": "name", "sortDirection": "asc", "visibleColumns": ["channelNumber", "stationId"] }. All fields are optional. Persists to config file. |
Channel discovery, service selection, and filtering for multi-service channels.
| Endpoint | Description |
|---|---|
GET /services/:slug/channels |
Discover all available channels for a service. Returns a JSON array of channel objects with name, channelSelector, and optional affiliate and tier fields. Service slugs: cox, directv, foxone, hbomax, hulu, sling, spectrum, xfinity, yttv. Returns cached results instantly when a prior tune or discovery call has already enumerated the lineup. Add ?refresh=true to clear caches and force a fresh discovery walk. |
PUT /config/channels/:key/service |
Update service selection for a multi-service channel. Body: { "service": "nbc-hulu" } |
POST /config/service-filter |
Set enabled service tags. Body: { "enabledServices": ["hulu", "yttv"] }. Empty array disables filter. |
POST /config/service-bulk-assign |
Assign a service to all multi-service channels. Body: { "service": "hulu" }. Returns { affected, previousSelections, selections } |
POST /config/service-bulk-restore |
Restore previous service selections (undo bulk assign). Body: { "selections": { "nbc": "nbc-hulu", "fox": null } }. A null value restores the channel to its default service. |
Custom site profiles and service pack distribution. Profiles define how PrismCast interacts with a streaming site. Service packs bundle profiles, domain mappings, and optional channels for sharing across instances.
| Endpoint | Description |
|---|---|
GET /config/profiles |
List all user-defined profiles and domain mappings with associated channel counts. |
POST /config/profiles |
Create or update a user-defined profile with optional domain mappings. Body: { "key": "myProfile", "profile": { "extends": "embeddedPlayer", ... }, "domains": { "example.com": { "profile": "myProfile" } } } |
DELETE /config/profiles/:key |
Delete a user-defined profile and its associated domain mappings. |
POST /config/profiles/import |
Import a service pack JSON file. Validates profiles, domains, and optional channels. Body: { "data": { ... }, "skipChannels": false } |
GET /config/profiles/export |
Export user profile(s) as a service pack JSON file download. Query params: ?profile=key1,key2 (required), &channels=1 (include channels), &domains=0 (exclude domains), &name= (pack display name). |
| Endpoint | Description |
|---|---|
POST /auth/login |
Start login mode for a channel. Body: { "channel": "name" } or { "url": "..." } |
POST /auth/done |
End login mode and close the login browser tab. |
GET /auth/status |
Get current login status including whether login mode is active and which channel. |
| Endpoint | Description |
|---|---|
GET /channels |
List all channels (predefined + user) as JSON with source, enabled status, and channel metadata. |
GET /streams |
List all currently active streams with their ID, channel, URL, duration, and status. |
GET /streams/status |
Server-Sent Events stream for real-time stream and system status updates. |
DELETE /streams/:id |
Terminate a specific stream by its numeric ID. Returns 200 on success, 404 if not found. |
Server configuration and backup.
| Endpoint | Description |
|---|---|
POST /config |
Save configuration settings. Returns { success, message, willRestart, deferred, activeStreams } |
GET /config/export |
Export current configuration as a JSON file download. |
POST /config/import |
Import configuration from JSON. Server restarts to apply changes (if running as service). |
POST /config/restart-now |
Force immediate server restart regardless of active streams. Only works when running as a service. |
| Endpoint | Description |
|---|---|
GET /health |
Health check returning JSON with browser status, memory usage, stream counts, and configuration. |
GET /logs |
Recent log entries as JSON. Query params: ?lines=N (default 100, max 1000), ?level=error|warn|info |
GET /logs/stream |
Server-Sent Events stream for real-time log entries. Query param: ?level=error|warn|info |
{
"browser": { "connected": true, "pageCount": 2 },
"captureMode": "ffmpeg",
"chrome": "Chrome/144.0.7559.110",
"clients": { "byType": [{ "count": 1, "type": "hls" }], "total": 1 },
"ffmpegAvailable": true,
"memory": { "heapTotal": 120000000, "heapUsed": 85000000, "rss": 150000000, "segmentBuffers": 25000000 },
"status": "healthy",
"streams": { "active": 1, "limit": 10 },
"timestamp": "2026-01-26T12:00:00.000Z",
"uptime": 3600.5,
"version": "1.0.12"
}
Settings and channel configurations are preserved across updates.
brew upgrade prismcast prismcast service restart
npm install -g prismcast prismcast service restart
Pull the latest image and recreate the container. If using Watchtower, updates are applied automatically.
docker pull ghcr.io/hjdhjd/prismcast:latest docker compose up -d
PrismCast stores all user data in a single directory (default: ~/.prismcast). The files that matter for backup are:
Go to Configuration → Backup to download and import settings and channels as JSON files. This is the easiest way to back up before an upgrade or transfer to another machine.
Copy the data directory (~/.prismcast) or just the three JSON files listed above. To restore, place them in the data
directory on the new machine and restart PrismCast. Docker users should ensure their container's data directory volume is backed up.
Service login sessions are stored in Chrome's profile data, not in the configuration files. After migrating to a new
machine, you will need to re-authenticate with each TV provider through the browser. The health.json file (channel health
and authentication state indicators) is also not exported — it rebuilds automatically as channels are tuned.
PrismCast captures video from Chrome's display output. The capture resolution must be smaller than the physical display resolution because browser toolbars and window chrome consume approximately 100–150 vertical pixels. For example, to capture at 1080p (1920×1080), the display must be larger than 1080p.
When the selected quality preset exceeds what the display can provide, PrismCast logs a warning and automatically degrades to the best available preset. This is not an error — PrismCast is adapting to your display.
macOS works without a physical monitor. Windows and Linux servers without a display need an HDMI dummy plug or a virtual display adapter to provide a display resolution for Chrome to render into.
macOS Screen Sharing and VNC work correctly. Windows Remote Desktop (RDP) does not work — RDP creates a virtual display with different properties that interfere with Chrome's rendering. Use VNC or connect a physical display on Windows.
Chrome on macOS uses GPU hardware acceleration for video encoding, providing the best capture performance. After installing Node.js, go to System Settings → Privacy & Security → App Management and allow Node.js. Use Screen Sharing or VNC for remote access to the PrismCast machine.
Install PrismCast as a service with prismcast service install. See Remote Access above for display capture requirements.
Docker containers support Intel GPU hardware acceleration when an Intel GPU with Quick Sync Video is available on the host.
Pass the GPU device to the container (--device /dev/dri:/dev/dri) for significantly lower CPU usage. The container auto-detects
the GPU and configures acceleration automatically. Without a GPU, the container falls back to software rendering. Access the browser via VNC
for authentication — Docker containers expose noVNC at port 6080.
| Problem | Cause | Solution |
|---|---|---|
| "Browser Offline" or "Browser is not connected" | An existing Chrome process is running. | Quit all Chrome instances, then restart PrismCast. |
| "All tuners in use" despite no active streams | Stale stream state. | Restart PrismCast service. |
| Chrome won't open for login | Running headless or as a service. | Access the PrismCast machine via VNC or Screen Sharing to complete authentication. |
| macOS blocks Node.js after install | App Management security gate. | System Settings → Privacy & Security → App Management → Allow Node.js. |
| Port conflict (address in use) | Another service using port 5589. | Stop the conflicting service, or change the port in Configuration. |
| Slow first tune (~5–10 seconds) | Guide-based services need to search their channel grid on the first tune. | This is normal. Subsequent tunes of the same channel are faster due to caching. Enable channel precaching in Configuration for faster first tunes. |
| "Channel not found" or wrong channel plays | The Channel Selector value does not match the service's guide entry. | Check the log for available channel names. The expected format varies by service — some use display names, others use internal codes. |
| Channel worked before but now fails to tune | TV provider session expired. | Click Login on the channel to re-authenticate with your TV provider. Sessions expire periodically on the provider's end. |
| Cox Contour TV / Xfinity Stream tunes take 15–30 seconds | The web player is inherently slow to initialize. | This is a limitation of the web player, not PrismCast. Each tune requires a full page load of the player. |