Azure AI Speech Transcription client library for JavaScript - versione 1.0.0-beta.1

La libreria client Azure AI Speech Transcription offre un facile accesso al servizio di trascrizione vocale su testo di Azure, permettendoti di convertire audio in testo con grande precisione.

Usare la libreria client per:

Trascrive file audio in testo
Supporta più lingue e località
Abilita la diarizzazione dei parlanti per identificare diversi parlanti
Applica il filtro delle parolacce
Usa modelli di voce personalizzati
Elabora sia file locali che URL remote
Usa la Modalità Avanzata per la trascrizione e la traduzione basate su LLM

Collegamenti chiave:

Come iniziare

Ambienti attualmente supportati

Versioni LTS di Node.js
Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

Una sottoscrizione di Azure.
Una risorsa Azure AI Speech o una risorsa Azure AI Foundry.

Installare il pacchetto `@azure/ai-speech-transcription`

Installa la libreria client Azure AI Speech Transcription per JavaScript con npm:

npm install @azure/ai-speech-transcription

Creare ed autenticare un `TranscriptionClient`

Per creare un oggetto client per accedere all'API di trascrizione di Azure, avrai bisogno della endpoint tua risorsa di trascrizione Azure e di un credentialfile di . Puoi trovare l'endpoint per la tua risorsa Azure Transcription nel Azure Portal.

Opzione 1: Autenticazione con chiave API

Puoi trovare la chiave API della tua risorsa vocale nel Portale Azure.

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));

Opzione 2: Autenticazione Entra ID (Consigliata per la produzione)

Per scenari di produzione, si consiglia di utilizzare l'autenticazione Entra ID con identità gestite o principi di servizio. Installare il pacchetto @azure/identity:

npm install @azure/identity

Dovrai inoltre assegnare il ruolo appropriato (ad esempio, "Utente dei Servizi Cognitivi") alla tua identità gestita o al principale del servizio. Per maggiori informazioni, consulta l'autenticazione Azure AI Services.

Usando Node.js e ambienti simili a Node, è possibile usare la classe DefaultAzureCredential per autenticare il client.

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { DefaultAzureCredential } from "@azure/identity";

const client = new TranscriptionClient("<endpoint>", new DefaultAzureCredential());

Per gli ambienti del browser, usare il InteractiveBrowserCredential dal pacchetto di @azure/identity per l'autenticazione.

import { InteractiveBrowserCredential } from "@azure/identity";
import { TranscriptionClient } from "@azure/ai-speech-transcription";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const client = new TranscriptionClient("<endpoint>", credential);

Versioni dell'API del servizio

La libreria client mira di default all'ultima versione dell'API di servizio. Puoi selezionare una versione API supportata specifica quando si istanzia il client:

import { TranscriptionClient, KnownServiceApiVersions } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"), {
  serviceVersion: KnownServiceApiVersions.V20251015,
});

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

Concetti chiave

Client di trascrizione

TranscriptionClient è l'interfaccia principale per gli sviluppatori che utilizzano la libreria client Azure AI Speech Transcription. Fornisce due metodi sovraccarichi transcribe — uno per i dati binari audio e uno per gli URL audio.

Formati audio

Il servizio supporta vari formati audio tra cui WAV, MP3, OGG, FLAC e altri. L'audio deve essere:

Durata meno di 2 ore
Dimensioni inferiori a 250 MB

Opzioni di trascrizione

Puoi personalizzare la trascrizione con opzioni come:

Filtraggio delle parolacce: Controlla come viene gestita la volgarità nelle trascrizioni ("None", "Masked", "Removed", "Tags")
Diarizzazione degli altoparlanti: Identificare diversi altoparlanti nell'audio multi-altoparlante (fino a 36 altoparlanti)
Liste di frasi: Fornire frasi specifiche per il dominio per migliorare l'accuratezza
Rilevamento della lingua: rilevare automaticamente la lingua parlata, oppure specificare le località note
Modalità migliorata: Migliora la qualità della trascrizione con elaborazione, traduzione e personalizzazione basata su prompt tramite LLM

