Player Core Analiz Raporu

Icerik Haritasi

1.1 Dosya Yapisi

Tek bir Alpine.js component (muzibuApp()) icinde her sey tanimli. Modullerin spread ile aktarildigi monolitik yapi:

player-core.js (9.186 satir)
|
|-- Satirlar 1-36      : ensureHlsJs() - HLS.js lazy loader
|-- Satirlar 38-109    : Debug sistemi (pLog, pWarn, console uyari)
|-- Satirlar 111-163   : Cihaz algilama + _mzParam test helper
|-- Satirlar 165-261   : playerDebug(), safeAudioCleanup(), createHlsBlobUrl()
|-- Satirlar 263-315   : Blob URL takibi, XOR decrypt, decryptStreamData()
|-- Satirlar 317-455   : HLS key on-bellek: _hlsKeyCache, CachingKeyLoader
|-- Satirlar 457-678   : HlsPool yoneticisi (2 instance havuz)
|-- Satirlar 680-780   : serverLog() - sunucu tarafli hata loglama
|-- Satirlar 781-9179  : muzibuApp() - ANA COMPONENT
    |-- 781-860   : Spread modules + config + auth state
    |-- 860-940   : Player state degiskenleri (~60 adet)
    |-- 940-1060  : getCoverUrl, updatePlayerColors, getActiveHlsAudio
    |-- 1062-1190 : authenticatedFetch, LRU stream cache, _ensureHlsReady
    |-- 1192-1310 : init() - baslangic fonksiyonu
    |-- 1310-1515 : animateDurationCounter, loadFeaturedPlaylists, preloadLastPlayedSong
    |-- 1519-1718 : togglePlayPause
    |-- 1720-1823 : playRandomSongs, fallbackToPopularSongs
    |-- 1825-2006 : saveQueueState, loadQueueState, loadInitialQueue
    |-- 2008-2406 : loadEmergencyQueue, previousTrack, nextTrack, _safePlayFromQueue, _refillQueue
    |-- 2408-2498 : toggleLike, toggleMute
    |-- 2500-2976 : Crossfade: startCrossfade, createNextHowlerPlayer, createNextHlsPlayer
    |-- 2978-3158 : completeCrossfade, seekTo
    |-- 3160-3697 : Volume, onTrackEnded, Watchdog v3, Spot Player
    |-- 3699-3844 : MediaSession, seekRelative, playContext
    |-- 3846-4382 : playAlbum, playPlaylist, playGenre, playSector, playRadio, playSong
    |-- 4384-5317 : playSongFromQueue (3 yol: preloaded/takeover/fresh)
    |-- 5319-5604 : stopCurrentPlayback, playWithHowler
    |-- 5606-6612 : playHlsStream (tum HLS mantigi)
    |-- 6614-6858 : retryHlsWithNewUrl, triggerMp3Fallback, fadeAudioElement, progress tracking
    |-- 6860-7311 : SPA navigasyon, sarki izleme (track-start/hit/end), kuyruk islemleri
    |-- 7313-7816 : Auth (login/register/forgot), tema, drag-and-drop
    |-- 7818-8340 : Preload sistemi (3 sarki + hover + next song HLS preload)
    |-- 8340-8523 : Buffer saglik sistemi (devre disi)
    |-- 8525-9179 : refreshHlsUrl, queue monitor, background playback, session terminated

1.2 Bagimliliklar (Dependencies)

1.3 Tasarim Desenleri

2.1 init() Fonksiyonu (Satir 1192-1310)

Alpine.js x-init ile cagrilan ana baslangic fonksiyonu. Sira:

1. Double-init guard — _initialized flag kontrolu
2. window._player — Console debug arayuzu olusturma (proxy-safe)
3. HLS Pool lazy init — _hlsPoolReady = false, beforeunload'da destroyAll
4. loadFeaturedPlaylists() — 300ms gecikmeyle (rate-limit onleme)
5. isLoading = false — Icerik hemen gorunsun (no delay)
6. startQueueMonitor() — 10sn interval ile kuyruk kontrolu
7. enableBackgroundPlayback() — visibilitychange + online/offline handler
8. clearPlayerState() — localStorage temizle (her yenilemede temiz baslangic)
9. loadInitialQueue() — API'den kuyruk yukle (3 retry, exponential backoff)
10. MuzibuDeviceProfiler.init() — Cihaz profili (loggedIn ise)
11. Buffer Monitor — Devre disi (bufferHealthEnabled=false)
12. SPA Router — Geri/ileri buton handler (popstate)
13. preloadLastPlayedSong() — localStorage'dan son sarkiyi goster (ama calma)
14. $watch duration — Animasyonlu sure gosterimi
15. setupAutoSave() — queue/volume degisikliklerini $watch ile kaydet

