Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite le prompt suivant :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-speech-synthesis` plugin in my project.

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

bun add @capgo/capacitor-speech-synthesis
bunx cap sync

Importer

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

Démarrage rapide

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.speak({
  text: 'Gate B12 is boarding.',
  language: 'en-US',
  rate: 1.0,
});

Exemple : exporter l'audio sur le natif

const { uri } = await SpeechSynthesis.synthesizeToFile({
  text: lessonScript,
  language: 'es-ES',
});

Erreurs courantes

• Initialisation iOS: appelez initialize() tôt sur iOS pour réduire la latence de la première lecture.
• Session audio: utiliser activateAudioSession() when speech must duck or mix with other audio.
• Voix Web: voice lists differ per browser, always fall back to default voice.

Aperçu de API

speak

Lit le texte fourni avec les options spécifiées. L'énoncé est ajouté à la file d'attente de synthèse vocale.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const result = await SpeechSynthesis.speak({
  text: 'Hello, world!',
  language: 'en-US',
  rate: 1.0,
  pitch: 1.0,
  volume: 1.0,
  queueStrategy: 'Add'
});
console.log('Utterance ID:', result.utteranceId);

synthesizeToFile

Synthétise la parole dans un fichier audio (Android/iOS uniquement). Retourne le chemin du fichier où l'audio a été sauvegardé.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const result = await SpeechSynthesis.synthesizeToFile({
  text: 'Hello, world!',
  language: 'en-US'
});
console.log('Audio file saved at:', result.filePath);

cancel

Annule toutes les expressions en file d'attente et arrête la parole en cours.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.cancel();

pause

Met la parole en pause immédiatement.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.pause();

resume

Reprend la parole mise en pause.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.resume();

isSpeaking

Vérifie si la synthèse vocale est en train de parler.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { isSpeaking } = await SpeechSynthesis.isSpeaking();
console.log('Is speaking:', isSpeaking);

isAvailable

Vérifie si la synthèse vocale est disponible sur l'appareil.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { isAvailable } = await SpeechSynthesis.isAvailable();
if (isAvailable) {
  console.log('Speech synthesis is available');
}

getVoices

Récupère toutes les voix disponibles.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { voices } = await SpeechSynthesis.getVoices();
voices.forEach(voice => {
  console.log(`${voice.name} (${voice.language})`);
});

getLanguages

Récupère toutes les langues disponibles.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { languages } = await SpeechSynthesis.getLanguages();
console.log('Available languages:', languages);

isLanguageAvailable

Vérifie si une langue spécifique est disponible.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { isAvailable } = await SpeechSynthesis.isLanguageAvailable({
  language: 'es-ES'
});
console.log('Spanish available:', isAvailable);

isVoiceAvailable

Vérifie si une voix spécifique est disponible.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

const { isAvailable } = await SpeechSynthesis.isVoiceAvailable({
  voiceId: 'com.apple.ttsbundle.Samantha-compact'
});
console.log('Voice available:', isAvailable);

initialize

Initialise le moteur de synthèse vocale (optimisation iOS). Cela peut réduire la latence lors de la première requête vocale.

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.initialize();

activateAudioSession

Active la session audio avec une catégorie spécifique (iOS uniquement).

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.activateAudioSession({
  category: 'Playback'
});

deactivateAudioSession

Désactive la session audio (iOS uniquement).

import { SpeechSynthesis } from '@capgo/capacitor-speech-synthesis';

await SpeechSynthesis.deactivateAudioSession();

Référence de type

SpeakOptions

Options pour la synthèse vocale.

export interface SpeakOptions {
  /**
   * The text to speak.
   *
   * @since 1.0.0
   */
  text: string;

  /**
   * The BCP-47 language tag (e.g., 'en-US', 'es-ES').
   *
   * @since 1.0.0
   */
  language?: string;

  /**
   * The voice identifier to use.
   *
   * @since 1.0.0
   */
  voiceId?: string;

  /**
   * The pitch of the voice (0.5 to 2.0, default: 1.0).
   *
   * @since 1.0.0
   */
  pitch?: number;

  /**
   * The speaking rate (0.1 to 10.0, default: 1.0).
   *
   * @since 1.0.0
   */
  rate?: number;

  /**
   * The volume (0.0 to 1.0, default: 1.0).
   *
   * @since 1.0.0
   */
  volume?: number;

  /**
   * The queue strategy: 'Add' to append or 'Flush' to replace queue.
   * Default: 'Add'
   *
   * @since 1.0.0
   */
  queueStrategy?: 'Add' | 'Flush';
}

SpeakResult

Résultat de la synthèse vocale.

export interface SpeakResult {
  /**
   * Unique identifier for this utterance.
   *
   * @since 1.0.0
   */
  utteranceId: string;
}

SynthesizeToFileResult

Résultat de la synthèse vers un fichier.

export interface SynthesizeToFileResult {
  /**
   * The file path where audio was saved.
   *
   * @since 1.0.0
   */
  filePath: string;

  /**
   * Unique identifier for this utterance.
   *
   * @since 1.0.0
   */
  utteranceId: string;
}

VoiceInfo

Informations sur une voix.

export interface VoiceInfo {
  /**
   * Unique voice identifier.
   *
   * @since 1.0.0
   */
  id: string;

  /**
   * Display name of the voice.
   *
   * @since 1.0.0
   */
  name: string;

  /**
   * BCP-47 language code.
   *
   * @since 1.0.0
   */
  language: string;

  /**
   * Gender of the voice (iOS only).
   *
   * @since 1.0.0
   */
  gender?: 'male' | 'female' | 'neutral';

  /**
   * Whether this voice requires a network connection.
   *
   * @since 1.0.0
   */
  isNetworkConnectionRequired?: boolean;

  /**
   * Whether this is the default voice (Web only).
   *
   * @since 1.0.0
   */
  default?: boolean;
}

IsLanguageAvailableOptions

Options pour vérifier la disponibilité d'une langue.

export interface IsLanguageAvailableOptions {
  /**
   * The BCP-47 language code to check.
   *
   * @since 1.0.0
   */
  language: string;
}

IsVoiceAvailableOptions

Options pour vérifier la disponibilité d'une voix.

export interface IsVoiceAvailableOptions {
  /**
   * The voice ID to check.
   *
   * @since 1.0.0
   */
  voiceId: string;
}

ActivateAudioSessionOptions

Options pour activer la session audio (iOS uniquement).

export interface ActivateAudioSessionOptions {
  /**
   * The audio session category.
   * - 'Ambient': Mixes with other audio
   * - 'Playback': Stops other audio
   *
   * @since 1.0.0
   */
  category: 'Ambient' | 'Playback';
}

UtteranceEvent

Événement émis au début ou à la fin de l'énoncé.

export interface UtteranceEvent {
  /**
   * The utterance identifier.
   *
   * @since 1.0.0
   */
  utteranceId: string;
}

BoundaryEvent

Événement émis lors des changements de mots.

export interface BoundaryEvent {
  /**
   * The utterance identifier.
   *
   * @since 1.0.0
   */
  utteranceId: string;

  /**
   * The character index in the text.
   *
   * @since 1.0.0
   */
  charIndex: number;

  /**
   * The character length of the current word.
   *
   * @since 1.0.0
   */
  charLength?: number;
}

ErrorEvent

Événement émis en cas d'erreur de synthèse.

export interface ErrorEvent {
  /**
   * The utterance identifier.
   *
   * @since 1.0.0
   */
  utteranceId: string;

  /**
   * The error message.
   *
   * @since 1.0.0
   */
  error: string;
}

Source de vérité

Cette page est générée à partir de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier les opérations du dashboard et de API, connectez-l’avec Utiliser @capgo/capacitor-speech-synthesis pour la capacité native dans l'utilisation de @capgo/capacitor-speech-synthesis, Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans « Clés API », et Appareils pour les détails d'implémentation dans Devices.