ɳTV Setup

This page covers setting up the ɳTV backend and connecting the Flutter app to it. For IPTV-only use, skip to M3U / IPTV: no backend is needed.

Prerequisites

Flutter app:

Flutter SDK 3.10 or later
Dart 3.0 or later (included with Flutter)
A device or simulator for your target platform

Backend:

ɳSelf CLI installed: Installation guide
ɳTV plugin bundle license, buy at nself.org for $0.99/mo

Step 1: Initialize the ɳSelf Backend

ɳTV uses a standard ɳSelf backend. Create one alongside the app:

mkdir -p ntv/.backend
cd ntv/.backend
nself init

nself init walks through project name, domain, and environment settings. For a local development setup, use localhost and accept the defaults.

Step 2: Install ɳTV Plugins

cd ntv/.backend

# 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 (Rust)
nself plugin install recording          # DVR from live streams

Step 3: Build and Start the Backend

nself build
nself start

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

Verify the backend is running:

nself status

The streaming plugin API should be reachable at http://localhost:8000/streaming/library (adjust port to your ɳSelf project config).

Step 4: Get the Flutter App

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

Step 5: Configure the App

Launch the app:

flutter run

On first launch:

Tap Configure Backend on the Library screen (or open Settings from the bottom nav).
Enter your backend URL in the Backend URL field. For local dev: http://localhost:8000. For a remote server: https://your-server.example.com.
Enter your API key if your backend requires authentication (the ɳSelf auth token or a configured static key).
Tap Save Connection.

The Library screen will load your media collection. If it shows an error, check that nself status shows all services healthy and the URL is correct.

Step 6: Add Media

With the backend running and the app connected, add media to your library:

Via the backend: Copy files into the media directory configured in your ɳSelf project .env and run nself media scan (requires media-processing plugin).
Via torrent-manager: Use the nself admin UI at localhost:3021 to add torrents if the torrent-manager plugin is installed.
Via content-acquisition: Configure automated download rules if the content-acquisition plugin is installed.

After adding files and scanning, pull-to-refresh on the Library screen to see new content.

Environment Configuration

Key environment variables for the ɳTV backend (set in nself):

Variable	Description
`MEDIA_PATH`	Directory where media files are stored
`TMDB_API_KEY`	TMDB API key for metadata (required by `tmdb` plugin)
`STREAMING_SEGMENT_DURATION`	HLS segment length in seconds (default: 6)
`STREAM_GATEWAY_AUTH`	Enable bearer token auth on stream URLs (`true`/`false`)

Get a free TMDB API key at themoviedb.org.

Staging and Production

To deploy the ɳTV backend to a remote server:

cd ntv/.backend
nself deploy staging     # deploy to staging server
nself deploy prod        # deploy to production server

The ɳTV Flutter app can point to any reachable backend URL, local, staging, or production. Update the Backend URL in Settings to switch.

Troubleshooting

Symptom	Check
Library screen shows error	`nself status`: all services must be Running
No poster art	`tmdb` plugin installed? `TMDB_API_KEY` set?
Stream fails to play	`stream-gateway` plugin installed? Backend URL reachable from device?
EPG not loading	`epg` plugin installed? EPG sources configured?
Progress not saving	`streaming` plugin installed? Auth token valid?