2.2 Global (Module-Level) Baslatma

muzibuApp() disinda, dosya yuklendiginde hemen calisan kodlar:

3.1 Oynatma Tetikleyicileri

3.2 Ana Oynatma Zinciri

Kullanici tiklar
    |
    v
playSong() / playAlbum() / playPlaylist() / ...
    |
    v
Kuyruktaki index belirlenir
    |
    v
playSongFromQueue(index) ← ANA FONKSIYON (Satir 4384-5317, ~930 satir!)
    |
    +--[1] Preloaded Ready Path: _preloadedNext.ready === true
    |      HLS instance + audio element dogrudan devralinir (gapless)
    |
    +--[2] Preload Takeover Path: _preloadedNext var ama ready degil
    |      Preload'un HLS'ini bekle veya tamamla
    |
    +--[3] Fresh Load Path: Preload yok
           |
           v
           Stream URL al (cache veya API)
           |
           v
           decryptStreamData() — XOR + Base64 decode
           |
           +--> stream_type === 'hls' --> playHlsStream()
           |
           +--> stream_type === 'mp3' --> playWithHowler()

3.3 Tum Playback Fonksiyonlari

4.1 HLS.js Lazy Loading

ensureHlsJs() (Satir 17-36): HLS.js kutuphanesi sayfa yuklendiginde degil, ilk ihtiyac aninda yuklenir.

• Promise tabanli, tekrar cagrildiginda mevcut yuklemeyi bekler
• 5 saniye timeout — yuklenmezse false doner
• Kaynak: /themes/muzibu/js/player/lib/hls.min.js

4.2 HlsPool — Instance Havuzu (Satir 457-678)

2 adet HLS.js instance'i havuzda tutar. Her release() aslinda destroy + yeniden olustur yapar (MediaSource sifirlamasi icin).

4.3 CachingKeyLoader (Satir 317-455)

HLS sifreleme anahtarlarini bellekte onbellegeleyen loader. queueMicrotask() ile asenkron cache-serve yaparak "decryptdata unset" hatasini onler.

4.4 ABR (Adaptive Bitrate) Stratejisi

Sarkı baslarken en yuksek kalite (level 3 = high) zorlanir, sonra ABR serbest birakilir:

BASLANGIC:
  hls.currentLevel = startLevel (genelde 3=high)
  hls.autoLevelCapping = startLevel

SERBEST BIRAKMA (2 kosuldan hangisi once olursa):
  1. FRAG_BUFFERED event'i → autoLevelCapping = -1
  2. 5 saniye timeout → autoLevelCapping = -1
  (currentLevel DEGISTIRILMEZ — pause yok!)

SOFT MODE (hls_soft):
  autoLevelCapping = 2 (max mid, high filtrelenir)

Seviyeler: 0=ultralow(32k), 1=low(64k), 2=mid(128k), 3=high(orijinal)

4.5 playHlsStream() Detay (Satir 5606-6612)

~1000 satirlik dev fonksiyon. Onemli noktalar:

• Alpine Proxy Bypass: var _rawHls = HlsPool.acquire() — closure degiskeni, this.hls'e atanmaz (proxy cascade onleme)
• Blob URL obfuscation: createHlsBlobUrl(url) ile gercek URL gizlenir
• ABR Lock/Unlock: MANIFEST_PARSED → startLoad → FRAG_BUFFERED/timeout → unlock
• Hata yonetimi: bufferStalledError sessiz, fragLoadError 401/403 URL yenile, keyLoadError kurtarma, fatal → retry → MP3
• Crossfade tetikleme: timeupdate event'inde kalan sure kontrolu
• 3 katmanli auto-resume: Beklenmeyen pause'da 3 deneme (play stall recovery)
• Safari native path: HLS.js desteklemiyorsa (Safari) native audio.src = m3u8 URL

5.1 playWithHowler() (Satir ~5500-5604)

MP3 fallback modu. HLS basarisiz oldugunda veya format mp3 ise kullanilir:

• new Howl({ src: [url], html5: true, volume }) ile olusturulur
• Event'ler: onload (duration set), onplay (progress tracking baslat), onend (onTrackEnded), onerror (toast mesaji)
• autoplay=true ise howl.play(), false ise sadece yukle
• this.isHlsStream = false olarak isaretlenir

Not: Howler kullanimi giderek azaliyor, HLS ana yontem. MP3 sadece fallback.

6.1 Yapisi ve Yaklasimi

Iki sarki arasi yumusak ses gecisi. Crossfade suresi config'den gelir (varsayilan 7000ms).

