> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Speech to Text multicanal

> **Note**
>
> **Guia prático** · Pressupõe que você concluiu o [guia de início rápido de Speech to Text ](/docs/pt/eleven-api/guides/cookbooks/speech-to-text).

## Visão geral

O recurso multicanal de Speech to Text permite transcrever arquivos de áudio em que cada canal contém um falante distinto. Isso é especialmente útil para gravações em que os falantes estão isolados em canais de áudio separados, proporcionando transcrições mais limpas sem a necessidade de diarização de falantes.

Cada canal é processado de forma independente e recebe automaticamente um ID de falante com base no número do canal (canal 0 → `speaker_0`, canal 1 → `speaker_1` etc.). O sistema extrai canais individuais do seu arquivo de áudio de entrada e os transcreve em paralelo. Por padrão, a API retorna uma transcrição por canal; defina `multichannel_output_style=combined` para receber uma única transcrição com todos os canais combinados em uma lista ordenada pelo horário de início, com cada palavra identificada pelo seu `channel_index`.

### Casos de uso comuns

* **Gravações de entrevistas em estéreo** - Entrevistador no canal esquerdo, entrevistado no canal direito
* **Gravações de podcasts com várias faixas** - Cada participante gravado em uma faixa separada
* **Gravações de central de atendimento** - Atendente e cliente separados em canais diferentes
* **Gravações de conferências** - Participantes individuais isolados em canais separados
* **Processos judiciais** - Várias partes gravadas em canais distintos

## Requisitos

