TizenPortal is a browser shell for Samsung Smart TVs running Tizen OS. It provides a launcher for managing any websites and injects site-specific fixes for TV compatibility (self-hosted apps like Audiobookshelf are a great fit, but not required).
A TV-friendly launcher with customizable themes to manage your sites in one place.
- Grid-based layout optimized for TV remote navigation
- TizenPortal branding with Portal-inspired icon and themes
- Site editor for adding/editing apps with custom names and icons
- Bundle selector for choosing compatibility fixes per-site
Runs as a TizenBrew module to inject fixes into any site.
- Unified Registry System - Features and userscripts managed through a consistent registry-based API
- Declarative bundle system - Bundles are primarily configuration, which can significantly reduce repetitive DOM manipulation code
- Bundle CSS/JS applied automatically
- Element registration API for focusable elements, styling, and DOM manipulation
- Card registration for multi-element interactive cards
- Viewport locking and focus tooling for responsive sites
- Cross-origin safe (iframe access is limited; runtime guards access)
- D-pad navigation with spatial focus
- Color buttons for quick actions:
- 🔴 Red: Address bar overlay
- 🟢 Green: Mouse mode toggle
- 🟡 Yellow: Preferences (portal) / Return to portal (sites)
- 🔵 Blue: Diagnostics panel
This project is designed to be loaded via TizenBrew on your Samsung TV.
- Open TizenBrew on your Samsung TV
- Add Module:
axelnanol/tizenportal - Launch TizenPortal from your TizenBrew dashboard
TizenBrew will open the portal and inject the runtime into all navigated pages.
- Press Enter on the "+" card
- Fill in the site details:
- Name: Display name for the card
- URL: Full URL including
http://orhttps://
- Site-specific Bundle: Select a compatibility bundle
- Icon: Optional - click "Fetch Favicon" or enter a custom URL
- Focus a site card and long-press Enter to open the editor
- Changes auto-save; press Close when finished
- Select a site card and press Enter to open
- Use D-pad for navigation or press 🟢 Green for mouse mode
- Press 🟡 Yellow to return to the portal
Press 🔴 Red to open the address bar overlay with browser controls:
- ⎈ Return to portal 🏠 Site home ← Back → Forward ↻ Reload
- URL field — Press Enter to edit, type a new address
- → Go — Navigate to the entered URL
- ℹ Info — Open TizenPortal documentation
- Press 🟡 Yellow on the portal to open Preferences
- Theme modes: Light, Dark, Automatic (Sunset), Portal (Blue & Orange), Custom Backdrop, Custom Colours
- Debug HUD position: Off / Top Right / Top Left / Bottom Right / Bottom Left
- Portal hints (color button labels)
- Viewport lock mode, focus outline mode, and user agent mode
- Auto-focusable elements, scroll-into-view, safe area inset
- GPU hints, CSS normalization, hide scrollbars
- Text input protection: prevents the TV keyboard from opening until Enter is pressed
| Button | Short Press | Long Press |
|---|---|---|
| 🔴 Red | Address Bar | Reload Page |
| 🟢 Green | Toggle Mouse | Edit Card (portal) / Focus Highlight (sites) |
| 🟡 Yellow | Preferences (portal) / Return to portal (sites) | Add Site (portal) / Return to portal (sites) |
| 🔵 Blue | Diagnostics | Safe Mode |
TizenPortal uses a Universal Runtime architecture:
┌─────────────────────────────────────────────────────────────┐
│ TizenBrew │
│ 1. Loads module from GitHub tag │
│ 2. Opens websiteURL (portal) in browser │
│ 3. Injects tizenportal.js into ALL pages │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Portal Page │
│ - Runtime detects it's on the portal │
│ - Renders site card grid │
│ - User selects card → navigates with #tp= payload │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Target Site │
│ - Runtime detects it's NOT on portal │
│ - Reads #tp= payload for bundle name │
│ - Applies bundle CSS/JS │
│ - Provides overlay UI (address bar, diagnostics) │
└─────────────────────────────────────────────────────────────┘
- Single runtime (
tizenportal.js) on all pages - Cross-origin safe — Payload passed via URL hash; iframe access is guarded
- Full DOM access — Runtime runs in page context
- Bundles compiled in — All bundles included in runtime
- Unified Registry System — Features and userscripts now share a consistent registry-based architecture
- Manifest System — Bundle metadata now defined in manifest.json with validation
- Bundle Options — Bundles can declare per-site options (with URL fetch support)
- Preferences Overhaul — Theme modes, custom colours, backdrop, and HUD position
- Adblock Enhancements — Strict mode, allowlist, cookie/inline heuristics
- Text Input Protection — Prevents OSK auto-popup (toggle in Preferences)
- User Guide — Complete feature walkthrough
- Security Guide — Security features and best practices
- Bundle Authoring — How to create site-specific bundles
- Unified Registry — Registry system for features and userscripts
- Manifest Schema — Bundle manifest.json reference
- API Reference — TizenPortal JavaScript API
- Architecture — System design and structure
- Getting Started — Quick start guide for new users
- FAQ — Frequently asked questions
- Troubleshooting — Common issues and solutions
- Contributing — How to contribute or fork the project
- Adblock Bundle — Usage guide and performance benchmarks
- Audiobookshelf Bundle — Bundle documentation
TizenPortal is designed with security as a priority:
- ✅ Zero vulnerabilities in dependencies (npm audit)
- ✅ Comprehensive input sanitization (XSS prevention)
- ✅ Secure URL handling (blocks javascript:, data:, etc.)
- ✅ Safe DOM manipulation (no eval or innerHTML with user data)
- ✅ Regular security audits (see Security Guide)
Important: Userscripts run with full page access. Only enable scripts you trust and have reviewed. See the Security Guide for details.
| Feature | Support Level |
|---|---|
| Target OS | Samsung Tizen 3.0 - 6.5 |
| Browser Engine | Chrome 47 - 69 (Tizen's Chromium) |
| Tested Apps | ✅ Audiobookshelf |
| Built-in Bundles | default, audiobookshelf, adblock |
This project uses code and inspiration from the following sources:
- WICG/spatial-navigation — Spatial navigation polyfill (
spatial-navigation-polyfillnpm package), modified with cross-origin guards and UMD wrapper fix - Financial-Times/polyfill-library — DOMRect polyfill
- TizenTube — Inspiration and approach for Tizen TV compatibility
- TizenBrew — Module loading platform
This project is licensed under the MIT License - see the LICENSE file for details.