Laravel AI SDK: Uygulamanıza 20 Dakikada Metinden Sese ve Ses Ekleme

Kaynak: hafiz.dev

Taylor Otwell’in X üzerinde yayınladığı bir paylaşım, dikkatimi anında çekti:

$audio = Str::of('Hello, Laravel')->toAudio();

Tek bir metod çağrısıyla metniniz ses kaydına dönüşüyor. Harici SDK ayarları, Guzzle çağrıları ve API yanıtlarını ayrıştırmak yok. Tıpkı ->upper() veya ->slug() metodlarını çağıralar gibi, ->toAudio() metodunu bir Stringable nesnesi üzerinde çağırabilirsiniz.

Laravel AI SDK’sını 1. bölüm ve 2. bölüm üzerinden takip ediyorsanız, metin üretimi ve araç çağrılarının nasıl çalıştığını biliyorsunuzdur. Ancak, SDK’nın çoğu geliştirici tarafından kullanılmayan bir tarafı var: ses. Metinden-sese üretimi, ses özelleştirme, sesten-metine transkripsiyon, kuyruk işleme ve test desteği tümüyle entegre edilmiştir.

Bu makalede, bu özellikleri kullanarak bir Laravel uygulaması geliştireceğiz.

Geliştireceğiniz Uygulama

Bu eğitimin sonunda, Laravel uygulamanız şunları yapabilir:

• Herhangi bir metni doğal sesle ses kaydına dönüştürüp saklayabilir
• Erkek, kadın veya belirli ses kimlikleri arasında seçim yapabilir
• AI’dan sesin nasıl olması gerektiği konusunda ipuçları verebilir (ton, hız, duygu)
• Yüklenen ses dosyalarını metne dökebilir (konuşmacı tespiti ile)
• Arka planda ses üretimi için kuyruklayabilir
• Tek bir API çağrısına bile ihtiyaç duymadan her şeyi test edebilir

Kurulum

Önceki bir eğitiminizden AI SDK kuruluysa bu bölümü atlayın. Aksi takdirde:

composer require laravel/ai

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

php artisan migrate

Gerekli sağlayıcı kimlik bilgilerinizi .env dosyanıza ekleyin. Ses için aşağıdakilerden en az birine ihtiyacınız var:

OPENAI_API_KEY=your-openai-key
ELEVENLABS_API_KEY=your-elevenlabs-key

OpenAI hem metinden-sese hem de sesten-metine desteği sağlamaktadır. ElevenLabs da ikisini desteklemekte, Mistral ise transkripsiyonu gerçekleştirmektedir. Sağlayıcı desteği hakkında daha fazla bilgi için ana dokümanlara başvurabilirsiniz.

Kurulum için bu kadar. Şimdi ses üretimi yapalım.

İlk Ses Üretiminiz

Audio facade’ı temiz ve akıcı bir API sunuyor:

use Laravel\Ai\Audio;

$audio = Audio::of('Your order has been shipped and will arrive by Thursday.')->generate();

$audio nesnesi ham ses içeriğini tutar. Bunu bir dizeye çevirerek byte’leri alabilir veya doğrudan saklayabilirsiniz:

// Varsayılan diskine sakla
$audio->store();

// Belirli bir yol ve dosya adı ile sakla
$audio->storeAs('audio', 'order-confirmation.mp3');

// Genel diskine sakla
$audio->storePublicly();

Kontrolörden doğrudan sunmak ister misiniz? Bir yanıt olarak döndürebilirsiniz:

Route::get('/audio/preview', function () {
    $audio = Audio::of('Welcome to our support line.')->generate();

    return response((string) $audio)
        ->header('Content-Type', 'audio/mpeg');
});

Şu anda çalışan bir ses uç noktanız var. Kodunuzda bir yere hızlı bir yöntem eklemeniz gerekirse, Stringable entegrasyonu daha da kısadır:

use Illuminate\Support\Str;

