MagicMirror Projesi: Spotify durum paneli ve kontrollü müzik komutları

MagicMirror Projesi’nde Spotify alanını yalnız parça adını gösteren bir kart olarak kullanmadık. Oynatma durumu bildirimlerini asistanın okuyabildiği bir anlık görüntüye bağladık; müzik komutları için de belirli modül bildirimlerini kullanan bir köprü ekledik. Bu yazıda hesap adı, cihaz kimliği, çalma listesi ve erişim bilgisi bulunmuyor. Uygulama adımları sürümlü koddan; test kapsamının sınırları tarihli işletim kaydından geliyor.

Panel durumu ile komutu ayırdık

Ön yüz, çalan parça ve oynatım durumuyla ilgili modül bildirimlerini kendi sınırlı durum nesnesine işliyor. Böylece asistanın müzik sorusuna yanıt vermesi için her seferinde bağımsız bir durum zinciri kurması gerekmiyor. Bu önbellek yalnız son bilinen durumu taşır. Bir parçanın ekranda görünmesi o anda ses aygıtından gerçekten çaldığının kanıtı olarak sunulmamalıdır; veri yaşı ve bağlantı durumu ayrıca önemlidir.

Komut tarafında oynat, duraklat, sonraki veya önceki parça, arama ve ses düzeyi gibi işlemleri belirli bildirimlere eşledik. Serbest konuşmayı doğrudan dış hizmet isteğine veya kabuk komutuna çevirmek yerine ayrıştırılmış işlem kullanılıyor. Her komutun hedef cihaz, kapsam ve yanıt koşulları aynı değildir. Spotify'ın hesap, uygulama modu ve uç nokta koşulları güncel belgelerden kontrol edilmelidir; bir uç noktadaki erişim bütün işlemler için yetki sayılmaz.

1. Oynatma durumunu oku
2. Komutu sınırlı bildirime çevir
3. Yetki ve cihazı değerlendir
4. Hız sınırında bekle
5. Güncel durumu yeniden al

Eşzamanlı yenilemeyi tek istekte topladık

Kaynakta birden fazla istek aynı anda erişim yenilemesi istediğinde ortak devam eden işlemi bekleyen bir düzen bulunuyor. Bu, her başarısız çağrının ayrı yenileme başlatmasını azaltmak için eklendi. Yenileme tamamlandığında bekleyen çağrılar sonucu alıyor; hata halinde başarısızlık da aktarılıyor. Bu mekanizmanın varlığı gerçek hesap verisini günlüğe yazmayı gerektirmez ve gizli değerler tarayıcıya taşınmamalıdır.

Saklanan özel yetki verisinin dosya geçişinde geçici dosya ve sınırlı izin yaklaşımı kullanılıyor. Yazı bu özel dosyaların konumunu veya içeriğini yayımlamıyor. Günlük ve hata çıktısında kimlik bilgisi bulunmaması ayrıca denetlenmesi gereken bir konudur; geliştirici hata ayıklama seçeneklerinin varlığı otomatik mahremiyet güvencesi değildir. Üretime taşınacak günlük kapsamı bilinçli biçimde dar tutulmalıdır.

Hız sınırında eski komutu tekrar oynatmadık

Spotify 429 cevabında Retry-After süresinin dikkate alınmasını öneriyor. Modülde bu süreyi izleyen bir bekleme durumu ekledik. Durum sorgusu daha sonra yeniden yapılabilir; fakat birkaç dakika önceki parça geç veya ses değiştir komutunu sonradan otomatik tekrarlamak kullanıcının güncel niyetini bozabilir. Kaynaktaki düzenleme bu eski durum değiştirme isteklerini bekleme sonunda körlemesine yeniden oynatmıyor.

Bağlantı hatası, yetki sorunu ve aktif cihaz bulunamaması aynı hata sınıfına indirilmemeli. Özellikle boş cihaz listesi veya aktif oynatma bulunmaması, panel uygulamasının bütün entegrasyonunun bozuk olduğu anlamına gelmeyebilir. Komut başarı mesajını gerçek hedef durumundan bağımsız üretmek de yanıltıcıdır. Kullanıcıya gönderilmiş istekle gerçekleşmiş oynatımı ayıran bir durum göstermek gerekir.

Gözlem sınırı ve geri dönüş

İncelenen işletim kaydında cihaz sorgusuna başarılı yanıt alındığı, ancak cihaz listesinin boş olduğu ve aktif oynatma bulunmadığı yazıyor. Bu nedenle o kaydı canlı şarkı atlama, arama veya fiziksel ses kabulü geçmiş gibi sunmuyoruz. Yerel Connect hizmetinin çalışması da tek başına hedef cihazın hesapta seçilebilir olduğunu kanıtlamaz. Kodda bulunan işlev ile tamamlanmış uçtan uca kabul farklı kanıtlardır.