TETIKLEME:
  startProgressTracking() veya timeupdate event'inde:
    kalan_sure <= crossfadeDuration/1000 VE !isCrossfading
    → startCrossfade()

AKIS:
  startCrossfade() (Satir 2510)
    |
    +--[Preload hazir] → Preload'un HLS + audio'sunu dogrudan kullan
    |                     removeAllListeners() + sahiplik aktar
    |                     nextAudio.volume = 0 → play() → fadeIn
    |
    +--[Preload yok]  → Stream URL al → createNextHlsPlayer() veya createNextHowlerPlayer()
    |
    v
  Eski player'i fade-out (rAF tabanli), yeni player'i fade-in
  UI hemen guncellenir (yeni sarki bilgisi + progress bar)
    |
    v
  completeCrossfade() (crossfadeDuration sonrasi)
    Eski player yok edilir, yeni player this.hls/this.howl olur
    activeHlsAudioId degistirilir
    Progress tracking yeni player'a baglanir

6.2 Crossfade Fonksiyonlari

6.3 Crossfade State Degiskenleri

7.1 Kuyruk Fonksiyonlari

7.2 Otomatik Doldurma Zinciri

checkAndRefillQueue() — her 10sn
    |
    kalan sarki <= 3?
    |
    v
_refillQueue()
    |
    +--[1] Genre sarkisi al (currentSong.genre_id'den)
    |      API: /api/muzibu/songs/random?genre_id=X&limit=15
    |
    +--[2] Genre bos? → Popular al
    |      API: /api/muzibu/songs/random?sort=popular&limit=15
    |
    +--[3] Popular da bos? → Mevcut kuyrugu karistir ve tekrar cal
    |      (Shuffle Repeat — sonsuz calma)
    |
    v
    Duplicate filtresi: kuyrukta zaten olan sarkilar eklenmez

7.3 Drag & Drop Siralama

Kuyruk icinde sarkilari surukleyerek yeniden siralama (Satir 7730-7816):

8.1 HLS Hata Turleri ve Tepkiler

8.2 Auth Hata Yonetimi

authenticatedFetch() (Satir 1062-1146) tum API cagrilarini sarar:

• 401 + guest: Login modali goster
• 419 (CSRF): Ana sayfa'dan yeni token al, tekrar dene
• 401 + force_logout: handleSessionTerminated() → hard redirect
• 401 + diger: Genel session sonlandirma mesaji
• _handlingAuthError flag: Tekrar deneme dongusu onleme

8.3 Watchdog Timer v3 (Satir 3330-3470)

Her 10 saniyede bir kontrol. 3 anomali tespit eder:

1. Ended Detection: audio.ended === true ama onTrackEnded cagirilmamis → nextTrack(true)
2. 15sn Pause: isPlaying=true ama audio 15sn'den fazla duraklatilmis → auto-resume (play)
3. 20sn Freeze: isPlaying=true ama currentTime 20sn degismemis → nextTrack()

_watchdogBusy flag ile race condition onlenir

8.4 Failed Songs Blacklist

9.1 Blob URL Takibi

activeBlobUrls (Set) ile olusturulan tum blob URL'leri izlenir ve URL.revokeObjectURL() ile serbest birakilir.

9.2 LRU Stream Cache

addToStreamCache() (Satir 1148-1176): Max 30 entry, 5dk TTL. Stream URL'lerini bellekte tutar.

• Her ekleme oncesi expired entry'ler temizlenir
• Limit asilirsa en eski (LRU) silinir
• getCachedStream() URL'deki expires parametresini kontrol eder

9.3 HLS Instance Yonetimi

• HlsPool.release() — her zaman destroy + yeniden olustur (MediaSource sifirlama)
• safeAudioCleanup(audio, removeFromDom) — src temizle, load(), opsiyonel DOM'dan cikar
• beforeunload'da HlsPool.destroyAll()
• Preload temizleme: _cleanupPreloadedNext() — timeout iptal, blob revoke, pool release, DOM cikar

9.4 Diger Bellek Onlemleri

• preloadedSongs Set'i 150'yi asarsa son 75'e kirpilir
• _failedSongs Map'i 5dk TTL ile otomatik temizlenir
• saveQueueState() kuyruktan sadece 22 sarki kaydeder (current +-10)
• Session terminated: streamUrlCache = new Map() (tum cache temizlenir)

10.1 Tum State Degiskenleri (Satir 794-940)

10.2 Computed Properties

Not: Sadece 1 computed property var. Geri kalan her sey fonksiyon veya duz degisken.

11.1 CustomEvent Dispatch (Gonderilen)

11.2 DOM Event Listener'lar

11.3 HLS.js Event Listener'lar

11.4 Alpine.js $watch Listener'lar