$audio = Str::of('Hello, Laravel')->toAudio();

Bu Taylor’ın tweetlediği şeydi. AI SDK’sı toAudio() metodunu Stringable sınıfına kaydeder, böylece ->replace(), ->trim() veya diğer dize yöntemleriyle bir arada zincirleme yapabilirsiniz. Bu, vektör araması için kullanılan ->toEmbeddings() ile aynı düzende çalışır.

Ses Seçimi

SDK size ses kontrolü için üç yol sağlar:

// Hızlı cinsiyet seçimi
$audio = Audio::of('Welcome back!')->female()->generate();
$audio = Audio::of('Your package is ready.')->male()->generate();

// Belirli bir ses ID'si veya adı ile
$audio = Audio::of('Breaking news: Laravel 14 announced.')->voice('alloy')->generate();

OpenAI, alloy, ash, coral, echo, fable, nova, onyx, sage, shimmer ve verse dahil 11+ ses sunmaktadır. Her biri farklı bir karaktere sahiptir. alloy nötr ve dengeli bir ses olup, çoğu kullanım durumu için uygundur. Ses nesnesiyle daha doğal çıkan sesler elde edilirken, OpenAI daha hızlı ve ucuzdur. Hızlı bildirimler mi? OpenAI. Uzun anlatımlar veya ürün tanıtımları mı? ElevenLabs, fazladan maliyeti karşılayabilir.

Tarz Talimatları

Bu kısımda işler ilginçleşiyor. instructions metodu, AI’yı sesin nasıl olması gerektiği konusunda yönlendirmekte:

$audio = Audio::of('Ahoy! Your treasure has arrived!')->female()->instructions('Speak like a friendly pirate captain')->generate();

$audio = Audio::of('We regret to inform you that your account has been suspended.')->male()->instructions('Professional and empathetic, slow pace')->generate();

instructions metodunu ses için bir sistem komutu olarak düşünebilirsiniz. Ton, hız, duygu, aksan stili ve teslimat biçimini kontrol edebilirsiniz. Her zaman mükemmel şekilde isabet etmeyebilir (bu sağlayıcıya bağlıdır), ancak çoğu kullanım durumu için fark edilir bir iyileşme sağlar. “Neşeli ve upbeat”, “sakin ve ölçülü” ya da “acil, bir haber spikeri gibi” gibi talimatlar deneyin.

Beş Uygulama Örneği

İlerleyen kısımlara geçmeden önce, derinlemesine inmek isteyebileceğiniz bazı örnekler:

1. Blog yazısı sesli versiyonları. Bir gönderi yayımlandığında ses dosyası üretilsin. Gönderi ile birlikte saklayın ve HTML5 ses oynatıcıyı gömün. Erişilebilirlik artacak ve okuyucuları daha uzun süre sayfada tutar.

// Post gözlemcinizde veya etkinlik dinleyicinizde
$audio = Audio::of($post->plain_text_content)->female()->instructions('Conversational and clear, like a podcast host')->generate();

$audio->storeAs('posts', "post-{$post->id}.mp3");

2. Sipariş onaylama sesli mesajları. E-ticaret uygulamaları, siparişi özetleyen kısa bir ses kaydı oluşturabilir ve bunu onay e-postasına ekleyebilir veya “teşekkür ederiz” sayfasında gösterebilir.

3. Uygulama içi sesli bildirimler. Bildirimlerin yanında sesli alternatifler üretin. Erişilebilirlik için veya ekran okuma imkânlarının kısıtlı olduğu ortamlarda oldukça yararlıdır.

4. Etkileşimli sesli yanıtlar. Basit bir IVR sistemi kurun. Çıkış tarafında TTS kullanırken, girişte transkripsiyon gerçekleştirin. Ses üretimi için Twilio SDK’sına ihtiyaç yoktur.

5. Dil öğrenme araçları. Dinamik telaffuz örnekleri oluşturun. Farklı aksanlar veya konuşma hızları için çeşitli instructions geçirin.