* Uma conta ElevenLabs com uma [chave de API](https://elevenlabs.io/app/settings/api-keys)
* Arquivo de áudio multicanal (WAV, MP3 ou outros formatos compatíveis)
* Máximo de 5 canais por arquivo de áudio
* Cada canal deve conter apenas um falante

## Como funciona

#### Prepare seu áudio multicanal

Verifique se os falantes do seu arquivo de áudio estão isolados em canais separados. O recurso multicanal aceita até 5 canais, com cada canal mapeado para um falante específico:

* Canal 0 → `speaker_0`
* Canal 1 → `speaker_1`
* Canal 2 → `speaker_2`
* Canal 3 → `speaker_3`
* Canal 4 → `speaker_4`

#### Configure os parâmetros da API

Ao fazer uma solicitação de Speech to Text, você deve definir:

* `use_multi_channel`: `true`
* `diarize`: `false` (o modo multicanal separa os falantes pelos canais)

Opcionalmente, controle o formato da resposta com:

* `multichannel_output_style`: `separate` (padrão) retorna uma transcrição por canal. `combined` combina todos os canais em uma única transcrição, cujas palavras são ordenadas pelo horário de início e incluem um `channel_index` — correspondendo ao formato de resposta padrão para canal único. `combined` requer timestamps (`timestamps_granularity` não pode ser `none`) e não é compatível com entrega por webhook ou detecção/remoção de entidades.

O parâmetro `num_speakers` não pode ser usado com o modo multicanal, pois a quantidade de falantes é determinada automaticamente pelo número de canais. O modo multicanal pressupõe que haverá exatamente um falante por canal. Se houver mais de um, o mesmo ID de falante será atribuído a todos os falantes do canal.

#### Processe a resposta

Por padrão (`multichannel_output_style=separate`), o áudio multicanal retorna um formato de resposta diferente do áudio de canal único:

> **Note**
>
> Se você definir `use_multi_channel: true`, mas fornecer um arquivo de áudio de canal único (mono), receberá
> uma resposta padrão de canal único, não o formato multicanal. O formato de resposta multicanal
> só é retornado quando o arquivo de áudio realmente contém vários canais.

**`Resposta de canal único`**

```python title="Resposta de canal único"
{
  "language_code": "en",
  "language_probability": 0.98,
  "text": "Hello world",
  "words": [...]
}
```

**`Resposta multicanal`**

```python title="Resposta multicanal"
{
  "transcripts": [
    {
      "language_code": "en",
      "language_probability": 0.98,
      "text": "Hello from channel one.",
      "channel_index": 0,
      "words": [...]
    },
    {
      "language_code": "en",
      "language_probability": 0.97,
      "text": "Greetings from channel two.",
      "channel_index": 1,
      "words": [...]
    }
  ]
}
```

**`Resposta combinada (multichannel_output_style=combined)`**

```python title="Resposta combinada (multichannel_output_style=combined)"
{
  "language_code": "en",
  "language_probability": 0.98,
  "text": "Hello from channel one. Greetings from channel two.",
  "words": [
    { "text": "Hello", "start": 0.0, "end": 0.5, "type": "word", "speaker_id": "speaker_0", "channel_index": 0 },
    { "text": "Greetings", "start": 0.6, "end": 1.2, "type": "word", "speaker_id": "speaker_1", "channel_index": 1 }
  ]
}
```

Com `multichannel_output_style=combined`, a resposta usa o mesmo formato simples de uma transcrição de canal único (`text` e `words` no nível superior, sem a matriz `transcripts`), com todos os canais combinados em uma lista ordenada pelo horário de início. Cada palavra inclui um `channel_index` (e `speaker_id`) que identifica seu canal.

## Implementação

### Transcrição multicanal básica

Este é um exemplo completo de transcrição de um arquivo de áudio estéreo com dois falantes:

**`Python`**

```python title="Python"
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

def transcribe_multichannel(audio_file_path):
    with open(audio_file_path, 'rb') as audio_file:
        result = elevenlabs.speech_to_text.convert(
            file=audio_file,
            model_id='scribe_v2',
            use_multi_channel=True,
            diarize=False,
            timestamps_granularity='word'
        )
    return result

# Process the response

result = transcribe_multichannel('stereo_interview.wav')

if hasattr(result, 'transcripts'): # Multichannel response
    for transcript in result.transcripts:
        channel = transcript.channel_index
        text = transcript.text
        print(f"Channel {channel} (speaker_{channel}): {text}")
    else: # Single channel response (fallback)
        print(f"Text: {result.text}")

```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import fs from "fs";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

async function transcribeMultichannel(audioFilePath) {
  try {
    const audioFile = fs.createReadStream(audioFilePath);

    const result = await elevenlabs.speechToText.convert({
      file: audioFile,
      modelId: "scribe_v2",
      useMultiChannel: true,
      diarize: false,
      timestampsGranularity: "word",
    });

    // With useMultiChannel: true the SDK returns one transcript per channel
    result.transcripts.forEach((transcript) => {
      console.log(`Channel ${transcript.channelIndex}: ${transcript.text}`);
    });

    return result;
  } catch (error) {
    console.error("Error transcribing audio:", error);
    throw error;
  }
}
```

**`cURL`**

```bash title="cURL"
curl -X POST "https://api.elevenlabs.io/v1/speech-to-text" \
  -H "xi-api-key: YOUR_API_KEY" \
  -F "file=@stereo_audio_file.wav" \
  -F "model_id=scribe_v2" \
  -F "use_multi_channel=true" \
  -F "diarize=false" \
  -F "timestamps_granularity=word"
```

### Criação de transcrições de conversas

A maneira mais fácil de obter uma transcrição de conversa ordenada cronologicamente é solicitar `multichannel_output_style=combined` — a API retorna uma única lista de `words`, já ordenada pelo horário de início, com um `channel_index` e `speaker_id` em cada palavra:

**`Saída combinada (recomendado)`**

```python title="Saída combinada (recomendado)"
with open("stereo_interview.wav", "rb") as audio_file:
    result = elevenlabs.speech_to_text.convert(
        file=audio_file,
        model_id="scribe_v2",
        use_multi_channel=True,
        multichannel_output_style="combined",
        diarize=False,
        timestamps_granularity="word",
    )

for word in result.words:
    if word.type == "word":
        print(f"speaker_{word.channel_index}: {word.text}")
```

Se você estiver usando a saída padrão `separate`, também pode combinar as transcrições por canal no cliente:

```python
def create_conversation_transcript(multichannel_result):
    """Create a conversation-style transcript with speaker labels"""
    all_words = []

    if hasattr(multichannel_result, 'transcripts'):
        # Collect all words from all channels
        for transcript in multichannel_result.transcripts:
            for word in transcript.words or []:
                if word.type == 'word':
                    all_words.append({
                        'text': word.text,
                        'start': word.start,
                        'speaker_id': word.speaker_id,
                        'channel': transcript.channel_index
                    })

    # Sort by timestamp
    all_words.sort(key=lambda w: w['start'])

    # Group consecutive words by speaker
    conversation = []
    current_speaker = None
    current_text = []

    for word in all_words:
        if word['speaker_id'] != current_speaker:
            if current_text:
                conversation.append({
                    'speaker': current_speaker,
                    'text': ' '.join(current_text)
                })
            current_speaker = word['speaker_id']
            current_text = [word['text']]
        else:
            current_text.append(word['text'])

    # Add the last segment
    if current_text:
        conversation.append({
            'speaker': current_speaker,
            'text': ' '.join(current_text)
        })

    return conversation

# Format the output
conversation = create_conversation_transcript(result)
for turn in conversation:
    print(f"{turn['speaker']}: {turn['text']}")
```

## Uso de webhooks com multicanal

A transcrição multicanal é compatível com a [entrega por webhook](/docs/pt/eleven-api/guides/how-to/speech-to-text/batch/webhooks) para processamento assíncrono:

> **Note**
>
> Os webhooks retornam o formato `separate` (por canal). `multichannel_output_style=combined` não é
> compatível atualmente com a entrega por webhook — use uma solicitação síncrona ou combine os payloads
> de webhook por canal no cliente.

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

async def transcribe_multichannel_with_webhook(audio_file_path):
    with open(audio_file_path, 'rb') as audio_file:
        result = await elevenlabs.speech_to_text.convert_async(
            file=audio_file,
            model_id='scribe_v2',
            use_multi_channel=True,
            diarize=False,
            webhook=True  # Enable webhook delivery
        )

    print(f"Transcription started with task ID: {result.task_id}")
    return result.task_id
```

## Tratamento de erros

### Erros de validação comuns

#### Definir diarize=true com o modo multicanal

**Erro**: O modo multicanal não oferece suporte à diarização e atribui falantes com base no
canal em que falam.

**Solução**: Sempre defina `diarize=false` ao usar o modo multicanal.

#### Fornecer o parâmetro num_speakers

**Erro**: Não é possível especificar num_speakers quando use_multi_channel está ativado. O número de falantes
é determinado automaticamente pelo número de canais. **Solução**: Remova o parâmetro
`num_speakers` da sua solicitação.

#### Arquivo de áudio com mais de 5 canais

**Erro**: O modo multicanal aceita até 5 canais, mas o arquivo de áudio contém X canais.

**Solução**: Processe apenas os primeiros 5 canais ou faça o pré-processamento do áudio para reduzir a
quantidade de canais.

#### Usar saída combinada sem timestamps

**Erro**: multichannel_output_style='combined' requer timestamps; defina timestamps_granularity
como 'word' ou 'character'.

**Solução**: A saída combinada ordena as palavras pelo tempo, então defina `timestamps_granularity` como `word`
(o padrão) ou `character`.

#### Usar saída combinada com webhooks

**Erro**: multichannel_output_style='combined' ainda não é compatível com a entrega por webhook.

**Solução**: Use uma solicitação síncrona com `combined` ou mantenha a saída padrão `separate`
ao usar webhooks e combine os dados no cliente.

## Boas práticas

### Preparação do áudio

> **Tip**
>
> Para obter os melhores resultados: - Use taxa de amostragem de 16 kHz para melhor desempenho - Remova canais silenciosos ou não utilizados
> antes do processamento - Verifique se cada canal contém apenas um falante - Use formatos sem perda
> (WAV) sempre que possível para obter a melhor qualidade

### Otimização de desempenho

O custo de simultaneidade aumenta linearmente com o número de canais. Um arquivo de 60 segundos com 3 canais tem um custo de simultaneidade 3 vezes maior que o de um arquivo de canal único.

Você pode estimar o tempo de processamento de áudio multicanal usando a seguinte fórmula:

$$
Processing\ Time = (D \cdot 0.3) + 2 + (N \cdot 0.5)
$$

Em que:

* $D$ = duração do arquivo em segundos
* $N$ = número de canais
* $0.3$ = fator de velocidade de processamento (aproximadamente 30% do tempo real)
* $2$ = sobrecarga fixa em segundos
* $0.5$ = sobrecarga por canal em segundos

**Exemplo**: Para um arquivo estéreo de 60 segundos (2 canais):

$$
Processing\ Time = (60 \cdot 0.3) + 2 + (2 \cdot 0.5) = 18 + 2 + 1 = 21\ seconds
$$

### Considerações sobre memória

Para arquivos multicanal grandes, considere fazer streaming ou dividir em partes:

**`Python`**

```python title="Python"
def process_large_multichannel_file(file_path, chunk_duration=300):
    """Process large files in chunks (5-minute segments)"""

    from pydub import AudioSegment
    from elevenlabs import ElevenLabs
    import os

    elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
    audio = AudioSegment.from_file(file_path)
    duration_ms = len(audio)
    chunk_size_ms = chunk_duration * 1000

    all_transcripts = []

    for start_ms in range(0, duration_ms, chunk_size_ms):
        end_ms = min(start_ms + chunk_size_ms, duration_ms)

        # Extract chunk
        chunk = audio[start_ms:end_ms]
        chunk_file = f"temp_chunk_{start_ms}.wav"
        chunk.export(chunk_file, format="wav")

        # Transcribe chunk using SDK
        with open(chunk_file, 'rb') as audio_file:
            result = elevenlabs.speech_to_text.convert(
                file=audio_file,
                model_id='scribe_v2',
                use_multi_channel=True,
                diarize=False,
                timestamps_granularity='word'
            )

        # Adjust timestamps
        if hasattr(result, 'transcripts'):
            for transcript in result.transcripts:
                for word in transcript.words or []:
                    word.start += start_ms / 1000
                    word.end += start_ms / 1000
            all_transcripts.extend(result.transcripts)

        # Clean up
        os.remove(chunk_file)

    return all_transcripts

```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { exec } from "child_process";
import fs from "fs";
import path from "path";
import { promisify } from "util";

const execAsync = promisify(exec);
const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

async function processLargeMultichannelFile(filePath, chunkDuration = 300) {
  /**
   * Process large files in chunks (5-minute segments)
   * Requires ffmpeg to be installed
   */

  // Get audio duration using ffprobe
  const { stdout } = await execAsync(
    `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${filePath}"`
  );
  const durationSeconds = parseFloat(stdout);

  const allTranscripts = [];

  for (let startSeconds = 0; startSeconds < durationSeconds; startSeconds += chunkDuration) {
    const endSeconds = Math.min(startSeconds + chunkDuration, durationSeconds);
    const chunkFile = path.join(path.dirname(filePath), `temp_chunk_${startSeconds}.wav`);

    // Extract chunk using ffmpeg
    await execAsync(
      `ffmpeg -i "${filePath}" -ss ${startSeconds} -t ${chunkDuration} -c:a pcm_s16le "${chunkFile}" -y`
    );

    try {
      // Transcribe chunk
      const audioFile = fs.createReadStream(chunkFile);
      const result = await elevenlabs.speechToText.convert({
        file: audioFile,
        modelId: "scribe_v2",
        useMultiChannel: true,
        diarize: false,
        timestampsGranularity: "word",
      });

      // Adjust timestamps
      if (result.transcripts) {
        for (const transcript of result.transcripts) {
          for (const word of transcript.words || []) {
            word.start += startSeconds;
            word.end += startSeconds;
          }
        }
        allTranscripts.push(...result.transcripts);
      }
    } finally {
      // Clean up
      fs.unlinkSync(chunkFile);
    }
  }

  return { transcripts: allTranscripts };
}
```

## Perguntas frequentes

#### O que acontece se meu áudio tiver mais de 5 canais?

A API retornará um erro. Você precisará selecionar quais 5 canais enviar para a API
ou mixar alguns canais antes de enviá-los para a API.

#### Posso processar áudio mono com o modo multicanal?

Sim, mas não é necessário. Se você enviar áudio mono com `use_multi_channel=true`, receberá
uma resposta padrão de canal único, não o formato multicanal.

#### Posso obter uma transcrição combinada em vez de transcrições separadas por canal?

Sim. Defina `multichannel_output_style=combined` para receber uma única transcrição com todos os canais
combinados e ordenados pelo horário de início, com cada palavra identificada pelo seu `channel_index`. Isso corresponde ao
formato de resposta padrão para canal único. Requer timestamps e não está disponível com entrega por
webhook.

#### Como os IDs de falante são atribuídos?

Os IDs de falante são determinísticos com base no número do canal: o canal 0 se torna speaker_0, o canal 1
se torna speaker_1 e assim por diante.

#### Os canais podem ter idiomas diferentes?

Sim, cada canal é processado de forma independente e pode detectar idiomas diferentes. A detecção de idioma
ocorre por canal. Com `multichannel_output_style=combined`, o `language_code`
de nível superior reflete o canal com maior confiança, enquanto cada palavra ainda inclui seu
`channel_index`.

## Próximas etapas

#### [Referência da API](/docs/pt/api-reference/speech-to-text)

Referência e parâmetros completos da API de Speech to Text.

#### [Webhooks](/docs/pt/eleven-api/guides/how-to/speech-to-text/batch/webhooks)

Receba resultados de transcrição de forma assíncrona via webhook.