chrome.tts

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ụng event.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ùng event.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ụng event.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 đến speak() hoặc stop() 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 đến speak() hoặc stop() 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 xem event.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

Chrome 54 trở lên

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

    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 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ặc error khi xảy ra bất kỳ lỗi nào khác. Khi tạm dừng lời nói, sự kiện pause 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

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 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 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.

  • 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

      TtsEvent

      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 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.

  • 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

Chrome 54 trở lên Ngừng sử dụng kể từ Chrome 70

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

Liệt kê

Phương thức

getVoices()

Cam kết 
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ê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 để 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()

Cam kết 
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ê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 để 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()

Cam kết 
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ê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 để 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 124 trở lên 
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