Nội dung mô tả
Sử dụng API chrome.tts
để phát tính năng chuyển văn bản sang lời nói tổng hợp (TTS). Xem thêm API ttsEngine
có liên quan để cho phép một tiện ích triển khai công cụ chuyển văn bản sang lời nói.
Chrome cung cấp tính năng này trên Windows (sử dụng SAPI 5), Mac OS X và ChromeOS, nhờ các tính năng tổng hợp giọng nói do hệ điều hành cung cấp. Trên mọi nền tảng, người dùng có thể cài đặt các tiện ích tự đăng ký làm công cụ chuyển văn bản sang lời nói thay thế.
Quyền
tts
Khái niệm và cách sử dụng
Tạo lời nói
Gọi cho speak()
từ tiện ích của bạn để nói. Ví dụ:
chrome.tts.speak('Hello, world.');
Để dừng nói ngay lập tức, chỉ cần gọi stop()
:
chrome.tts.stop();
Bạn có thể cung cấp các tuỳ chọn kiểm soát nhiều thuộc tính của giọng nói, chẳng hạn như tốc độ, cao độ, v.v. Ví dụ:
chrome.tts.speak('Hello, world.', {'rate': 2.0});
Bạn cũng nên chỉ định ngôn ngữ để chọn một trình tổng hợp hỗ trợ ngôn ngữ đó (và phương ngữ khu vực, nếu có).
chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});
Theo mặc định, mỗi lệnh gọi tới speak()
sẽ làm gián đoạn mọi giọng nói đang diễn ra và nói ngay lập tức. Để xác định xem một cuộc gọi có làm gián đoạn điều gì đó hay không, bạn có thể gọi isSpeaking()
. Ngoài ra, bạn có thể sử dụng tuỳ chọn enqueue
để thêm cách phát âm này vào hàng đợi những câu sẽ được đọc khi câu hiện tại kết thúc.
chrome.tts.speak('Speak this first.');
chrome.tts.speak(
'Speak this next, when the first sentence is done.', {'enqueue': true});
Bạn có thể xem nội dung mô tả đầy đủ về tất cả các lựa chọn trong tts.speak()
. Không phải công cụ chuyển văn bản nào cũng hỗ trợ mọi tuỳ chọn.
Để phát hiện lỗi và đảm bảo bạn đang gọi speak()
đúng cách, hãy truyền một hàm callback không nhận đối số. Bên trong lệnh gọi lại, hãy kiểm tra runtime.lastError
để xem có lỗi nào không.
chrome.tts.speak(
utterance,
options,
function() {
if (chrome.runtime.lastError) {
console.log('Error: ' + chrome.runtime.lastError.message);
}
}
);
Lệnh gọi lại sẽ trả về ngay lập tức, trước khi công cụ bắt đầu tạo giọng nói. Mục đích của lệnh gọi lại là để cảnh báo bạn về các lỗi cú pháp khi sử dụng API TTS, chứ không phải để phát hiện mọi lỗi có thể xảy ra trong quá trình tổng hợp và xuất giọng nói. Để phát hiện các lỗi này, bạn cần sử dụng trình nghe sự kiện, được mô tả trong phần tiếp theo.
Theo dõi sự kiện
Để biết thêm thông tin theo thời gian thực về trạng thái của giọng nói tổng hợp, hãy truyền một trình nghe sự kiện trong các tuỳ chọn đến speak()
, như sau:
chrome.tts.speak(
utterance,
{
onEvent: function(event) {
console.log('Event ' + event.type + ' at position ' + event.charIndex);
if (event.type == 'error') {
console.log('Error: ' + event.errorMessage);
}
}
},
callback
);
Mỗi sự kiện bao gồm một loại sự kiện, chỉ mục ký tự của lời nói hiện tại so với câu nói và đối với các sự kiện lỗi, sẽ có một thông báo lỗi không bắt buộc. Có các loại sự kiện sau:
'start'
: Động cơ đã bắt đầu đọc giọng nói.'word'
: Đã đạt đến ranh giới từ. Sử dụngevent.charIndex
để xác định vị trí lời nói hiện tại.'sentence'
: Đã đạt đến ranh giới của câu. Dùngevent.charIndex
để xác định vị trí lời nói hiện tại.'marker'
: Đã đạt đến một điểm đánh dấu SSML. Sử dụngevent.charIndex
để xác định vị trí lời nói hiện tại.'end'
: Động cơ đã đọc xong câu nói.'interrupted'
: Câu nói này bị gián đoạn bởi một lệnh gọi khác đếnspeak()
hoặcstop()
và không thể kết thúc.'cancelled'
: Câu nói này đã được đưa vào hàng đợi, nhưng sau đó bị huỷ bởi một lệnh gọi khác đếnspeak()
hoặcstop()
và hoàn toàn không bắt đầu nói.'error'
: Đã xảy ra lỗi riêng của công cụ nên không thể đọc cách nói này. Hãy xemevent.errorMessage
để biết thông tin chi tiết.
Bốn loại sự kiện 'end'
, 'interrupted'
, 'cancelled'
và 'error'
là chính thức. Sau khi nhận được một trong các sự kiện đó, câu nói này sẽ không còn đọc và không nhận được sự kiện mới nào từ câu nói này.
Một số giọng nói có thể không hỗ trợ tất cả các loại sự kiện và một số giọng nói có thể hoàn toàn không gửi bất kỳ sự kiện nào. Nếu bạn không muốn sử dụng giọng nói trừ phi giọng nói đó gửi một số sự kiện nhất định, hãy truyền các sự kiện bạn yêu cầu trong thành phần requiredEventTypes
của đối tượng tuỳ chọn, hoặc sử dụng getVoices()
để chọn một giọng nói đáp ứng các yêu cầu của bạn. Cả hai đều được mô tả trong phần sau đây.
mã đánh dấu SSML
Ngôn ngữ dùng trong API này có thể bao gồm mã đánh dấu bằng Ngôn ngữ đánh dấu tổng hợp lời nói (SSML). Nếu bạn sử dụng SSML, đối số đầu tiên cho speak()
phải là một tài liệu SSML hoàn chỉnh có tiêu đề XML và thẻ <speak>
cấp cao nhất, không phải là một mảnh tài liệu.
Ví dụ:
chrome.tts.speak(
'<?xml version="1.0"?>' +
'<speak>' +
' The <emphasis>second</emphasis> ' +
' word of this sentence was emphasized.' +
'</speak>'
);
Không phải công cụ chuyển văn bản nào cũng hỗ trợ tất cả các thẻ SSML, và một số công cụ có thể không hỗ trợ SSML, nhưng tất cả các công cụ đều phải bỏ qua bất kỳ SSML nào mà chúng không hỗ trợ và vẫn đọc được văn bản cơ bản.
Chọn một giọng nói
Theo mặc định, Chrome sẽ chọn giọng nói thích hợp nhất cho mỗi cách nói mà bạn muốn nói, dựa trên ngôn ngữ đó. Trên hầu hết các hệ thống Windows, Mac OS X và ChromeOS, tính năng tổng hợp giọng nói do hệ điều hành cung cấp phải có thể nói bất kỳ văn bản nào bằng ít nhất một ngôn ngữ. Tuy nhiên, một số người dùng có thể có nhiều giọng nói khác nhau, từ hệ điều hành và từ công cụ chuyển văn bản sang lời nói do các tiện ích khác của Chrome triển khai. Trong những trường hợp đó, bạn có thể triển khai mã tuỳ chỉnh để chọn giọng nói thích hợp hoặc để hiển thị cho người dùng danh sách các lựa chọn.
Để nhận danh sách tất cả giọng nói, hãy gọi getVoices()
và truyền vào đó một hàm nhận một mảng gồm các đối tượng TtsVoice
làm đối số:
chrome.tts.getVoices(
function(voices) {
for (var i = 0; i < voices.length; i++) {
console.log('Voice ' + i + ':');
console.log(' name: ' + voices[i].voiceName);
console.log(' lang: ' + voices[i].lang);
console.log(' extension id: ' + voices[i].extensionId);
console.log(' event types: ' + voices[i].eventTypes);
}
}
);
Loại
EventType
Liệt kê
"sentence"
TtsEvent
Một sự kiện từ công cụ TTS để thông báo trạng thái của một cách phát âm.
Thuộc tính
-
charIndex
số không bắt buộc
Chỉ mục của ký tự hiện tại trong câu. Đối với sự kiện từ, sự kiện sẽ kích hoạt ở cuối một từ và trước sự kiện bắt đầu từ tiếp theo.
charIndex
biểu thị một điểm trong văn bản ở đầu từ tiếp theo sẽ được đọc. -
errorMessage
chuỗi không bắt buộc
Nội dung mô tả lỗi, nếu loại sự kiện là
error
. -
chiều dài
số không bắt buộc
Chrome 74 trở lênĐộ dài của phần tiếp theo của câu nói. Ví dụ: trong sự kiện
word
, đây là độ dài của từ sẽ được nói tiếp theo. Giá trị này sẽ được đặt thành -1 nếu không được đặt bằng công cụ chuyển văn bản sang lời nói. -
loại
Loại này có thể là
start
ngay khi lời nói bắt đầu,word
khi đạt đến ranh giới từ,sentence
khi đạt đến ranh giới câu,marker
khi đạt đến một phần tử dấu SSML,end
khi đạt đến cuối câu,interrupted
khi cách phát âm bị dừng hoặc gián đoạn trước khi kết thúc,cancelled
khi bị xoá khỏi hàng đợi trước khi được tổng hợp hoặcerror
khi xảy ra bất kỳ lỗi nào khác. Khi tạm dừng lời nói, sự kiệnpause
sẽ được kích hoạt nếu một cách nói cụ thể bị tạm dừng ở giữa vàresume
nếu một cách nói tiếp tục nói. Lưu ý rằng các sự kiện tạm dừng và tiếp tục có thể không kích hoạt nếu lời nói bị tạm dừng giữa các cách phát âm.
TtsOptions
Tuỳ chọn lời nói cho công cụ TTS.
Thuộc tính
-
desiredEventTypes
string[] không bắt buộc
Các loại sự kiện TTS mà bạn muốn nghe. Nếu thiếu, tất cả các loại sự kiện có thể được gửi.
-
thêm vào hàng đợi
boolean không bắt buộc
Nếu đúng, hãy thêm cách phát này vào hàng đợi nếu chức năng TTS đang diễn ra. Nếu giá trị là false (giá trị mặc định), hãy làm gián đoạn mọi giọng nói hiện tại và xoá hàng đợi giọng nói trước khi nói giọng mới này.
-
extensionId
chuỗi không bắt buộc
Mã tiện ích của công cụ chuyển văn bản sang lời nói sẽ sử dụng (nếu biết).
-
gender
VoiceGender không bắt buộc
Không dùng nữa kể từ Chrome 77Giới tính không được dùng nữa và sẽ bị bỏ qua.
Giới tính của giọng nói cho giọng nói tổng hợp.
-
lang
chuỗi không bắt buộc
Ngôn ngữ dùng để tổng hợp, ở dạng ngôn ngữ-khu vực. Ví dụ: "en", "en-US", "en-GB", "zh-CN".
-
ném bóng
số không bắt buộc
Nói nhanh từ 0 đến 2, trong đó 0 là thấp nhất và 2 là cao nhất. 1,0 tương ứng với cao độ mặc định của một giọng nói.
-
vận tốc
số không bắt buộc
Tốc độ nói so với tốc độ mặc định cho giọng nói này. 1.0 là tốc độ mặc định, thường là khoảng 180 đến 220 từ mỗi phút. 2.0 nhanh gấp đôi và 0, 5 nhanh bằng một nửa. Chúng tôi nghiêm cấm các giá trị dưới 0,1 hoặc trên 10,0, nhưng nhiều giọng nói sẽ hạn chế tốc độ tối thiểu và tối đa hơn nữa - ví dụ: một giọng nói cụ thể không thể thực sự nói nhanh hơn 3 lần bình thường ngay cả khi bạn chỉ định một giá trị lớn hơn 3.0.
-
requiredEventTypes
string[] không bắt buộc
Các loại sự kiện TTS mà giọng nói phải hỗ trợ.
-
voiceName
chuỗi không bắt buộc
Tên của giọng nói cần sử dụng cho tổng hợp. Nếu trống, hãy dùng bất kỳ giọng nói nào có sẵn.
-
thể tích
số không bắt buộc
Âm lượng nói từ 0 đến 1, với 0 là thấp nhất và 1 là cao nhất, với mặc định là 1.0.
-
onEvent
khoảng trống không bắt buộc
Hàm này được gọi bằng các sự kiện xảy ra trong quá trình nói cách phát âm.
Hàm
onEvent
sẽ có dạng như sau:(event: TtsEvent) => {...}
-
event
Sự kiện cập nhật qua công cụ chuyển văn bản sang lời nói cho biết trạng thái của cách nói này.
-
TtsVoice
Mô tả giọng nói dùng để tổng hợp giọng nói.
Thuộc tính
-
eventTypes
EventType[] không bắt buộc
Tất cả các loại sự kiện gọi lại mà giọng nói này có thể gửi.
-
extensionId
chuỗi không bắt buộc
Mã của tiện ích cung cấp giọng nói này.
-
gender
VoiceGender không bắt buộc
Không dùng nữa kể từ Chrome 70Giới tính không được dùng nữa và sẽ bị bỏ qua.
Giới tính của giọng nói này.
-
lang
chuỗi không bắt buộc
Ngôn ngữ mà giọng nói này hỗ trợ, ở dạng ngôn ngữ – khu vực. Ví dụ: "en", "en-US", "en-GB", "zh-CN".
-
từ xa
boolean không bắt buộc
Nếu đúng, công cụ tổng hợp là một tài nguyên mạng từ xa. Đường truyền có thể có độ trễ cao hơn và có thể phát sinh chi phí băng thông.
-
voiceName
chuỗi không bắt buộc
Tên giọng nói.
VoiceGender
Giới tính không được dùng nữa và bị bỏ qua.
Liệt kê
Phương thức
getVoices()
chrome.tts.getVoices(
callback?: function,
)
Nhận được một loạt các giọng nói hiện có.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(voices: TtsVoice[]) => void
-
những giọng nói
TtsVoice[]
Mảng gồm các đối tượng
tts.TtsVoice
đại diện cho các giọng nói hiện có để tổng hợp giọng nói.
-
Giá trị trả về
-
Promise<TtsVoice[]>
Chrome 101 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
isSpeaking()
chrome.tts.isSpeaking(
callback?: function,
)
Kiểm tra xem động cơ có đang nói hay không. Trên Mac OS X, kết quả sẽ đúng bất cứ khi nào công cụ chuyển văn bản sang lời nói của hệ thống nói, ngay cả khi Chrome không khởi tạo lời nói đó.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(speaking: boolean) => void
-
đang nói
boolean
"True" nếu nói, nếu không nói là "false".
-
Giá trị trả về
-
Promise<boolean>
Chrome 101 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
pause()
chrome.tts.pause()
Tạm dừng tổng hợp giọng nói, có thể đang giữa giọng nói. Nếu bạn gọi để tiếp tục hoặc dừng cuộc gọi, thì tính năng này sẽ huỷ việc tạm dừng giọng nói.
resume()
chrome.tts.resume()
Nếu lời nói bị tạm dừng, sẽ tiếp tục nói từ nơi dừng lại.
speak()
chrome.tts.speak(
utterance: string,
options?: TtsOptions,
callback?: function,
)
Đọc văn bản bằng công cụ chuyển văn bản sang lời nói.
Tham số
-
cách phát âm
string
Văn bản cần nói, có thể là văn bản thuần tuý hoặc một tài liệu SSML hoàn chỉnh, được định dạng tốt. Các công cụ chuyển văn bản sang lời nói không hỗ trợ SSML sẽ xoá các thẻ và đọc văn bản. Độ dài tối đa của văn bản là 32.768 ký tự.
-
tùy chọn
TtsOptions không bắt buộc
Tuỳ chọn lời nói.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
Giá trị trả về
-
Promise<void>
Chrome 101 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
stop()
chrome.tts.stop()
Dừng mọi giọng nói hiện tại và xoá hàng đợi của mọi giọng nói đang chờ xử lý. Ngoài ra, nếu giọng nói đã bị tạm dừng thì giờ đây lời nói sẽ được hủy tạm dừng cho cuộc gọi tiếp theo để nói.
Sự kiện
onVoicesChanged
chrome.tts.onVoicesChanged.addListener(
callback: function,
)
Được gọi khi danh sách tts.TtsVoice
mà getVoices trả về đã thay đổi.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:() => void