Skip to main content

ɳTV Getting Started

ɳTV Getting Started — ɳSelf documentation.

This guide walks through installing ɳTV and connecting it to a self-hosted ɳSelf backend. If you only want IPTV / M3U live channel support without a backend, skip to Step 4: just clone, run, and add your M3U URL in Settings.

Prerequisites

Flutter app:

  • Flutter 3.10 or later: flutter.dev/install
  • Dart 3.0 or later (included with Flutter)
  • A device or simulator for your target platform

Backend (required for library features):

  • ɳSelf CLI: Installation
  • An nself license key with the ɳTV bundle entitlement ($0.99/mo) : get one at nself.org
  • Docker Desktop (macOS/Windows) or Docker Engine (Linux)

Step 1: Bootstrap the Backend

Create a dedicated directory for the ɳTV backend and initialize it with the ɳSelf CLI:

mkdir ntv-backend && cd ntv-backend
nself init

nself init asks for a project name, domain (use localhost for local dev), and environment settings. Accept the defaults for a local setup.

Step 2: Install ɳTV Plugins

# Set your license key
nself license set nself_pro_xxxxx...

# Required paid plugins
nself plugin install streaming stream-gateway epg tmdb

# Free plugins (no key needed)
nself plugin install torrent-manager content-acquisition subtitle-manager

Optional paid plugins for additional features:

nself plugin install media-processing   # server-side encoding
nself plugin install recording          # DVR from live streams

See Backend Setup for a full plugin reference including environment variables.

Step 3: Build and Start the Backend

nself build
nself start

nself build generates the docker-compose.yml from your plugin configuration. nself start brings all services up.

Verify the backend is ready:

nself status

All services should show as Running. The streaming plugin API is reachable at http://localhost:8000/streaming/library (port may differ based on your project config).

Step 4: Get the Flutter App

git clone https://github.com/nself-org/ntv.git
cd ntv
flutter pub get

Run flutter doctor to confirm your environment is ready. Resolve any issues it reports before continuing.

Step 5: Add Platform Scaffolds

The repository ships with the lib/ source but without generated platform directories. Add them:

flutter create .

This adds ios/, android/, macos/, linux/, windows/, and web/ without touching lib/. Commit the result.

Step 6: Run the App

Pick a platform:

flutter run -d macos      # macOS
flutter run -d chrome     # Web
flutter run               # auto-detect connected device

Step 7: Configure the Backend Connection

On first launch, the Library screen shows a “Configure Backend” prompt (or open Settings from the bottom navigation bar).

  1. Enter your Backend URL. For local dev: http://localhost:8000. For a remote server: https://your-server.example.com.
  2. Enter your email and password for your nself account on that backend.
  3. Tap Connect.

The app stores a JWT in flutter_secure_storage. Subsequent launches skip this step until you log out or switch backends.

Verification

The Library screen loads and shows your media catalog. Tapping a title opens the Player and starts playback. If you have not added media yet, the Library will be empty, see Step 8 below.

If you see errors, see Troubleshooting below.

Step 8: Add Media

With the backend running, add media to your library:

  • Manual: Copy files into the directory configured in your backend .env as MEDIA_PATH, then run nself plugin run media-processing scan to trigger discovery.
  • Via torrent-manager: Open the nself admin at http://localhost:3021 and use the torrent client UI (requires torrent-manager plugin).
  • Via content-acquisition: Configure automated download rules in the plugin settings.

After adding files, pull-to-refresh on the Library screen to see new titles.

For IPTV / M3U Only

No backend is needed for live TV via M3U playlists:

  1. Open Settings in the bottom nav.
  2. Scroll to the IPTV section.
  3. Tap Add M3U URL and enter your playlist URL.
  4. Tap Add. Channels load immediately.

Troubleshooting

SymptomCheck
”No backend reachable”Run nself status on the backend. Confirm the URL and port.
Library is emptyRun nself plugin run media-processing scan on the backend. Check TMDB_API_KEY is set in .env.
Playback failsnself status must show streaming and stream-gateway as Running.
No poster artTMDB_API_KEY must be set in your backend .env.
EPG not showingepg plugin must be installed and your channels must have tvg-id values.

Next Steps