Nuvio Sağlayıcı Başlangıç Şablonu

Nuvio ekosistemi için sıfırdan özel dizi ve film sağlayıcıları (scraper / provider) geliştirmek amacıyla tasarlanmış minimal, modüler ve açık kaynaklı başlangıç şablonudur.

Bu depo, sıfır harici bağımlılıkla ve saf TypeScript ile yazılmış tam işlevsel bir referans sağlayıcı (HDFilmCehennemi) içerir.

---

Mimari ve Proje Yapısı

nuvio-starter/
├── manifest.json              # Sağlayıcı yapılandırma ve metaveri dosyası
├── package.json               # Derleme araçları ve komutlar (Sıfır çalışma zamanı bağımlılığı)
├── tsconfig.json              # TypeScript derleyici ayarları
├── build.js                   # esbuild derleyici scripti (Bağımsız JS çıktısı üretir)
├── dev-server.js              # Canlı hot-reload destekli yerel HTTP geliştirici sunucusu
└── src/
    ├── types.ts               # Temel Nuvio arayüz ve tip tanımları
    └── hdfilmcehennemi/
        └── index.ts           # Referans sağlayıcı motoru

---

Çalışma Mantığı ve Temel Kavramlar

Kullanıcı Nuvio üzerinden bir içerik seçtiğinde, uygulama eklentideki getStreams fonksiyonunu tetikler:

+--------------------+     1. TMDB ID      +----------------------+
| Nuvio Uygulaması   | ------------------> |  getStreams(id, ...) |
+--------------------+                     +----------------------+
                                                      |
                                                      v
                                           +----------------------+
                                           | TMDB -> IMDb Çözümü  |
                                           +----------------------+
                                                      |
                                                      v
                                           +----------------------+
                                           | Sitede Arama Sorgusu |
                                           +----------------------+
                                                      |
                                                      v
                                           +----------------------+
                                           | Bölüm / Sayfa Eşleme |
                                           +----------------------+
                                                      |
                                                      v
                                           +----------------------+
                                           | Oynatıcı & VTT Çözüm |
                                           +----------------------+
                                                      |
                                                      v
+--------------------+   6. NuvioStream[]  +----------------------+
| Oynatıcı (1080p)   | <------------------ | Akış Objesini Döndür |
+--------------------+                     +----------------------+

1. TMDB ID'den IMDb ID'ye Dönüşüm

Nuvio uygulaması içerik kimliği olarak TMDB ID (örn: 550) iletir. Birçok film ve dizi sitesinin arama altyapısı kesin eşleşme için IMDb ID (örn: tt0137523) gerektirir.

• getImdbId fonksiyonu TMDB external IDs API'sini kullanarak imdb_id değerini çözümler.

2. Sitede Arama ve Katalog Taraması

Elde edilen IMDb ID veya içerik başlığı ile hedef sitenin arama uç noktasına sorgu atılır (/search?q=tt0137523).

3. Hedef Sayfa ve Dizi Bölüm Eşleştirmesi

• Film ise: Doğrudan film sayfası URL'si alınır.
• Dizi ise: Dizi ana sayfasına bağlanılarak ilgili sezon ve bölüm bağlantısı (örn: sezon-1/bolum-1) tespit edilir.

4. Oynatıcı Şifre Çözümü (Decryption)

Oynatıcı iframe sayfası çekilir ve içindeki JavaScript şifrelemeleri (atob/btoa veya eval paketleri) bellek üzerinde çalıştırılarak doğrudan .m3u8 HLS akış adresi elde edilir.

5. Altyazı Standart Şeması (Bilinmeyen / Unknown Hatasını Önleme)

Nuvio oynatıcısının altyazıları tanıyabilmesi ve arayüzde "Unknown" olarak listelememesi için şu standart şema kullanılır:

Alan	Tip	Açıklama	Örnek
id	string	Benzersiz altyazı indeksi	"0"
url	string	Doğrudan WebVTT (.vtt) altyazı bağlantısı	"https://..."
lang	string	ISO 639-1 standart dil kodu	"tr"
language	string	Oynatıcı tanımı için İngilizce dil adı	"Turkish"
name	string	Kullanıcı arayüzünde görünen yerelleştirilmiş isim	"Türkçe"
label	string	Oynatıcı menüsündeki etiket	"Türkçe"
title	string	Alternatif başlık etiketi	"Türkçe"
type	string	Altyazı dosya formatı	"vtt"
headers	object	Gerekli HTTP başlıkları (Referer, User-Agent)	{ ... }

6. Standart Akış Çıktısı (NuvioStream)

Elde edilen tüm veriler Nuvio'nun standart akış dizisi formatında döndürülür:

return [
  {
    name: 'HDFilmCehennemi',
    title: 'Dublaj / Altyazılı',
    description: '1080p • HLS',
    quality: '1080p',
    format: 'm3u8',
    url: 'https://cdn.site.com/hls/master.m3u8',
    subtitles: subtitles,
    headers: {
      Referer: 'https://oynatici.site.com/',
      'User-Agent': 'Mozilla/5.0...'
    }
  }
];

---

Kurulum ve Yerel Geliştirme

1. Bağımlılıkları Yükleyin

npm install

2. TMDB API Anahtarını Tanımlayın

TheMovieDB adresinden ücretsiz bir API anahtarı alın ve src/hdfilmcehennemi/index.ts dosyasına yazın:

// src/hdfilmcehennemi/index.ts
const TMDB_API_KEY = 'BURAYA_KENDİ_TMDB_API_ANAHTARINIZI_YAZIN';

3. Geliştirici Sunucusunu Başlatın (Canlı Test)

npm run dev

Sunucu çıktısı:

======================================================
[DevServer] http://localhost:3000 üzerinde aktif
Manifest URL: http://localhost:3000/manifest.json
======================================================

4. Nuvio Uygulamasına Bağlayın

1. Nuvio uygulamasını açın (Desktop, Mobil veya Android TV).
2. Ayarlar -> Plugins bölümüne gidin.
3. Adres çubuğuna http://localhost:3000/manifest.json adresini yapıştırın ve ekleyin.
4. src/ klasöründe yapacağınız her değişiklik anında otomatik olarak derlenir.

5. Üretim Derlemesi (Build)

Canlıya almak üzere tek parça dağıtım dosyası üretmek için:

npm run build

Çıktı dosyası: providers/hdfilmcehennemi.js.

---

Yeni Bir Sağlayıcı Ekleme

1. src/ altında yeni bir klasör oluşturun (örn: src/yenisaglayici/index.ts).
2. getStreams fonksiyonunu standart NuvioStream dönüş tipine uygun olarak yazın.
3. Yeni sağlayıcıyı manifest.json dosyasına kaydedin:

   {
     "id": "yenisaglayici",
     "name": "Yeni Sağlayıcı",
     "description": "Film ve Dizi",
     "version": "1.0.0",
     "author": "Geliştirici Adınız",
     "supportedTypes": ["movie", "tv"],
     "filename": "providers/yenisaglayici.js",
     "enabled": true
   }

4. npm run build komutu ile derleyin.

---

Lisans

Bu proje MIT Lisansı kapsamında lisanslanmıştır.