Laravel TTS Client

Client Laravel cho laravel-tts-api, dịch vụ chuyển văn bản thành giọng nói chạy Piper.

• Token tạm được ký ngay trong app bằng client secret, không phải gọi lên server để xin token. Token được dùng lại cho tới khi gần hết hạn.
• Tts::synthesize() trả về một file WAV hoàn chỉnh. Tts::stream() trả audio theo từng câu, có thể chuyển tiếp thẳng xuống trình duyệt.
• Tts::url() / Tts::token() cấp URL hoặc token cho frontend tự gọi server, để audio không phải đi qua app.
• Hỗ trợ Laravel 11–13, PHP 8.2+.

Cài đặt

composer require vuthaihoc/laravel-tts-client
php artisan vendor:publish --tag=tts-config   # không bắt buộc

.env:

TTS_BASE_URL=https://tts.example.com
TTS_CLIENT_ID=acme.k3f9
TTS_CLIENT_SECRET=...        # do admin server cấp bằng `php artisan tts:client acme`
# TTS_VOICE=vi_VN-csa-voice-piper-v3-medium   # voice mặc định, bỏ trống thì server tự chọn
# TTS_TOKEN_TTL=300          # không được vượt giới hạn của server (mặc định 300)
# TTS_TIMEOUT=120

TTS_CLIENT_SECRET chỉ nằm ở backend: ai có nó đều ký được token. Trình duyệt chỉ nhận token đã ký sẵn hoặc URL có gắn token.

Sử dụng

use Vuthaihoc\TtsClient\Facades\Tts;

// Danh sách voice và speaker (cache 5 phút)
$voices = Tts::voices();

// Một file WAV
$audio = Tts::synthesize('Xin chào!', voice: 'vi_VN-csa-voice-piper-v3-medium', speaker: 'yen_nhi');
$audio->content;     // bytes WAV
$audio->duration;    // giây
$audio->save('tts/hello.wav', 's3');

// Trả thẳng từ controller
Route::get('/hello.wav', fn () => Tts::synthesize('Xin chào!'));

Tuỳ chỉnh âm thanh

synthesize(), stream() và url() nhận thêm các named argument sau. Để null (mặc định) thì lấy giá trị trong config; config cũng không đặt thì server dùng mặc định của nó:

Tts::synthesize('Xin chào!', volume: 0.8, sentenceSilence: 0.4);
Tts::stream($text, format: 'pcm', noiseScale: 0.5, noiseW: 0.6);

Đặt mặc định cho cả app trong .env: TTS_NORMALIZE, TTS_VOLUME, TTS_SENTENCE_SILENCE, TTS_NOISE_SCALE, TTS_NOISE_W.

IPA

Phần nằm giữa [[ ... ]] được đọc đúng theo âm vị IPA, dùng để sửa cách đọc tên riêng, từ viết tắt, hoặc chọn cách đọc Anh-Anh hay Anh-Mỹ cho một từ:

Tts::synthesize('I like [[təmˈɑːtəʊ]] sauce.', voice: 'en_US-amy-medium');
Tts::synthesize('Chào mừng quý khách đến [[tˈe-2ɲ fˈoɜ]] Hồ Chí Minh.');

Ký hiệu phải theo đúng quy ước của espeak-ng cho voice đó. Lấy IPA mẫu trên server bằng php artisan piper:ipa "thành phố" --voice=.... Cần server có libpiper build từ scripts/build-libpiper.sh (image Docker đã có sẵn), xem docs/api.md của server.

Lấy phiên âm (IPA)

Tts::ipa() gọi /api/tts/ipa: đưa vào một từ, một câu hoặc nhiều câu, nhận lại IPA theo từng câu.

$ipa = Tts::ipa('either', 'en-GB');
$ipa->cambridge();                                // "/ˈaɪ.ðə/"
array_column($ipa->alternatives(), 'cambridge');  // ["/ˈaɪ.ðə/", "/ˈiː.ðə/"] (chỉ có với từ lẻ)
$ipa->ipa();                                      // "ˈaɪðɐ", dán được vào [[ ]]

$ipa = Tts::ipa('The vegetable recipe.', 'en-US', engine: 'dictionary');
$ipa->cambridge();                                // "/ðə ˈvedʒ.tə.bəl ˈres.ə.pi/"
$ipa->words();                                    // từng từ: nguồn (cmudict/britfone/espeak) và mọi cách đọc
$ipa->sentences;                                  // dữ liệu gốc theo từng câu

• language: en-GB, en-US hoặc vi-VN. Để trống thì lấy TTS_IPA_LANGUAGE (mặc định en-US).
• engine: 'espeak' (mặc định) cho IPA đúng như voice sẽ đọc. engine: 'dictionary' tra từng từ trong CMUdict (Anh-Mỹ) hoặc Britfone (Anh-Anh), từ nào không có thì dùng espeak; chỉ dùng được với tiếng Anh, vi-VN sẽ ném TtsValidationException.
• Bản ghi kiểu Cambridge (cambridge()) là null với tiếng Việt.

Stream

// Chuyển tiếp xuống trình duyệt theo từng câu
Route::get('/speak', fn (Request $r) => Tts::stream($r->input('text'), voice: 'en_US-amy-medium'));

// Tự đọc từng chunk
foreach (Tts::stream($text, format: 'pcm') as $chunk) {
    // s16le mono, Tts::stream(...)->sampleRate Hz
}

// NDJSON: mỗi câu một mảng ['i', 'sample_rate', 'duration', 'last', 'pcm' => base64]
foreach (Tts::stream($text, format: 'ndjson')->sentences() as $sentence) {
    // ...
}

Lỗi (voice sai, token bị từ chối, ...) được ném ra ngay khi gọi stream(), trước khi gửi byte audio nào xuống trình duyệt. Việc chuyển tiếp dùng echo + flush, nên stream được trên PHP-FPM và Octane/Swoole. Riêng Octane/RoadRunner sẽ gom hết rồi mới gửi.

Để frontend gọi server trực tiếp

{{-- URL dùng được trong token_ttl giây (mặc định 5 phút) --}}
<audio controls src="{{ Tts::url('Xin chào các bạn.', speaker: 'quang_huy') }}"></audio>

// Hoặc trả token cho JavaScript, để JS tự gọi fetch(`${base}/api/tts/stream`, { headers: { Authorization: `Bearer ${token}` } })
return ['token' => Tts::token(), 'expires_at' => Tts::tokenExpiresAt()];

Xử lý lỗi

Mọi lỗi đều kế thừa Vuthaihoc\TtsClient\Exceptions\TtsException (getCode() là HTTP status, ->response là response gốc):

Test

composer test                                  # unit test, dùng Http::fake
TTS_LIVE_BASE_URL=http://127.0.0.1:8088 TTS_LIVE_CLIENT_ID=... TTS_LIVE_CLIENT_SECRET=... \
  vendor/bin/phpunit --testsuite Live          # chạy với server thật

Trong app của bạn, chỉ cần Http::fake(['*/api/tts*' => Http::response('RIFF...')]) là gọi được Tts mà không cần server.

License

MIT