📚 Dokümantasyon 8 Ocak 2025

Muzibu Toplu İşlem Sistemi

HLS Conversion ve AI Görsel Üretimi - Kullanım Kılavuzu

📝 Basit Anlatım (Herkes İçin)

Sisteminiz şarkılar için otomatik olarak iki işlem yapabilir:

🎵 HLS Dönüşümü

MP3 şarkıları küçük parçalara böler ve güvenli streaming formatına çevirir. Böylece şarkılar kolay kolay indirilemez, sadece dinlenebilir.

🎨 AI Görsel Üretimi

Şarkı adından otomatik olarak yapay zeka ile profesyonel albüm kapağı görseli oluşturur. Her şarkıya benzersiz, yüksek kaliteli kapak resmi.

✨ 3 Farklı Kullanım Şekli:

1️⃣ Sadece HLS: Şarkıları streaming formatına çevir (görsel yok)
2️⃣ Sadece Görsel: AI ile kapak görseli oluştur (HLS yok)
3️⃣ Hem HLS Hem Görsel: İkisini birden yap (tam otomatik)

🎯 3 İşlem Modu

MOD 1

Sadece HLS Dönüşümü

🎯 Ne Zaman Kullanılır?

• Zaten görseli olan şarkılar için
• Sadece streaming formatına çevirmek istiyorsanız
• AI görsel üretimi istemiyorsanız
• Hızlı işlem gerekiyorsa

⚙️ Ne Yapar?

• MP3 dosyasını HLS formatına dönüştürür
• Küçük parçalara böler (.ts segments)
• M3U8 playlist dosyası oluşturur
• AES-128 ile şifreler (opsiyonel)

📁 Dosya Konumları

HLS Klasörü:

/var/www/vhosts/muzibu.com/httpdocs/storage/tenant1001/app/public/muzibu/hls/

Şarkı Yapısı:

hls/song-{id}/master.m3u8

💡 Örnek: Song ID: 12345
HLS Path: muzibu/hls/song-12345/master.m3u8

🗄️ Veritabanı Güncellemesi

Tablo: muzibu_songs

Field	Açıklama	Örnek Değer
`hls_path`	M3U8 playlist dosya yolu	`muzibu/hls/song-12345/master.m3u8`
`encryption_key`	AES-128 encryption key	`a1b2c3d4e5f6...`
`is_encrypted`	Encrypt edildi mi?	`true`
`hls_converted_at`	Conversion zamanı	`2025-01-08 23:45:00`

MOD 2

Sadece AI Görsel Üretimi

🎯 Ne Zaman Kullanılır?

• Zaten HLS'i olan şarkılar için
• Sadece kapak görseli eksik şarkılar
• HLS dönüşümü istemiyorsanız
• Sadece görsel yenilemek istiyorsanız

⚙️ Ne Yapar?

• Şarkı başlığını analiz eder (GPT-4)
• Otomatik dil tespiti + çeviri
• Leonardo AI ile görsel üretir
• Media tablosuna kaydeder

🧠 AI İşlemi

1️⃣

GPT-4 Prompt Oluşturma

Şarkı başlığını analiz eder, dil tespit eder, İngilizce'ye çevirir, detaylı fotoğraf prompt'u oluşturur


                                    "Paradise" → "Tropical beach, turquoise water, sunset..."

2️⃣

Leonardo AI Görsel Üretimi

GPT-4'ün prompt'unu kullanarak profesyonel fotoğraf tarzında görsel üretir


                                    Model: Lucid Origin | Boyut: 1472x832px | Stil: GPT-4 seçimi

3️⃣

Görsel İndirme ve Kaydetme

Leonardo AI'dan görseli indirir, Spatie Media Library ile şarkıya bağlar

🗄️ Veritabanı Yapısı

Tablo: media (Spatie Media Library)

Field	Açıklama	Örnek Değer
`model_type`	Bağlı model (Song)	`Modules\Muzibu\App\Models\Song`
`model_id`	Şarkı ID'si	`12345`
`collection_name`	Media collection	`hero` (album cover)
`file_name`	Dosya adı	`song-cover-12345.jpg`
`disk`	Storage disk	`public`
`custom_properties`	AI metadata (JSON)	`{ "generation_source": "ai_generated", ... }`

📦 custom_properties İçeriği:

