Trang này được dịch bởi Cloud Translation API.

chrome.tts

Mô tả

Dùng API chrome.tts để phát tính năng chuyển văn bản sang lời nói (TTS) được tổng hợp. Ngoài ra, hãy xem API ttsEngine có liên quan, giúp cho phép tiện ích triển khai công cụ chuyển lời nói.

Chrome cung cấp khả năng này trên Windows (sử dụng SAPI 5), Mac OS X và ChromeOS, sử dụng khả năng tổng hợp giọng nói do hệ điều hành cung cấp. Trên tất cả các 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 lời nói thay thế.

Quyền

tts

Khái niệm và cách sử dụng

Tạo giọng nói

Hãy gọi cho speak() từ số máy lẻ của bạn để nói. Ví dụ:

chrome.tts.speak('Hello, world.');

Để dừng nói ngay lập tức, bạn 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 các thuộc tính khác nhau của lời nói, chẳng hạn như tốc độ, cao độ và khác. Ví dụ:

chrome.tts.speak('Hello, world.', {'rate': 2.0});

Bạn cũng nên chỉ định ngôn ngữ để bộ tổng hợp hỗ trợ ngôn ngữ đó (và phương ngữ địa phương, nếu có) được chọn.

chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});

Theo mặc định, mỗi lệnh gọi đến speak() sẽ làm gián đoạn mọi lời nói đang diễn ra và được nói ngay lập tức. Người nhận xác định xem một cuộc gọi có làm gián đoạn điều gì 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 một hàng đợi những cách phát âm mà được nói khi cách phát âm 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 tất cả lời nói sẽ hỗ trợ tất cả các 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ó bất kỳ mã nào .

chrome.tts.speak(
  utterance,
  options,
  function() {
    if (chrome.runtime.lastError) {
      console.log('Error: ' + chrome.runtime.lastError.message);
    }
  }
);

Lệnh gọi lại 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 dùng để cảnh báo bạn về các lỗi cú pháp khi sử dụng TTS API, chứ không phải để nắm bắt tất cả những lỗi có thể xảy ra 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 những lỗi này bạn cũng cần dùng trình nghe sự kiện, như mô tả trong phần tiếp theo.

Nghe các sự kiện

Để nhận 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 chuyển một trình nghe sự kiện vào các tuỳ chọn cho speak(), chẳng hạn như:

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 bài nói hiện tại tương ứng với cách phát âm và đối với các sự kiện lỗi, đây sẽ là thông báo lỗi không bắt buộc. Sau đây là các loại sự kiện:

'start': Công cụ đã bắt đầu đọc cách phát âm.
'word': Đã đạt đến giới hạn từ. Sử dụng event.charIndex để xác định lời nói hiện tại vị trí.
'sentence': Đã đạt đến giới hạn của câu. Sử dụng event.charIndex để xác định thời điểm hiện tại vị trí lời nói.
'marker': Đã đạt đến một điểm đánh dấu SSML. Sử dụng event.charIndex để xác định lời nói hiện tại vị trí.
'end': Công cụ đã đọc xong cách phát âm.
'interrupted': Câu nói này đã bị một lệnh gọi khác đến speak() hoặc stop() làm gián đoạn và có chưa hoàn tất.
'cancelled': Câu nói này đã được đưa vào hàng đợi nhưng sau đó bị một lệnh gọi khác đến speak() hoặc huỷ stop() và chưa từng bắt đầu nói.
'error': Đã xảy ra lỗi cụ thể đối với công cụ và không thể đọc lời nói này. Séc event.errorMessage để biết thông tin chi tiết.

4 trong số các loại sự kiện – 'end', 'interrupted', 'cancelled' và 'error' – là chính thức. Sau một trong các sự kiện đó đã được nhận, câu nói này sẽ không còn có hiệu lực và không có sự kiện mới từ sẽ được nhận dạng.

Một số giọng nói có thể không hỗ trợ hết mọi loại sự kiện và một số giọng nói có thể không gửi được sự kiện nào. Nếu bạn không muốn sử dụng một giọng nói trừ phi giọng nói đó gửi một số sự kiện nhất định, hãy chuyển các sự kiện bạn yêu cầu vào requiredEventTypes thành viên của đối tượng tuỳ chọn hoặc sử dụng getVoices() để chọn một giọng nói phù hợp các yêu cầu của bạn. Cả hai đều được mô tả trong phần bên dưới.

mã đánh dấu SSML

Ngôn ngữ được dùng trong API này có thể bao gồm việc đá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 với 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 sang lời nói 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ụ đó phải bỏ qua mọi SSML mà chúng không hỗ trợ và vẫn đọ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 phù hợp nhất với từng cách nói mà bạn muốn dùng, dựa trên ngôn ngữ. Trên hầu hết hệ thống Windows, Mac OS X và ChromeOS, tính năng tổng hợp giọng nói được cung cấp bằng hệ điều hành phải có thể đọc bất kỳ văn bản nào bằng ít nhất một ngôn ngữ. Một số người dùng có thể gặp phải có nhiều giọng nói khác nhau, mặc dù từ hệ điều hành và từ các công cụ chuyển lời nói được triển khai bởi các tiện ích khác của Chrome. Trong những trường hợp đó, bạn có thể triển khai mã tuỳ chỉnh để chọn hoặc để hiển thị cho người dùng danh sách các lựa chọn.

