subopen

opensubtitles.org için unofficial API — IMDB numarasıyla altyazı arama ve indirme.

subTR paketinin kardeşi: turkcealtyazi.org yerine opensubtitles.org'u hedefler, aynı mimariyi (fetchWithRetry + ZIP parse + UTF-8 dönüşümü) kullanır. Film ve dizi ayrımı otomatik yapılır.

Modern, Promise-tabanlı, ES Modules. Node 18+ native fetch kullanır.

Nasıl çalışır?

Sitedeki arama formuna IMDB numarası yazınca site tahmin edilebilir bir GET adresine gider:

https://www.opensubtitles.org/en/search/sublanguageid-{DİL}/imdbid-{IMDB}

Bu paket aynı adresin /xml sürümünü çeker — HTML parse yok, yapılandırılmış XML gelir. İndirme için dl.opensubtitles.org uç noktası kullanılır (token/session gerekmez).

Kurulum

npm install subopen

Kullanım

import { search, download } from "subopen";

// 1. IMDB ile ara (film VEYA dizi — otomatik algılanır)
const result = await search({ imdbId: "tt0111161", lang: "tur" });

if (result.kind === "movie") {
  // Film (veya dizi bölümü): altyazılar hazır
  console.log(result.movie.title);        // "The Shawshank Redemption"
  console.log(result.total);              // 67
  console.log(result.subtitles[0]);
  // {
  //   id: "10749539",
  //   name: "The Shawshank Redemption (1994) - YIFY",
  //   language: "Turkish", iso: "tr", format: "srt", cds: 1,
  //   date: "2024-07-01", rating: 0, downloads: 160,
  //   hd: true, bad: false, uploader: "SubSceneImport",
  //   url: "https://www.opensubtitles.org/en/subtitles/10749539/...",
  //   downloadUrl: "https://dl.opensubtitles.org/en/download/subad/10749539"
  // }

  // 2. Altyazıyı indir
  const { srt, fileName } = await download(result.subtitles[0].id);
  fs.writeFileSync("shawshank.tr.srt", srt, "utf8");
} else {
  // Dizi: sonuç bölüm listesidir; her bölümün kendi IMDB numarası vardır.
  // İstenen bölümün IMDB'siyle search tekrar çağrılır → altyazılar.
  const ep = result.episodes.find((e) => e.season === 1 && e.episode === 1);
  const epResult = await search({ imdbId: ep.imdbId, lang: "tur" });
  const { srt } = await download(epResult.subtitles[0].id);
}

API

search({ imdbId, lang, offset }) → Promise<SearchResult>

opensubtitles.org'da IMDB numarasıyla arar. Sonuç türü kind alanıyla ayrılır — kullanıcının film mi dizi mi bilmesine gerek yoktur.

| Parametre | Tip | Açıklama | |-----------|-----|----------| | imdbId | string \| number | IMDB numarası: "tt0111161", "0111161", 111161 (zorunlu) | | lang | string | Dil kodu: "tur" (varsayılan), "eng", "tur,eng", "all" | | offset | number | Sayfalama başlangıcı; sayfa başına 40 sonuç (varsayılan 0) |

Film sonucu: { kind: "movie", movie, total, offset, subtitles }

| Alan | Açıklama | |------|----------| | movie | { title, year, imdbId, imdbRating } | | total | Toplam sonuç sayısı (tüm sayfalar) | | subtitles | Altyazı dizisi (site sıralamasıyla) |

Dizi sonucu: { kind: "series", movie, episodes }

| Alan | Açıklama | |------|----------| | movie | { title, year: null, imdbId, imdbRating: null } — başlık bölüm adlarından çıkarılır | | episodes | { season, episode, name, imdbId, count }[] — imdbId ile search() tekrar çağrılır |

Dizi bölümlerinin altyazıları, bölümün kendi IMDB numarasıyla sorgulanınca kind: "movie" şeklinde döner (bölüm sayfası tek yapıştır). Bu iki adımlı akış paketin tasarımının parçasıdır — sitenin kendisi de böyle çalışır.

download(subtitleId) → Promise<{ srt, fileName }>

Altyazıyı indirir ve UTF-8 SRT olarak döner.