Geri dönüşte panel, komut köprüsü ve arka uç istek yönetiminin uyumlu sürümleri birlikte korunmalı. Hesap sırlarını eski kaynak paketiyle gelişigüzel değiştirmeyin. Kontrollü kabulde zararsız test hesabı ve açıkça seçilmiş cihaz kullanılmalı; geciken komut, boş cihaz ve hız sınırı davranışları ayrı sınanmalıdır. Bu yazı bu testleri yeni yapılmış saymaz; yaptığımız entegrasyonu ve dürüstçe korunması gereken sınırlarını anlatır.

Serinin bütün çalışmaları: MagicMirror Projesi.

Nasıl yapılır: ayrıntılı uygulama

Ortam ve ön koşullar: Mevcut yetkili Spotify OAuth backend’i ve playback pilotu — Read playback ve modify playback scope’ları, desteklenen kullanıcı/cihaz ve güvenli kısa ömürlü token gerekir.

1. Yetkili backend oturumunu ve scope’u hazırlayın
2. Token’ı geçmişe yazmadan durum/cihaz okuyun
3. Cihazı seçip kontrollü transfer edin
4. Play/pause ve durum onayını ayırın
5. Hata ve eski komut davranışını kabul edin

1. Yetkili backend oturumunu ve scope’u hazırlayın

Bu akış önceden kurulmuş Spotify OAuth backend’i içindir. Read playback/device ve modify playback scope’larını, uygulamanın güncel Development Mode kullanıcı kısıtlarını ve playback hesabının gereksinimini resmî dashboard/docs üzerinden doğrulayın. Refresh token frontend/config.js içine konmaz.

2. Token’ı geçmişe yazmadan durum/cihaz okuyun

Bash isteminde kısa ömürlü access token alın; gerçek cevap hesap/cihaz bilgisi içerdiği için public loga taşınmaz. Token girilen satır echo edilmez.

read -r -s -p 'Yetkili kisa omurlu access token: ' SPOTIFY_ACCESS_TOKEN
printf '\n'
curl --silent --show-error --fail-with-body -D batuhanyazici-spotify.headers --header "Authorization: Bearer $SPOTIFY_ACCESS_TOKEN" https://api.spotify.com/v1/me/player
curl --silent --show-error --fail-with-body --header "Authorization: Bearer $SPOTIFY_ACCESS_TOKEN" https://api.spotify.com/v1/me/player/devices

3. Cihazı seçip kontrollü transfer edin

Kendi authorized /devices cevabından aktif/kontrol edilebilir cihazı seçin. Aşağıdaki transfer play=false ile otomatik başlatmaz. Python yalnız JSON kodlar; hiçbir secret dosyası okunmaz. Playback için gerekli kullanıcı/cihaz koşulları sağlanmalı.

read -r -p 'Kendi izinli cihaz ID: ' device_id
payload=$(python3 -c 'import json,sys; print(json.dumps({"device_ids":[sys.argv[1]],"play":False}))' "$device_id")
curl --silent --show-error --fail-with-body --request PUT \
  --header "Authorization: Bearer $SPOTIFY_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' --data "$payload" \
  https://api.spotify.com/v1/me/player

4. Play/pause ve durum onayını ayırın

Yalnız izinli cihaz ve kullanıcı eylemiyle aşağıdaki komutları ayrı deneyin. 204 boş başarı gövdesi olabilir; sonuç için yeni GET /me/player okuyun. Kullanıcı müziği zaten dinliyorsa denemeyi koordine edin.

curl --silent --show-error --fail-with-body --request PUT --header "Authorization: Bearer $SPOTIFY_ACCESS_TOKEN" https://api.spotify.com/v1/me/player/play
curl --silent --show-error --fail-with-body --request PUT --header "Authorization: Bearer $SPOTIFY_ACCESS_TOKEN" https://api.spotify.com/v1/me/player/pause

5. Hata ve eski komut davranışını kabul edin

401 için kontrollü tek refresh/single-flight, 403 için scope/account koşulu, 404 için aktif cihaz, 429 için Retry-After ve iptal edilmiş eski action’ı replay etmeme kuralını panel/helper’da uygulayın. Önceki module/helper/config takımına dönün; test sonunda shell’de unset SPOTIFY_ACCESS_TOKEN yapın.

Beklenen sonuç: Yetkili cihazda durum, transfer ve play/pause doğru sırayla kabul edilir; eski komutlar tekrar yürütülmez.

Sonuç farklıysa: Token’ı kabuk geçmişine veya config ekran görüntüsüne yapıştırmayın; 429’da sınırsız tekrar yapmayın.

Geri dönüş: Yeni panel kontrolünü önceki uyumlu sürüme döndürün; iptal edilmiş token’ı tekrar kullanmayın.