Để lấy danh sách tất cả cá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 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

Chrome 54 trở lên

Enum

"start"

"kết thúc"

"word"

"sentence"

"điểm đánh dấu"

"bị gián đoạn"

"đã huỷ"

"error"

"tạm dừng"

"tiếp tục"

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ách phát âm. Đối với các sự kiện từ, sự kiện sẽ kích hoạt ở cuối một từ và trước phần đầu của một từ tiếp theo. charIndex đại diện cho 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ách phát âm. Ví dụ: trong một 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 công cụ chuyển lời nói không đặt giá trị này.
loại

EventType

Loại này có thể là start ngay khi lời nói bắt đầu, word khi đạt đến ranh giới của từ, sentence khi đạt đến ranh giới của câu, marker khi đạt đến phần tử dấu SSML, end khi đạt đến cuối câu, interrupted khi phát âm bị dừng hoặc bị 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ặc error khi xảy ra lỗi nào khác. Khi tạm dừng giọng nói, sự kiện pause sẽ được kích hoạt nếu một cách phát âm cụ thể bị tạm dừng ở giữa và resume nếu một cách nói tiếp tục lời 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 nói.

TtsOptions

Chrome 77 trở lên

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 đều 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âu này vào hàng đợi nếu TTS đang diễn ra. Nếu false (mặc định), sẽ 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 cách phát âm mới này.
extensionId

chuỗi không bắt buộc

Mã tiện ích của công cụ chuyển 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 77

Giớ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.
ngôn ngữ

chuỗi không bắt buộc

Ngôn ngữ dùng để tổng hợp, dưới dạng language-region. Ví dụ: "en", "en-US", "en-GB", "zh-CN".
đề cử

số không bắt buộc

Cao độ nói nằm trong khoảng từ 0 đến 2, với 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 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 của giọng nói này. 1.0 là tốc độ mặc định, thường vào 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. Không được phép sử dụng các giá trị dưới 0,1 hoặc trên 10, 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ể có thể không 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 giọng nói để sử dụng cho quá trình tổng hợp. Nếu trống, hãy sử 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 trong khoảng từ 0 đến 1, với 0 là thấp nhất và 1 là cao nhất, với giá trị mặc định là 1.0.
onEvent

khoảng trống không bắt buộc

Hàm này được gọi với các sự kiện xảy ra trong quá trình đọc cách phát âm.

Hàm onEvent có dạng như sau:
```
(event: TtsEvent) => {...}
```
- event
  
  TtsEvent
  
  Sự kiện cập nhật từ công cụ chuyển văn bản sang lời nói cho biết trạng thái của câu nói này.

TtsVoice

Nội dung mô tả của 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 70

Giớ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.
ngôn ngữ

chuỗi không bắt buộc

Ngôn ngữ mà giọng nói này hỗ trợ, dưới 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. Việc này 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

Chrome 54 trở lên Không dùng nữa kể từ Chrome 70

Giới tính không được dùng nữa và bị bỏ qua.

Enum

"male"

"female"

Phương thức

getVoices()

Lời hứa

chrome.tts.getVoices(
  callback?: function,
)

Lấy một loạt tất 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 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ên

Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

isSpeaking()

Lời hứa

chrome.tts.isSpeaking(
  callback?: function,
)

Kiểm tra xem công cụ có đang nói gì không. Trên Mac OS X, kết quả là true bất cứ khi nào công cụ lời nói của hệ thống đang nói, ngay cả khi Chrome không khởi động giọng 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 không nói, nếu không thì sai.

Giá trị trả về

Promise<boolean>

Chrome 101 trở lên

Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng 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ể xảy ra ở giữa một cách phát âm. Cuộc gọi để tiếp tục hoặc dừng cuộc gọi sẽ huỷ việc tạm dừng giọng nói.

resume()

chrome.tts.resume()

Nếu giọng nói bị tạm dừng, hãy tiếp tục nói từ nơi bạn dừng nói.

speak()

Lời hứa

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 tài liệu SSML hoàn chỉnh, có định dạng phù hợp. Các công cụ chuyển lời nói không hỗ trợ SSML sẽ xoá các thẻ này và đọc văn bản. Văn bản này có độ dài tối đa là 32.768 ký tự.
tùy chọ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ề

Lời hứa<vô hiệu>

Chrome 101 trở lên

Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng 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 phát âm đang chờ xử lý. Ngoài ra, nếu giọng nói đã bị tạm dừng thì giờ đây, giọng nói đó cũng sẽ được huỷ tạm dừng cho cuộc gọi tiếp theo.

Sự kiện

onVoicesChanged

Chrome 124 trở lên

chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

Được gọi khi danh sách tts.TtsVoice mà getVoices sẽ trả về thay đổi.

Tham số

số gọi lại

hàm

Tham số callback sẽ có dạng như sau:
```
() => void
```