Sesten-Metine Transkripsiyon

SDK, ters yönde de çalışır. Bir ses dosyanız varsa bunu metne dönüştürebilirsiniz:

use Laravel\Ai\Transcription;

// Diskteki bir dosyadan
$text = Transcription::fromStorage('recordings/meeting.mp3')->generate();

echo (string) $text; // "Alright team, let's review the Q2 numbers..."

Ayrıca ham dosya yolundan da transkripte edebilirsiniz:

$text = Transcription::fromPath('/tmp/uploaded-audio.webm', 'audio/webm')->generate();

Bu, dosya yüklemeleri ile doğal olarak eşleşir. Tipik bir kontrolör şöyle görünebilir:

public function transcribe(Request $request)
{
    $request->validate([
        'audio' => 'required|file|mimes:mp3,wav,webm',
    ]);

    $path = $request->file('audio')->store('temp');

    $text = Transcription::fromPath(
        Storage::path($path),
        $request->file('audio')->getMimeType()
    )->generate();

    Storage::delete($path);

    return response()->json([
        'text' => (string) $text,
    ]);
}

Bu, tamamlanmış bir ses-metin dönüşüm uç noktasıdır. Doğrulama ve temizleme dahil 20 satırdır. OpenAI API’sini manuel olarak Guzzle ile ayarlayıp birden fazla parçalı yüklemeleri yönetmekten çok daha basit.

Bir şey göz önünde bulundurulmalıdır: Transkripsiyon sağlayıcılarının dosya boyutu sınırları vardır. OpenAI’nin Whisper modeli, 25MB’a kadar dosyaları kabul eder. Daha uzun kayıtlar için sesi parçalara ayırmanız gerekiyor. Bunu FFmpeg ile iyi bir şekilde yapabilirsiniz; Laravel’in Process facade’ını kullanarak çalıştırabilirsiniz:

use Illuminate\Support\Facades\Process;

Process::run("ffmpeg -i input.mp3 -f segment -segment_time 300 -c copy chunk_%03d.mp3");

Bu, kaydı 5 dakikalık parçalara ayırır. Her birini transkripte edin ve sonuçları birleştirin.

Konuşmacı için Diğerleyici (Diarization)

Toplantı kayıtları veya çoklu konuşmacı sesleri için SDK, konuşmacıların kim olduğunu belirlemek için destek sunar. Bu, otomasyona alınmış toplantı notları, çağrı merkezi analitiği veya podcast transkripsiyonu işlemleri için faydalıdır.

Tüm sağlayıcılar aynı şekilde çalışmamaktadır. OpenAI’nin yeni GPT-4o Transcribe modeli yerel olarak desteklerken, eski Whisper modeli bunu desteklememektedir. ElevenLabs da desteklemektedir. Bu özelliğin kesin metod zinciri ve sağlayıcı gereksinimleri için resmi AI SDK belgelerine başvurun.

Kuyrukta Ses Üretimi

Ses üretimi zaman alır, özellikle uzun metinler için. Kullanıcıları, blog gönderisinin seslendirildiği süre boyunca bir bekleme simgesiyle baş başa bırakmak istemezsiniz. Kuyruklayın:

Audio::of($post->plain_text_content)
    ->female()
    ->instructions('Conversational, like a podcast')
    ->generateQueued();

SDK, kuyruk sistemi‘ne bir görev gönderir. Ses üretiminden sonra bir şey yapmanız gerekiyorsa (saklamak, kullanıcıya bildirmek), bir geri çağırma ile zincirleme yapabilirsiniz:

Audio::of($post->plain_text_content)
    ->female()
    ->instructions('Conversational, like a podcast')
    ->generateQueued()
    ->then(function ($audio) use ($post) {
        $audio->storeAs('posts', "post-{$post->id}.mp3");

        $post->update(['has_audio' => true]);
    });