| Parametre | Tip | Açıklama | |-----------|-----|----------| | subtitleId | string \| number | search() sonucundaki id alanı (örn "10749539") |

Dönüş: { srt: string (UTF-8), fileName: string } — ZIP'ten SRT çıkarılır, CP1254 (Türkçe Windows-1254) encoding UTF-8'e çevrilir.

Özellikler

• ✅ IMDB ile arama (tt öneki, baştaki sıfırlar, sayı girdisi — hepsi kabul)
• ✅ Film/dizi otomatik ayrımı (kind) — dizi ise bölüm listesi + bölüm IMDB'leri
• ✅ Çoklu dil desteği ("tur,eng" gibi)
• ✅ Sayfalama (offset; sayfa başına 40)
• ✅ Altyazı indirme (dl.opensubtitles.org → ZIP → UTF-8 SRT)
• ✅ CP1254 → UTF-8 encoding dönüşümü
• ✅ Timeout + retry (ağ halletarına dayanıklı)
• ✅ Zero-config: API key / login gerekmez
• ✅ HTML scrape yok — resmî XML uç noktası (site tasarım değişikliğine dayanıklı)

Test

npm test

Doğrulanmış test sonuçleri (28/28 geçti)

| Senaryo | Sonuç | |---------|-------| | Film: The Shawshank Redemption (tt0111161, tur) | 67 sonuç, alanlar doğru | | Dizi: Breaking Bad (tt0903747, tur) | kind: "series", 62 bölüm, bölüm IMDB'leri | | Bölüm: S1E1 Pilot (959621, tur) | 9 altyazı | | Çoklu dil: tur,eng (111161) | 215 sonuç, iki dil de var | | Olmayan IMDB (tt999999999) | Boş sonuç, crash yok | | Geçersiz girdi ("abc") | Anlaşılır hata | | Download: 10749539 | 101K UTF-8 SRT, Türkçe karakterler düzgün |

subTR ile farklar

| | subTR | subopen | |---|-------|---------| | Kaynak | turkcealtyazi.org | opensubtitles.org | | Arama | İsim/yıl/IMDB (HTML scrape) | Sadece IMDB (XML uç noktası) | | Dil | Sadece Türkçe | Tüm diller (lang parametresi) | | Dizi davranışı | Sezon/bölüm altyazı alanlarında | Bölüm listesi → bölüm IMDB'siyle 2. arama | | FPS bilgisi | ✅ | ❌ (OpenSubtitles XML'de yok) |

Süreç (adım adım)

search({ imdbId, lang, offset })
  │
  ├─ 1. IMDB normalize ("tt0111161" → "111161")
  ├─ 2. GET /en/search/sublanguageid-{lang}/imdbid-{imdb}[/offset-N]/xml
  ├─ 3. XML'de <search><results><subtitle> satırlarını parse et:
  │     • IDSubtitle'lı satır → altyazı kaydı
  │     • EpisodeName'li satır → bölüm kaydı (bölüm IMDB'si linkte)
  └─ 4. Bölüm satırı varsa → { kind: "series", episodes }
        yoksa             → { kind: "movie", subtitles }

download(subtitleId)
  │
  ├─ 1. GET https://dl.opensubtitles.org/en/download/subad/{id} → ZIP
  ├─ 2. ZIP'ten SRT çıkar (tüm entry'ler taranır, .nfo atlanır)
  └─ 3. UTF-8 dene, bozuksa CP1254 → UTF-8 çevir

Notlar

• Site düz bot isteklerine 401 döndürdüğü için gerçekçi bir Chrome User-Agent gönderilir.
• subtitleserve indirme uç noktası bot koruması (Anubis) arkasında olduğundan dl.opensubtitles.org kullanılır — anonim indirme çalışır.
• OpenSubtitles'ta anonim kullanıcılara günlük indirme limiti uygulanabilir.

Uyarı: unofficial ve best-effort

Bu paket opensubtitles.org'un resmî API'sini kullanmaz; sitenin halka açık XML arama sayfasını ve dl.opensubtitles.org indirme uç noktasını okur. Site bu uç noktalardan birini değiştirirse paket bozulabilir — böyle bir durumda issue açın. Sürümün 0.x'te tutulmasının sebebi tam olarak bu dış bağımlılıktır.

Lisans

MIT