Watch folders for new media files, scan them into your ɳTV library, deduplicate by content hash, and kick off the enrichment pipeline — automatically, the moment a file lands.
Acts as the entry point for the ɳTV ingest pipeline — nself-file-processing → nself-tmdb → nself-media-processing → nself-streaming.
nself license set nself_pro_...
nself plugin install file-processing
nself build
nself startnself-file-processing uses inotify (Linux) or FSEvents (macOS) to watch configured directories for new or modified files. When a media file appears, it computes a SHA-256 content hash, checks for duplicates in the library, and registers the file in the ɳTV media registry. Duplicates are flagged and optionally auto-deleted or soft-linked.
After registration, the plugin fires the enrichment pipeline: it calls nself-tmdb (for movies and TV episodes) or nself-game-metadata (for ROMs) to attach metadata, then submits a transcode job to nself-media-processing if the file format or codec is not in the approved list. Approved formats (H.264 MP4, AAC audio) skip transcoding and go directly to nself-streaming for HLS manifest generation.
Watch paths are configured per media type — separate paths for movies, TV shows, music, podcasts, and ROMs. The plugin reads path structure to infer type: files under the configured movies path are treated as movies; files under the TV path are parsed for S01E03-style naming. Override detection via the POST /files/ingest endpoint with an explicit type field.
| Variable | Required | Description |
|---|---|---|
DATABASE_URL | Yes | Postgres connection string (auto-set by nself) |
FILE_WATCH_PATHS | Yes | JSON map of media type to watch path, e.g. {"movies":"/media/movies","tv":"/media/tv"} |
FILE_STORAGE_BUCKET | Yes | Object storage bucket for uploaded/moved media files |
FILE_DEDUP_POLICY | No | How to handle duplicates: flag, delete, or symlink. Default: flag |
FILE_APPROVED_CODECS | No | Comma-separated codecs that skip transcoding. Default: h264,aac,mp3 |
FILE_SCAN_ON_START | No | Scan all watch paths on plugin startup. Default: true |
FILE_MAX_CONCURRENT_SCANS | No | Parallel file hashing workers. Default: 4 |
| Endpoint | Method | Description |
|---|---|---|
/files | GET | List all registered media files with ingest status |
/files/ingest | POST | Manually trigger ingest for a specific file path or URL |
/files/:id | GET / DELETE | Get file record or remove it from the library (does not delete from disk) |
/files/scan | POST | Trigger a full rescan of all watch paths |
/files/duplicates | GET | List all detected duplicate files with their hashes |
/health | GET | Plugin health, active watch paths, scan queue depth |
| Table | Purpose |
|---|---|
np_media_files | Registry of all ingested files: path, type, hash, size, codec, ingest status, enrichment status |
np_media_duplicates | Duplicate pairs: primary file ID, duplicate file ID, resolution policy |
| Event | Payload |
|---|---|
file.ingested | File ID, path, type, hash, size, codec detected |
file.duplicate.detected | New file ID, existing file ID, hash, policy applied |
file.enrichment.queued | File ID, enrichment plugin targeted (tmdb / game-metadata) |
nself-file-processing is the ingest entry point for the entire ɳTV media pipeline. Drop a file into a watch path and the pipeline runs: ingest → metadata enrichment via nself-tmdb or nself-game-metadata → transcode via nself-media-processing → stream via nself-streaming. You can also push files directly via POST /files/ingest from external scripts or download managers.
Files not detected: Confirm the watch path is mounted and accessible inside the container. Pass the path via Docker volume mount in your nself config. Run GET /health to verify active watch paths. inotify watch limits can be low on default Linux installs — increase with sysctl fs.inotify.max_user_watches=524288.
All files going to transcode: Set FILE_APPROVED_CODECS to include the codecs in your collection. Run ffprobe <file> to identify codec — most modern MP4/MKV H.264 files should skip transcoding by default.
Port: 3517 (moved from 3089) | Bundle: ɳTV ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.0.13