Kritik Bug: Şarkı Geçiş Sorunu
MÜŞTERİ ŞİKAYETİSorun Tanımı
Müşteri bildirimi: "Şarkı bittiğinde sonrakine geçmiyor"
Ek sorunlar: Şarkı yarıda kesilip diğerine geçiyor. Sonsuz döngü (continuous play) durduruluyor.
Kod Analizi — Geçiş Zinciri
Şarkı bittiğinde tetiklenen zincir (player-core.js):
audio.onended veya timeupdate fallback (Safari)
Satır 2758 (HLS onended) — Satır 5754-5796 (Safari fallback: son 0.5 sn'de tetiklenir)
onTrackEnded() çağrılır
Satır 2964-3040 — Debounce: 1 sn içinde tekrar çağrılmayı engeller
nextTrack(true) çağrılır — gapless geçiş
Satır 2011-2248 — Concurrent guard: _nextTrackInProgress + 300ms debounce
Queue'da sonraki şarkı VAR → playSongFromQueue()
Normal akış — sorun burada değil
Queue BİTTİ → Genre-based auto-refill
Satır 2088-2247 — API çağrısı: /api/muzibu/genres/{id}/songs — Max 5 deneme, 20 offset
Potansiyel Sebepler (7 Adet)
Queue'daki son şarkı çalındığında genre-based refill API'si çağrılır. API 404/500 dönerse veya genre_id null ise → geçiş durur. Duplikat filtre tüm şarkıları elerse → boş yanıt.
Crossfade sırasında sonraki şarkının stream URL'i alınamıyor (auth token expired, session timeout). Error recovery var ama → playSongFromQueue() da aynı auth sorunuyla başarısız olur → sonsuz hata döngüsü yerine sessizce durur.
Crossfade sırasında yeni HLS player'ın buffer'ı append edemezse → fatal error → player durur. Özellikle eski cihazlarda MediaSource API sınırlaması.
nextTrack() başında _nextTrackInProgress=true yapılır. Exception yaşanırsa finally bloğunda reset edilmeli — eğer reset edilmezse sonraki tüm geçişler engellenir.
Safari fallback mevcut (timeupdate ile son 0.5 sn'de tetiklenir) — ama Safari arka plan tabında timer throttle ederse 0.5 sn penceresi kaçabilir.
4 sn crossfade timeout'u tamamlanmadan şarkı biterse (çok kısa şarkı) veya completeCrossfade() hatası.
Preload ve crossfade aynı anda tetiklenirse, preload cleanup yeni player'ı da bozabilir. _cleanupPreloadedNext() zamanlama sorunu.
Düzeltme Planı
Queue bittiğinde: genre refill başarısızsa → popular songs'tan doldur. O da başarısızsa → shuffle ile mevcut queue'yu tekrar çal (repeat all). Hiçbir durumda player DURMAMALI.
10 sn sonra otomatik reset: setTimeout(() => this._nextTrackInProgress = false, 10000). Exception durumunda kilitlenmeyi önler.
Crossfade sırasında 401 gelirse: token yenile → tekrar dene (1 kez). Başarısızsa: playSongFromQueue() ile sonraki şarkıyı dene. Tüm queue başarısızsa: kullanıcıya bildirim göster ("Oturum süresi doldu, sayfa yenileniyor").
Her onTrackEnded, nextTrack, crossfade adımını serverLog'a yaz. Hangi adımda takıldığını görmek için. Debug panel transition logs'a entegre et.
Karar: Soft Mode Nasıl Aktifleşecek?
Kesin Karar: Hibrit Strateji
Otomatik Açılma
RAM ≤ 2GB veya bağlantı 2G
Öneri Göster
RAM < 4GB veya CPU < 4 çekirdek
Normal Mod
RAM ≥ 4GB ve CPU ≥ 4 ve 3G+
Manuel Kontrol (Her Zaman Erişilebilir)
Karar: Debug Mode Yönetimi
Mevcut Durum
performance-debug.js (180 KB, 3.505 satır) TÜM kullanıcılara HEAD'de yükleniyor. Debug paneli sadece root kullanıcı veya admin panelden "debugger aktif" işaretlenen kullanıcılara görünüyor — ama dosya herkes tarafından indiriliyor.
Yeni Davranış
Debug KAPALI → performance-debug.js HİÇ YÜKLENMESİN
Blade'de @if koşuluna al. Debug kapalıysa 180 KB'lık dosya sunucudan bile istenmez. Tüm kullanıcılar 180 KB + 3-4 MB RAM tasarrufu.
Debug AÇIK → Tüm debug özellikleri aktif (mobil dahil)
Admin panelden kullanıcı için debug açıldığında: performance-debug.js yüklenir, debug panel görünür, transition logs aktif, TTP ölçümü başlar. Mobilde de çalışmalı (responsive panel).
Root kullanıcı → Debug her zaman erişilebilir
Root/admin kullanıcılar için performance-debug.js her zaman yüklenir. Paneli gizle/göster toggle ile kontrol eder.
Karar: HLS / MP3 / Otomatik Seçimi
"Otomatik" Ne Demek?
Kullanıcı veya kurum "otomatik" seçtiğinde sistem şöyle karar verir:
"Otomatik" modunda karar ağacı: 1. Soft Mode AKTİF mi? ├─ Evet → MP3 kullan (Soft Mode = hafiflik = MP3) └─ Hayır → devam et 2. Şarkının HLS dönüştürmesi var mı? ├─ Evet → HLS kullan (kaliteli, adaptive) └─ Hayır → MP3 kullan (dönüştürme henüz yapılmamış) 3. Cihaz HLS destekliyor mu? (Hls.isSupported()) ├─ Evet → HLS └─ Hayır → MP3 (eski tarayıcı fallback)
Kurumsal Hesap Senaryosu
Kurumsal hesapların neden MP3'e zorlanması mantıklı:
Kafe / Restoran
Eski tablet/telefon, WiFi paylaşımlı, gün boyu çalıyor. HLS'in şifreleme overhead'i gereksiz → MP3 yeterli ve stabil.
Spor Salonu
Ses sistemi Bluetooth bağlantılı, kesintisiz çalmalı. MP3 + crossfade = en güvenilir geçiş.
Kurum sahibi kurumsal panelden "Çalma Formatı: MP3" seçer → tüm şubeler ve üyeler MP3 çalar. Ancak bireysel üye kendi profilinden "HLS" seçerse, kurumsal kararı ezer.
HLS Adaptive & Crossfade
HLS Adaptive Bitrate — Mevcut Durum
Sistemde multi-variant playlist desteği mevcut: master.m3u8 → ultralow/playlist.m3u8, low/playlist.m3u8, mid/playlist.m3u8 şeklinde 3 kalite seviyesi var.
Mevcut HLS.js ABR Davranışı (player-core.js)
- Startup Lock: autoLevelCapping = 0 → ilk segment en düşük kalitede
- Unlock: FRAG_BUFFERED event'i gelince veya 3 sn timeout → ABR serbest
- Sonra: HLS.js otomatik bant genişliğine göre kalite ayarlar
Sonuç: HLS adaptive zaten çalışıyor. Ekstra yapılacak: Soft Mode'da HLS kullanılırsa en düşük kalite sabitlenmeli (autoLevelCapping = 0 sabit).
Crossfade — Mevcut Durum & Plan
Şu An
- crossfadeEnabled: false
- crossfadeDuration: 0
- Kod %100 hazır (startCrossfade, completeCrossfade, fade fonksiyonları)
- HLS 2 audio element toggle var
- Howler.js native fade() desteği var
Hedef
- crossfadeEnabled: true (Soft Mode'da)
- crossfadeDuration: 3000 (3 sn)
- Normal mod'da: kullanıcı tercihi (toggle)
- Soft Mode'da: otomatik açık
- Backend'den soft_config.crossfade_duration gönder
Önemli: Crossfade eski cihazlarda donmayı AZALTIR — çünkü yeni şarkı hazırlanırken eski şarkı hâlâ çalıyor. Kullanıcı sessizlik/donma hissetmez.
Kapsamlı TODO List
Tüm iş kalemleri öncelik sırasıyla. Her grubun sonunda ABA test senaryosu var.
Test ortamı: mztest.muzibu.com
A. Kritik Bug Fix — Şarkı Geçiş Sorunu
Öncelik: EN YÜKSEK — Müşteri şikayeti var
A1. Queue auto-refill güçlendirme
Genre refill başarısız → popular songs → shuffle repeat. nextTrack() satır 2088-2247
A2. _nextTrackInProgress güvenlik zamanlayıcısı (10 sn)
Exception durumunda kilitlenmeyi önle. nextTrack() satır 2011
A3. Stream 401 recovery mekanizması
startCrossfade() error handler satır 2498. Token refresh + retry + user notification
A4. Geçiş loglama (serverLog entegrasyonu)
onTrackEnded, nextTrack, crossfade her adımda log. Debug panel transition logs
A5. Şarkı yarıda kesilme koruması
Preload/crossfade race condition düzeltmesi. _cleanupPreloadedNext() zamanlama
ABA Test — Şarkı Geçiş
🎯 GÖREV: Şarkı Geçiş Testi SENARYO: 1. https://mztest.muzibu.com açın 2. Giriş yapın (premium hesap) 3. Herhangi bir şarkıyı çalın 4. Şarkının bitmesini bekleyin (veya sonuna sarın) 5. Sonraki şarkıya otomatik geçiş olduğunu doğrulayın 6. 5 şarkı art arda geçiş testi (skip + doğal bitiş) 7. Queue sonuna ulaşın — auto-refill olduğunu doğrulayın 8. Console'da hata olup olmadığını kontrol edin BAŞARI KRİTERLERİ: ✅ Şarkı bittiğinde sonrakine 3 sn içinde geçmeli ✅ Yarıda kesilme OLMAMALI ✅ Queue bittiğinde otomatik dolmalı ✅ Console'da critical error olmamalı RAPOR: Geçiş süreleri, hatalar, console logları
B. Debug Mode Yönetimi
Öncelik: YÜKSEK — 180 KB tüm kullanıcıları etkiliyor
B1. performance-debug.js koşullu yükleme
app.blade.php → @if($isDebugAllowed) ile sar. Debug kapalı = dosya yüklenmez
B2. Mobil responsive debug panel
performance-debug.js panel CSS'ini mobil uyumlu yap. Touch-friendly butonlar
B3. Admin panel debug toggle UI
Kullanıcı yönetimi → Debug aç/kapat butonu + süre belirle (1 saat, 1 gün, 1 hafta)
ABA Test — Debug Mode
🎯 GÖREV: Debug Mode Kontrol Testi SENARYO: 1. https://mztest.muzibu.com — normal kullanıcı ile giriş 2. Network tab'ı aç → performance-debug.js YÜKLENMEMELİ 3. Sayfanın toplam JS boyutunu not al 4. Admin panelden bu kullanıcı için debug aç 5. Sayfayı yenile → performance-debug.js yüklenmeli 6. Debug panel görünmeli (masaüstü + mobil) 7. Admin panelden debug kapat → sayfayı yenile → yüklenmemeli BAŞARI KRİTERLERİ: ✅ Debug kapalı → performance-debug.js network request'i YOK ✅ Debug açık → panel görünür ve fonksiyonel ✅ Mobilde de panel açılabilir ve kullanılabilir RAPOR: JS boyut farkı, panel screenshot, mobil uyumluluk
C. API Cache & Hızlandırma
Öncelik: YÜKSEK — Şarkı başlama hızı
C1. isPremium() Redis cache (2 saat TTL)
User.php satır 454-472. Cache::remember + recalculateSubscriptionExpiry'de bust
C2. recent/popular/lastPlayed cache
SongController.php. recent: 5dk user-based, popular: 30dk global, lastPlayed: 5dk user-based
C3. trackStart queue'ya taşı
SongStreamController.php satır 271-347. Laravel Job → anında 200 dön
C4. HLS playlist şablon cache
SongStreamController::serveHls() satır 645. Redis 24h, disk I/O + regex kalkar
C5. Rate limiting (throttle) ekle
track-start, track-hit, recent, popular → saatlik limitler
ABA Test — Cache & Performans
🎯 GÖREV: Cache Performans Testi
SENARYO:
1. https://mztest.muzibu.com — premium hesap ile giriş
2. Network tab → /api/muzibu/songs/{id}/stream isteğinin süresini ölç
3. Aynı şarkıyı 3 kez çal → ikinci/üçüncü süreyi karşılaştır
4. /api/muzibu/songs/recent süresini ölç → sayfa yenile → tekrar ölç
5. Ödeme simülasyonu: subscription_expires_at'ı güncelle → isPremium cache bust olduğunu doğrula
BAŞARI KRİTERLERİ:
✅ isPremium: 2. çağrı ≤ 5ms (cache'den)
✅ recent: 2. çağrı ≤ 10ms (cache'den)
✅ Ödeme sonrası: cache anında temizlenmiş, yeni sorgu yapılmış
RAPOR: Her endpoint'in önce/sonra süreleri (ms)
D. Format Seçimi & Soft Mode
Öncelik: ORTA — Altyapı değişikliği gerekli (migration)
D1. Migration: users tablosuna audio_preference + soft_mode kolonları
3 aşamalı onay gerekli! Tenant migration. Default: 'auto'
D2. Migration: corporate_accounts tablosuna audio_preference + soft_mode
3 aşamalı onay gerekli! Tenant migration
D3. ENV: MUZIBU_DEFAULT_AUDIO_FORMAT + MUZIBU_DEFAULT_SOFT_MODE
.env dosyasına ekle. Config dosyası oluştur. Default: 'auto'
D4. Backend: resolveAudioFormat($user) metodu
SongStreamController::stream() içinde 4 katmanlı hiyerarşi uygula
D5. Backend: resolveSoftMode($user) metodu
User model + corporate chain + ENV + cihaz algılama sonucu
D6. Frontend: Cihaz algılama (detectDeviceCapability)
navigator.deviceMemory, hardwareConcurrency, connection.effectiveType kontrol
D7. Frontend: Soft Mode öneri toast
Orta seviye cihazlarda "Hafif Mod Önerisi" bildirimi göster
D8. UI: Player ayarlar ikonu + Soft Mode toggle
Player bar üzerinde dişli ikonu → modal/dropdown → Hafif Mod switch
D9. UI: Profil ayarları sayfasına Çalma Modu bölümü
HLS/MP3/Otomatik seçim + Soft Mode on/off/auto
D10. UI: Kurumsal panel format ayarı
Kurumsal hesap yönetim paneli → Çalma Formatı + Soft Mode ayarları
ABA Test — Format & Soft Mode
🎯 GÖREV: Format Seçim & Soft Mode Testi SENARYO: 1. https://mztest.muzibu.com — premium hesap 2. Profil → Ayarlar → Çalma Formatı: "MP3" seç → kaydet 3. Şarkı çal → stream_type: "mp3" olduğunu doğrula (network tab) 4. Çalma Formatı: "HLS" seç → şarkı çal → stream_type: "hls" 5. Çalma Formatı: "Otomatik" seç → cihaz algılama tetiklenmeli 6. Player'da dişli ikonu → "Hafif Mod" aç → crossfade aktif, debug kapalı 7. Kurumsal hesapla giriş yap → kurum formatı geçerli mi kontrol et BAŞARI KRİTERLERİ: ✅ MP3 seçildiğinde gerçekten MP3 çalıyor ✅ HLS seçildiğinde gerçekten HLS çalıyor ✅ Soft Mode açıldığında crossfade, preload kapalı, debug yüklenmez ✅ Kurumsal format kişisel "Otomatik"i eziyor RAPOR: Her mod için network istekleri, stream_type, geçiş süreleri
E. Crossfade Aktivasyonu
Öncelik: ORTA — Kod hazır, config değişikliği yeterli
E1. Crossfade config backend'den gönder
API response'a soft_config.crossfade + soft_config.crossfade_duration ekle
E2. Frontend crossfade toggle
player-core.js satır 865-866: crossfadeEnabled/Duration dinamik yap
E3. Soft Mode + crossfade entegrasyonu
Soft Mode aktif → crossfade otomatik açılsın (3 sn)
E4. Player UI'da crossfade toggle
Ayarlar modalında "Geçişlerde yumuşak geçiş" switch'i
ABA Test — Crossfade
🎯 GÖREV: Crossfade Testi SENARYO: 1. https://mztest.muzibu.com — premium hesap 2. Crossfade KAPALI durumda: Şarkı bitişini bekle → keskin geçiş 3. Player ayarlar → Crossfade AÇ 4. Şarkıyı sonuna sarı → yumuşak geçiş olmalı (eski fade out + yeni fade in) 5. Skip butonu ile geçiş → crossfade tetiklenmeli 6. 5 şarkı art arda crossfade ile geçiş 7. Ses kesilmesi veya çift çalma olmamalı BAŞARI KRİTERLERİ: ✅ Fade out/in 3 sn içinde tamamlanmalı ✅ İki şarkı aynı anda duyulabilir (overlap dönemi) ✅ Ses kesilmesi yok ✅ Volume tutarlı (yeni şarkı aynı volume'da) RAPOR: Geçiş süreleri, ses kalitesi notları, hata varsa console log
F. Sonsuz Çalma Döngüsü (Continuous Play)
Öncelik: YÜKSEK — Müşteri beklentisi: "Açtım, gün boyu çalsın"
F1. Queue refill fallback zinciri güçlendirme
Genre → Popular → Random → Repeat Queue. Hiçbir durumda durmamalı
F2. Arka plan tab koruması
Tarayıcı arka planda timer throttle ediyor → Web Worker veya Audio Worklet ile koruma
F3. Session keepalive mekanizması
Uzun süreli çalmada auth token expire olmamalı. Periyodik ping/refresh
F4. Memory leak temizliği
Uzun süre çalışınca birikecek: eski Howl/HLS instance'ları, event listener'lar, blob URL'ler
ABA Test — Sonsuz Çalma
🎯 GÖREV: Sonsuz Çalma Dayanıklılık Testi SENARYO: 1. https://mztest.muzibu.com — premium hesap 2. Bir şarkı çalın, 30 dakika boyunca çalmaya bırakın 3. Bu sürede: sayfa arka plana alın (başka tab açın) 4. 30 dk sonra dönün — müzik hâlâ çalıyor mu? 5. Queue'nun otomatik dolduğunu doğrulayın 6. Tarayıcı bellek kullanımını not edin (başlangıç vs 30dk sonra) BAŞARI KRİTERLERİ: ✅ 30 dakika kesintisiz çalma ✅ Arka plan tab'da devam ediyor ✅ Queue otomatik dolmuş (10+ şarkı art arda geçmiş) ✅ Bellek sızıntısı yok (±20MB tolerans) RAPOR: Çalma süresi, geçiş sayısı, bellek kullanımı, hatalar
Uygulama Sırası
| Sıra | Grup | İş Kalemi | Migration | Test |
|---|---|---|---|---|
| 1 | A Şarkı Geçiş Fix | 5 | Hayır | ABA + Manuel |
| 2 | B Debug Mode | 3 | Hayır | ABA |
| 3 | C API Cache | 5 | Hayır | ABA + Performans |
| 4 | E Crossfade | 4 | Hayır | ABA |
| 5 | F Sonsuz Çalma | 4 | Hayır | ABA (30dk) |
| 6 | D Format & Soft Mode | 10 | EVET (4 kolon) | ABA + Manuel |
| TOPLAM | 31 iş kalemi | 4 migration | 6 ABA test | |
Strateji: Migration gerektirmeyen gruplar (A, B, C, E, F) önce yapılır — hızlı deploy. Migration gerektirenler (D) en son — 3 aşamalı onay süreci.