{
  "generation_source": "ai_generated",
  "generation_prompt": "Album cover art of tropical beach...",
  "generation_params": {
    "model": "leonardo-lucid-origin",
    "size": "1472x832",
    "style": "cinematic",
    "provider": "leonardo",
    "generation_id": "abc-123-def",
    "detected_language": "English",
    "translated_title": "Paradise",
    "tenant_id": 1001,
    "purpose": "song_cover"
  }
}

💡 Önemli: Görsel dosyası media tablosunda, prompt ve AI bilgileri custom_properties JSON field'inde saklanır. Ayrı bir "media_library_items" tablosu YOK!

MOD 3

Hem HLS Hem AI Görsel (Tam Otomatik)

🎯 Ne Zaman Kullanılır?

• Yeni yüklenen şarkılar için
• Hem HLS hem görsel eksik olanlar
• Tek seferde her şeyi halletmek istiyorsanız
• Toplu işlem yapacaksanız

⚙️ Ne Yapar?

• MOD 1 + MOD 2 işlemlerinin tamamını yapar
• Sıralı çalışır: Önce HLS, sonra Görsel
• Her iki veritabanı kaydını günceller
• Paralel queue'lerde çalışır

🔄 İşlem Sırası

HLS Conversion (Queue: muzibu_hls)

MP3 → HLS dönüşümü, song tablosunda hls_path güncellenir

Job: ConvertSongToHLS
Timeout: 300s | Tries: 1

↓ HLS tamamlandıktan sonra

AI Görsel Üretimi (Queue: muzibu_my_playlist)

GPT-4 + Leonardo AI, media tablosuna kayıt

Job: GenerateSongCover
Timeout: 180s | Tries: 1

✅ Sonuç:

• Şarkı HLS formatında streaming'e hazır
• Şarkı AI görseliyle albüm kapağına sahip
• Her iki veritabanı güncel
• Kullanıcı deneyimi tam

🔧 Teknik Detaylar (Geliştiriciler İçin)

📁 HLS Dosya Yapısı

storage/tenant1001/app/public/muzibu/hls/
└── song-12345/
    ├── master.m3u8          # Ana playlist
    ├── stream.m3u8          # Segment listesi
    ├── segment-000.ts       # Video segment 1
    ├── segment-001.ts       # Video segment 2
    ├── segment-002.ts       # Video segment 3
    └── encryption.key       # AES-128 key (opsiyonel)

🎨 Media Storage Yapısı

storage/tenant1001/app/public/
└── 12345/                   # Model ID (Song ID)
    └── song-cover.jpg       # AI generated cover

Database: media tablosu
├── file_name: "song-cover.jpg"
├── disk: "public"
├── collection_name: "hero"
└── custom_properties: { AI metadata }

⚙️ Laravel Queue Sistemi

Queue	İşlem	Timeout	Tries
`muzibu_hls`	HLS Conversion	300s	1
`muzibu_my_playlist`	AI Cover Generation	180s	1

📦 Job Class'ları

Modules\Muzibu\App\Jobs\ConvertSongToHLS

→ MP3 → HLS conversion, song.hls_path günceller

Modules\Muzibu\App\Jobs\GenerateSongCover

→ GPT-4 + Leonardo AI, media tablosuna kayıt

Modules\Muzibu\App\Services\MuzibuLeonardoAIService

→ AI servisi (dil tespiti, çeviri, prompt oluşturma, görsel üretme)

⚠️ Önemli Notlar

💾

Veritabanı Yapısı

"media_library_items" diye bir tablo YOK! Eski sistemde olabilir ama şu an Spatie Media Library kullanılıyor. Tüm media bilgileri media tablosunda, AI prompt ve generation bilgileri custom_properties JSON field'inde.

🔐

HLS Encryption

HLS parçaları AES-128 ile şifrelenebilir. Encryption key encryption_key field'inde saklanır. Şifreleme aktifse is_encrypted = true olur.

🌍

Çok Dilli Destek

AI görsel sistemi otomatik dil tespiti yapar (Türkçe, İngilizce, İtalyanca, İspanyolca, Japonca vb.) ve Leonardo AI için İngilizce'ye çevirir. Dil bilgisi custom_properties.detected_language içinde.

⏱️

İşlem Süreleri

HLS conversion: ~2-5 dakika (şarkı uzunluğuna bağlı)
AI görsel üretimi: ~30-60 saniye (GPT-4 + Leonardo AI)

🚫

Kullanıcı Görseli Kontrolü

Eğer şarkıda zaten manuel yüklenmiş görsel varsa (hasMedia('hero')), AI görsel üretimi ATLANIR. Kullanıcının görseli korunur, AI ezmez.