Examples

Trascrivi un file audio locale
Trascrivi l'audio da un URL
Accedi a singole parole trascritte
Identificare i parlanti con diarizzazione
Filtra le parolacce
Migliora l'accuratezza con frasi personalizzate
Trascrivere con una lingua nota
Usa la Modalità Migliorata per la massima precisione
Traduzione con modalità avanzata
Combina più opzioni

Trascrivi un file audio locale

L'operazione più basilare consiste nel trascrivere un file audio dal file system locale:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile);
console.log(`Duration: ${result.durationInMs}ms`);
console.log("Transcription:", result.combinedPhrases[0]?.text);

Trascrivi l'audio da un URL

Puoi trascrivere l'audio direttamente da un URL accessibile pubblicamente senza prima scaricare il file:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const result = await client.transcribe("https://example.com/audio/sample.wav", {
  locales: ["en-US"],
});
console.log("Transcription:", result.combinedPhrases[0]?.text);

Accedi a singole parole trascritte

Per accedere ai dettagli a livello di parola, inclusi timestamp, punteggi di fiducia e singole parole:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile);
for (const phrase of result.phrases) {
  console.log(`Phrase: ${phrase.text}`);
  console.log(
    `  Offset: ${phrase.offsetMilliseconds}ms | Duration: ${phrase.durationMilliseconds}ms`,
  );
  console.log(`  Confidence: ${phrase.confidence.toFixed(2)}`);
  // Access individual words in the phrase
  for (const word of phrase.words ?? []) {
    console.log(`    Word: '${word.text}' | Offset: ${word.offsetMilliseconds}ms`);
  }
}

Identificare i parlanti con diarizzazione

La diarizzazione del parlante identifica chi ha parlato e quando nelle conversazioni con più altoparlanti:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/conversation.wav");
const result = await client.transcribe(audioFile, {
  diarizationOptions: {
    maxSpeakers: 4, // Expect up to 4 speakers in the conversation
  },
});
for (const phrase of result.phrases) {
  console.log(`Speaker ${phrase.speaker}: ${phrase.text}`);
}

Nota: Il numero totale di parlanti identificati non supererà maxSpeakersmai . Se l'audio effettivo contiene più altoparlanti di quelli specificati, il servizio li consoliderà. Stabilisci un limite superiore ragionevole se non sei sicuro del conteggio esatto.

Filtra le parolacce

Controlla come appaiono le parolacce nelle tue trascrizioni usando diverse modalità di filtro:

import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  profanityFilterMode: KnownProfanityFilterModes.Masked, // Default - profanity replaced with asterisks
});
console.log("Transcription:", result.combinedPhrases[0]?.text);

Modalità disponibili:

"None": Nessun filtraggio — le parolacce appaiono come dette
"Masked": Le parolacce sostituite da asterischi (ad esempio, f***)
"Removed": Parolacce completamente rimosse dal testo
"Tags": Parolacce avvolte in tag XML (ad esempio, <profanity>word</profanity>)

Migliora l'accuratezza con frasi personalizzate

Aggiungi frasi personalizzate per aiutare il servizio a riconoscere correttamente termini, nomi e acronimi specifici di dominio:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  phraseList: {
    phrases: ["Contoso", "Jessie", "Rehaan"],
  },
});
console.log("Transcription:", result.combinedPhrases[0]?.text);

Trascrivere con una lingua nota

Quando conosci la lingua dell'audio, specificare una singola località migliora l'accuratezza e riduce la latenza:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/english-audio.mp3");
const result = await client.transcribe(audioFile, {
  locales: ["en-US"],
});
console.log("Transcription:", result.combinedPhrases[0]?.text);

Per l'identificazione della lingua, quando non sei sicuro della lingua, specifica più località candidate e il servizio rileverà automaticamente la lingua:

import { TranscriptionClient } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.mp3");
const result = await client.transcribe(audioFile, {
  locales: ["en-US", "es-ES"],
});
for (const phrase of result.phrases) {
  console.log(`[${phrase.locale}] ${phrase.text}`);
}

Usa la Modalità Migliorata per la massima precisione

Enhanced Mode utilizza l'elaborazione basata su LLM per la trascrizione con la massima accuratezza:

import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/audio.wav");
const result = await client.transcribe(audioFile, {
  // Enhanced mode: LLM-powered speech recognition with prompt customization
  enhancedMode: {
    task: "transcribe",
    prompt: ["Output must be in lexical format."],
  },
  // Existing Fast Transcription options work alongside enhanced mode
  diarizationOptions: {
    maxSpeakers: 2,
  },
  profanityFilterMode: KnownProfanityFilterModes.Masked,
  activeChannels: [0, 1],
});
for (const phrase of result.phrases) {
  console.log(`[Speaker ${phrase.speaker}] ${phrase.text}`);
}

Traduzione con modalità avanzata

La Modalità Migliorata supporta anche la traduzione del discorso in una lingua di destinazione:

import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/chinese-audio.wav");
const result = await client.transcribe(audioFile, {
  enhancedMode: {
    task: "translate",
    targetLanguage: "ko", // Translate to Korean
  },
  profanityFilterMode: KnownProfanityFilterModes.Masked,
});
console.log("Translated to Korean:", result.combinedPhrases[0]?.text);

Combina più opzioni

Puoi combinare più funzionalità di trascrizione per scenari complessi:

import { TranscriptionClient, KnownProfanityFilterModes } from "@azure/ai-speech-transcription";
import { AzureKeyCredential } from "@azure/core-auth";
import { readFileSync } from "node:fs";

const client = new TranscriptionClient("<endpoint>", new AzureKeyCredential("<api-key>"));
const audioFile = readFileSync("path/to/meeting.wav");
const result = await client.transcribe(audioFile, {
  // Enable speaker diarization
  diarizationOptions: {
    maxSpeakers: 5,
  },
  // Mask profanity
  profanityFilterMode: KnownProfanityFilterModes.Masked,
  // Add custom phrases
  phraseList: {
    phrases: ["action items", "Q4", "KPIs"],
  },
});
console.log("Full Transcript:");
console.log(result.combinedPhrases[0]?.text);
for (const phrase of result.phrases) {
  console.log(`Speaker ${phrase.speaker}: ${phrase.text}`);
}

Risoluzione dei problemi

Problemi comuni

Fallimenti nell'autenticazione: verifica che la tua chiave API o le credenziali dell'ID Entra siano corrette e che la tua risorsa vocale sia attiva.
Formato audio non supportato: Assicurati che il tuo audio sia in un formato supportato (WAV, MP3, OGG, FLAC, ecc.). Il servizio gestisce automaticamente il rilevamento dei formati.
Trascrizione lenta: Per file grandi, assicurati che la connessione di rete sia stabile.
Scarsa accuratezza: prova a specificare la posizione corretta, aggiungere frasi personalizzate per termini specifici di dominio o usare la Modalità Migliorata.

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la AZURE_LOG_LEVEL variabile di ambiente su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Passaggi successivi

Esplora altri esempi per saperne di più sulle funzionalità avanzate:

Trascrizione di base - Creare clienti e trascrizione di base
Opzioni di trascrizione - Combinare più funzionalità di trascrizione
Trascrizione da URL - Trascrizione da URL remoti
Enhanced Mode - Trascrizione e traduzione basate su LLM
Filtro delle parolacce - Tutte le modalità di filtraggio delle parolacce
Diarizzazione del parlante - Identificazione del parlante
Lista di Frasi - Vocabolario personalizzato
Trascrizione con località - Specifica e rilevamento del linguaggio
Trascrizione multilingue - Contenuti multilingue (anteprima)

Contributing

Per contribuire a questa libreria, leggere la guida per i contributi per altre informazioni su come compilare e testare il codice.

Microsoft Azure SDK per JavaScript

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-16