Bu, blog gönderisi seslendirmesi için kullanacağım düzendir. Gönderiyi yayımlayın, ses işini kuyruklayın ve dosya hazır olduğunda gönderi kaydını güncelleyin. Okuyucunun ses oynatıcısını, işlendiğinde görmesi mümkündür.

Sağlayıcıları Değiştirme

Varsayılan olarak, SDK, config/ai.php‘de yapılandırdığınız sağlayıcıyı kullanır. Ancak, istenen talep başına sağlayıcıyı değiştirebilirsiniz:

use Laravel\Ai\Enums\Lab;

// Yüksek kaliteli ses için ElevenLabs kullan
$audio = Audio::of('Premium audio content')->generate(Lab::ElevenLabs);

// Daha hızlı, daha ucuz üretim için OpenAI kullan
$audio = Audio::of('Quick notification')->generate(Lab::OpenAI);

AI SDK genelinde, birden fazla sağlayıcıyla tek bir API’deki bu düzeni tanıyorsunuzdur. Tek bir SDK, tek bir API, çoklu sağlayıcılar.

API Çağrıları Olmadan Test Etme

Test kümeniz her çalıştığında OpenAI’nin API’sini çağırmak istemezsiniz. SDK’nın yerleşik taklitleri vardır:

use Laravel\Ai\Audio;
use Laravel\Ai\Transcription;

it('generates audio for a new post', function () {
    Audio::fake();

    $post = Post::factory()->create();

    // Ses oluşturma kodunuz...

    Audio::assertGenerated(function ($audio) {
        return str_contains($audio->text, 'order has been shipped');
    });
});

it('transcribes uploaded audio', function () {
    Transcription::fake();

    // Transkripsiyon kodunuz...
    
    Transcription::assertGenerated();
});

Audio::fake(), HTTP isteklerini engeller ve doğru girdiyle üretimin yapılmış olduğuna dair doğrulama yapmanıza olanak tanır. Http::fake(), Mail::fake() veya Queue::fake() ile aynı düzeni kullanır.

Üretim Düşünceleri

Gerçek kullanıcılara ses özelliklerini dağıtmadan önce düşünmeniz gereken bazı hususlar:

Aşırı önbellekleme. Aynı metin aynı sesi üretiyorsa, sonucu saklayın ve bir sonraki sefer diskten sunun. İçeriği değiştirilmediği sürece ses üretimini tekrar gerçekleştirmeyin. Blog yazıları için, yayımlandığında bir kez oluşturun ve saklanan dosyayı sürekli sunun. İçerik güncellendiğinde yalnızca geçersiz kılın.

Başarısızlıkları nazikçe ele alın. API çağrıları başarısız olur. Hız sınırları aşılır. Sağlayıcı kesintileri yaşanabilir. Ses üretiminizi try/catch blokları içine sarın ve ses mevcut olmadığında kullanıcı deneyiminin nazik bir şekilde düşmesini sağlayın.

try {
    $audio = Audio::of($text)->generate();
    $audio->storeAs('audio', "post-{$id}.mp3");
} catch (\Throwable $e) {
    Log::warning("Audio generation failed for post {$id}", [
        'error' => $e->getMessage(),
    ]);
    // Ses olmadan devam et - gönderi hala çalışır
}

Uygun zaman aşamalarını ayarlayın. Uzun metinler daha uzun zaman alır. 2,000 kelimelik bir blog yazısını seslendirdiğinizde API’nın 15-20 saniye boyunca çalışması gerekebilir. Bu, senkron bir istek için çok uzundur. Birkaç paragraftan fazlası için kuyruklu üretim kullanın.

Harcamalarınızı izleyin. Hem OpenAI hem de ElevenLabs karakter başına ücret almaktadır. Bir web kancası veya arka plan işi hangi ses kaydını yaratıyorsa, bir hata hızlı bir şekilde şaşırtıcı bir faturaya neden olabilir. Sağlayıcı hesaplarınızda maliyet uyarıları ayarlayın ve kodunuza bir karakter sayısı koruma eki eklemeyi düşünün.

Maliyetler ve Hız Sınırları

Üretimde AI ile ilgili konuşulurken fiyatlandırma sıkça gündeme gelir. Şu an itibarıyla, OpenAI’nin TTS’si yaklaşık 15$ per milyon karakter. 2,000 kelimelik bir blog yazısı yaklaşık 10,000 karakterdir. Bu, seslendirilen gönderi için 0.15$ eder. ElevenLabs, serbest katmanında ayağınıza ilk 10,000 karakter sunmakta ve daha yüksek limitler ve premium sesler için planları 5$’dan başlamaktadır.

Transkripsiyon için OpenAI Whisper, ses başına yaklaşık 0.006$ ücret alır. 30 dakikalık bir toplantının transkripti yaklaşık 0.18$ tutmaktadır.

Bu maliyetler çoğu üretim kullanım durumu için düşüktür; ancak, üretilen sesleri saklayın veya önbelleğe alın. Aynı içeriği tekrar tekrar üretmeyin.

SSS

Bu özellikleri AI SDK’nın ajan özellikleri olmadan kullanabilir miyim?

Evet. Audio ve Transcription facade’ları tamamen bağımsızdır. Ajan oluşturmanız, araçları tanımlamanız veya konuşmalar kurmanız gerekmez. Tek yapmanız gereken composer require laravel/ai, API anahtarınızı eklemek ve Audio::of('text')->generate() ifadesini çağırmaktır.

Hangi sağlayıcılar ->toAudio() Stringable metodunu destekliyor?

->toAudio() metodu, config/ai.phpde yapılandırdığınız varsayılan sağlayıcıyı kullanır. Bunu OpenAI veya ElevenLabs olarak ayarlayabilirsiniz. Stringable kısayolu doğrudan sağlayıcı parametrelerini kabul etmez, bu yüzden yapılandırma dosyasında tercih ettiğiniz sağlayıcıyı tanımlayın.

Bu, yalnızca Laravel 12 veya sadece Laravel 13 ile mi çalışır?

AI SDK, hem Laravel 12 hem de 13 ile çalışır. ->toAudio() Stringable entegrasyonu, Audio facade’ı ve Transcription sınıfı, hangi Laravel sürümünü kullandığınızdan bağımsız olarak SDK’nın mevcut kararlı sürümünde bulunmaktadır.

İngilizce dışındaki dillerde ses üretebilir miyim?

Evet. Metninizi sağlayıcının desteklediği herhangi bir dilde geçebilirsiniz. OpenAI’nin TTS’si, girdi metnine dayalı olarak otomatik olarak birçok dili işler. ElevenLabs için, hedef diliniz için uygun bir sesi seçmeniz gerekebilir veya çok dilli modelini kullanabilirsiniz.

Girdi metni ne kadar uzun olabilir?

OpenAI’nin TTS uç noktası, talep başına 4,096 karakter kabul eder. Daha uzun içerikler (örneğin tam bir blog yazısı) için, metni parçalayarak ayrı ses dosyası oluşturmaları gerekir. Birleştirmek FFmpeg ile basittir.

Sonraki Adımlar

Metin üretimi, araç çağrıları, RAG ve şimdi ses. AI SDK, tek bir composer require ile birçok konuyu kapsar. Henüz metin özelliklerini denemediyseniz, 1. bölümü ve 2. bölümü ile başlayabilirsiniz. Zaten SDK’yı kullanıyorsanız ve Claude Opus 4.7’nin AI kurulumunuz için değişiklikleri keşfetmek istiyorsanız, bu yazı kırılma değişiklikleri ve bilmeniz gereken token ayarlamalarını kapsıyor.

Bir Laravel uygulamasına ses özellikleri ekliyorsanız ve mimari, kuyruk stratejileri veya üretim ölçeklendirme ile yardım istiyorsanız, iletişime geçin.