# Comandos de mídia e voz

> Troque vozes, embuta legendas, crie slides e sobreposições, processe áudio e planeje edições com os comandos voice, media, audio e edit da CLI do Nodaro.

Source: https://nodaro.ai/pt-BR/docs/developers/cli/media-commands

Os **comandos de mídia e voz** da CLI do Nodaro trabalham diretamente com áudio, vídeo e imagens. O grupo `voice` troca a voz de faixas e cria vozes, `media` importa, corta, legenda e compõe mídias, `audio` processa e transcreve sons, e `edit` planeja e aplica edições para podcasts e vídeos longos. Cada comando usa o mesmo mecanismo que o nó correspondente no editor.

Todo comando que inicia um job aceita `--watch` para aguardar o resultado, `--poll-interval <ms>` para definir o intervalo da consulta periódica, e `--json`. Veja [Saída e códigos de saída](https://nodaro.ai/docs/developers/cli/output).

## Voz
```bash
nodaro voice list [--clones] [--json]
nodaro voice changer --voice <id> --audio <url>|--video <url> [--model <id>] [--stability <0..1>] [--similarity <0..1>] [--style <0..1>] [--use-speaker-boost] [--seed <n>] [--remove-background-noise] [--watch] [--poll-interval <ms>] [--json]
nodaro voice recast --audio <url>|--video <url> --voices <v1,v2,...>|--voices-json <json> [--model <id>] [--output video|stems] [--analysis-json <json>|--analysis-file <path>] [--no-preserve-background] [--separation-quality fast|best] [--music-volume-mode match|normalize|manual] [--music-volume <0-200>] [--remove-background-noise] [--voice-fx <preset>] [--voice-fx-mix <0-100>] [--voice-fx-delay <20-2000>] [--voice-fx-decay <0-1>] [--watch] [--poll-interval <ms>] [--json]
nodaro voice analyze --audio <url>|--video <url> [--separation-quality fast|best] [--suggest-title] [--watch] [--poll-interval <ms>] [--json]
nodaro voice export --source <videoUrl> --tracks-json <json>|--tracks-file <path> [--voice-fx <preset>] [--voice-fx-mix <0-100>] [--voice-fx-delay <20-2000>] [--voice-fx-decay <0-1>] [--watch] [--poll-interval <ms>] [--json]
nodaro voice design --text <line> --description <desc> [--model <id>] [--loudness <-1..1>] [--guidance-scale <0-100>] [--seed <n>] [--quality <n>] [--enhance] [--user-prompt <text>] [--watch] [--poll-interval <ms>] [--json]
nodaro voice remix --text <text> --description <desc> [--user-prompt <text>] [--watch] [--poll-interval <ms>] [--json]
nodaro voice dub --audio <url> --target-language <code> [--source-language <code>] [--num-speakers <1-20>] [--disable-voice-cloning] [--drop-background-audio] [--watch] [--poll-interval <ms>] [--json]
nodaro voice clones list [--json]
nodaro voice clones delete <id> [--json]
```

| Comando | O que faz |
| --- | --- |
| `voice list` | Lista as vozes prontas, ou os seus clones com `--clones`. Use os nomes ou os ids delas com `--voice` e `--voices`. |
| `voice changer` | Troca a voz de uma faixa de áudio ou de um vídeo com fala por uma única voz, como o nó [**Modificador de voz** (Voice Changer)](https://nodaro.ai/docs/nodes/audio/voice-changer). `voice change` é o mesmo comando. |
| `voice recast` | Troca a voz de todos os falantes de uma gravação de uma vez, como o nó [**Modificador de voz Pro** (Voice Changer Pro)](https://nodaro.ai/docs/nodes/audio/voice-changer-pro). `voice pro` é o mesmo comando. |
| `voice analyze` | Detecta os falantes sem trocar as vozes e imprime a lista com `--watch`. Só no Nodaro Cloud. |
| `voice export` | Renderiza o vídeo final a partir de um conjunto de faixas mixadas. Só no Nodaro Cloud. |
| `voice design` | Cria uma nova voz sintética a partir de uma descrição em texto, como o nó [**Design de voz** (Voice Design)](https://nodaro.ai/docs/nodes/audio/voice-design). |
| `voice remix` | Fala um texto com uma voz descrita, sem clonagem, como o nó [**Remix de voz** (Voice Remix)](https://nodaro.ai/docs/nodes/audio/voice-remix). |
| `voice dub` | Dubla uma gravação em outro idioma e mantém a voz de cada falante, como o nó [**Dublagem** (Dubbing)](https://nodaro.ai/docs/nodes/audio/dubbing). |
| `voice clones` | Lista e exclui os clones de voz criados antes de a clonagem ser descontinuada. |

### Trocar a voz de vários falantes
`voice recast` roda no Nodaro Cloud. Uma instalação self-hosted o executa pela [conexão com o Nodaro Cloud](https://nodaro.ai/docs/self-hosting/cloud-connect).

- `--voices` associa vozes aos falantes na ordem em que o Nodaro os detecta. A palavra `keep` mantém a voz original daquele falante, como em `--voices Rachel,keep,Aria`.
- `--voices-json` recebe, em vez disso, o array bruto do SDK: ids de vozes, objetos de configuração por voz, ou `null` para um falante que mantém a voz original.
- `--output stems` retorna uma faixa seca por falante, para uma mixagem interativa, em vez de um vídeo pronto. Renderize a mixagem com `voice export`.
- `--analysis-file` reaproveita um resultado salvo de `voice analyze`, então os falantes não são detectados de novo.

### O fluxo interativo de troca de vozes
O `voice recast` de uma etapa renderiza um vídeo pronto em uma única chamada. O fluxo de três etapas permite conferir primeiro os falantes e mixar o resultado antes de renderizá-lo:

```bash
# 1. Detect the speakers. Save the job's output_data for step 2.
nodaro voice analyze --video https://example.com/panel.mp4 --watch --json > analyze.json
jq .output_data analyze.json > analysis.json

# 2. Recast to dry stems, reusing the analysis (no second detection)
nodaro voice recast --video https://example.com/panel.mp4 --voices Rachel,keep,Aria \
  --analysis-file analysis.json --output stems --watch

# 3. Set the level and mute of each track, then render
nodaro voice export --source https://example.com/panel.mp4 --tracks-file mix.json \
  --voice-fx hall --voice-fx-mix 25 --watch
```

Na etapa 3, cada faixa em `mix.json` é um objeto com um `url`, um `gain` de 0 a 200, uma flag `muted` e um `kind` opcional, tirados dos stems da etapa 2. A exportação copia o fluxo de vídeo sem alterações; ele nunca é codificado de novo.

## Mídia
```bash
nodaro media download <url> [--max-height <px>] [--section <a-b>] [--watch] [--json]
nodaro media metadata <url> [--json]
nodaro media trim-video --video <url> --start <sec> --end <sec>|--keep-first <sec>|--keep-last <sec> [--watch] [--poll-interval <ms>] [--json]
nodaro media trim-audio --video <url>|--audio <url> [--start <sec>] [--end <sec>] [--format mp3|wav|aac] [--watch] [--poll-interval <ms>] [--json]
nodaro media add-captions <videoUrl> [options, see below]
nodaro media still-to-video --image <url> --audio <url> [--motion none|zoom-in|zoom-out|pan-left|pan-right|ken-burns] [--intensity <1-10>] [--resolution 720p|1080p|4K] [--aspect-ratio <W:H>] [--fps 24|30] [--fit cover|contain] [--pad-color <hex>] [--watch] [--poll-interval <ms>] [--json]
nodaro media slideshow --images <url...> [--audio <url>] [--durations "10,auto,auto"] [--per-image <sec>] [--transition <id>] [--transition-duration <sec>] [--motion none|zoom-in|zoom-out|ken-burns|alternate] [--intensity <1-10>] [--resolution 720p|1080p|4K] [--aspect-ratio <W:H>] [--fps 24|30] [--fit cover|contain] [--pad-color <hex>] [--watch] [--json]
nodaro media collage <imageUrls...> [--sizes <0-3,...>] [--numbered] [--label <text>...] [--badge-position top-left|top-right] [--layout smart|grid] [--resolution 2K|4K] [--aspect-ratio <W:H>] [--gap <px>] [--background-color <hex>] [--watch] [--poll-interval <ms>] [--json]
nodaro media overlay <imageUrl> [layerUrls...] [--layers-file <path>] [--anchor <anchor>] [--x <%>] [--y <%>] [--width <%>] [--opacity <0-1>] [--platform <id>...] [--qr-text <text>] [--mask-mode none|layers|around|outside] [--mask-spread <px>] [--canvas <WxH>] [--base-fit contain|cover] [--background-color <hex>] [--output-format png|jpg|webp] [--watch] [--poll-interval <ms>] [--json]
nodaro media overlay-placement <imageUrl> [--intent <text>] [--aspect <ratio>] [--safe-area <x,y,w,h>] [--json]
nodaro media video-overlay <videoUrl> [layerUrls...] [--at <start[-end]>...] [--preset card|corner-badge|full-frame] [--corner top-left|top-right|bottom-left|bottom-right] [--layers-file <path>] [--aspect 16:9|9:16|1:1|4:5] [--base-fit cover|contain] [--background-color <hex>] [--watch] [--poll-interval <ms>] [--json]
nodaro media save <url> [--filename <name>] [--type image|video|audio] [--watch] [--poll-interval <ms>] [--json]
```

| Comando | O que faz |
| --- | --- |
| `media download` | Importa para o seu armazenamento um vídeo do YouTube, TikTok, Instagram, X ou Facebook. `--section` busca um intervalo de tempo, em segundos. `--watch` transmite o progresso ao vivo, e não há job para consultar periodicamente depois. |
| `media metadata` | Lê a duração, as dimensões e o título de uma URL de mídia sem baixá-la. |
| `media trim-video` | Corta um vídeo pelo tempo de início e de fim, ou mantém os primeiros ou os últimos segundos. |
| `media trim-audio` | Corta o áudio de um vídeo ou de um arquivo de áudio e o salva como MP3, WAV ou AAC. |
| `media add-captions` | Embute legendas em um vídeo. Veja [Legendas](#captions). |
| `media still-to-video` | Transforma uma imagem fixa e um arquivo de áudio em um MP4, e custa 0 créditos. O vídeo tem a duração do áudio, então não há opção de duração. `--motion` anima a imagem fixa. |
| `media slideshow` | Transforma de 2 a 100 imagens, com áudio opcional, em uma apresentação de slides em MP4, e custa 0 créditos. |
| `media collage` | Combina de 2 a 30 imagens em uma única imagem grande. |
| `media overlay` | Coloca até 12 camadas sobre uma imagem base, com precisão de pixel, sem IA. |
| `media overlay-placement` | Pergunta a um modelo de visão onde uma camada deve ficar. |
| `media video-overlay` | Coloca de 1 a 20 camadas de imagem temporizadas sobre um vídeo, sem IA, por 22 créditos. |
| `media save` | Salva uma URL de mídia no seu armazenamento, como imagem, vídeo ou arquivo de áudio. |

### Apresentações de slides
Com áudio, o áudio define a duração da apresentação. As durações que você fixou com `--durations` são ajustadas na mesma proporção, e a CLI avisa isso. Sem áudio, a apresentação fica sem som e dura o número de imagens multiplicado por `--per-image`.

### Colagens
- `--sizes` dá a cada imagem uma indicação de tamanho relativo, na ordem das imagens: `0` automático, `1` grande (cerca de duas vezes mais larga), `2` médio, `3` pequeno (cerca de metade da largura). As indicações de tamanho só funcionam com o layout smart.
- `--numbered` carimba um número de sequência, a partir de 1, em um canto de cada imagem, para storyboards.
- `--badge-position` define esse canto: `top-left`, o padrão, ou `top-right`. A opção também posiciona os rótulos.
- `--label` adiciona uma legenda depois do número. Repita a opção uma vez por imagem, na ordem; um `""` vazio pula uma imagem.

### Sobreposições em imagem
- As URLs de imagens depois da imagem base são camadas de imagem. Elas compartilham `--anchor`, `--x`, `--y`, `--width` e `--opacity`, o que serve bem para uma marca d'água.
- `--layers-file` recebe, em vez disso, o array JSON completo de camadas: opções por camada e os tipos texto, QR code e forma.
- O posicionamento é em porcentagem da imagem base, então um mesmo comando serve para uma prévia em 1K e para uma renderização em 4K.
- `--platform`, que pode ser repetido, também renderiza a composição no tamanho daquela plataforma. A renderização base custa 11 créditos, e cada plataforma aumenta o preço. A saída do job lista as renderizações extras como `variants`.
- `overlay-placement` responde nas mesmas unidades de porcentagem: uma âncora, `x`, `y`, `width` e um motivo de uma linha. Ele responde na hora, sem job para consultar periodicamente, e custa uma chamada de imagem para texto.

### Sobreposições em vídeo
- Informe um `--at` por URL de imagem, na ordem. `3` significa de 3 segundos até o fim, e `1.2-2.6` significa de 1,2 a 2,6 segundos.
- `--preset` e `--corner` valem para todas as camadas de imagem informadas como URL.
- `--layers-file` recebe, em vez disso, o array completo de camadas, com caixa, opacidade, animação e ordem de empilhamento por camada.
- `--base-fit` e `--background-color` exigem `--aspect`.
- O áudio do vídeo base é mantido intacto.

Veja o nó [**Sobreposição em vídeo** (Video Overlay)](https://nodaro.ai/docs/nodes/video/video-overlay) para as opções de camada.

## Legendas
```bash
nodaro media add-captions <videoUrl> [--text <text>] [--captions-file <file.json>] [--style subtitle|word-highlight|karaoke|tiktok-words|word-pop|bouncy] [--look outline|clean] [--position bottom|top|center] [--position-y <pct>] [--font-size <px>] [--font-family <name>] [--font-weight <100-900>] [--color <c>] [--background-color <c>] [--stroke-color <c>] [--stroke-width <px>] [--highlight-color <c>] [--uppercase|--no-uppercase] [--max-words-per-line <1-20>] [--animate|--no-animate] [--no-auto-transcribe] [--transcribe-provider elevenlabs-stt|incredibly-fast-whisper|whisper] [--segments-file <file.json>] [--watch] [--poll-interval <ms>] [--json]
```

`media add-captions` tem dois tipos de estilo, como o nó [**Adicionar legendas** (Add Captions)](https://nodaro.ai/docs/nodes/video/add-captions):

| Estilo | O que mostra |
| --- | --- |
| `subtitle` | Legendas estáticas, sem animação das palavras. |
| `word-highlight`, `karaoke`, `tiktok-words`, `word-pop`, `bouncy` | Legendas cinéticas, animadas palavra por palavra. `word-highlight`, `karaoke` e `bouncy` mostram uma linha fixa de cada vez. |

### O texto das legendas
- Em `subtitle`, `--text` é embutido como um único bloco estático durante o vídeo inteiro. Ele nunca é substituído por uma transcrição. Omita `--text` para legendar a fala.
- Em um estilo cinético, `--text` é só a alternativa quando a transcrição não retorna nada, ou quando você passa `--no-auto-transcribe`.
- `--captions-file` é um array JSON de entradas com tempo por palavra, `[{ text, startMs, endMs }]`, com uma entrada por palavra nos estilos cinéticos. Os `words` de um resultado de `nodaro audio transcribe` servem do jeito que estão; use o arquivo junto com `--no-auto-transcribe`.
- `--segments-file` dá a intervalos de tempo estilo, visual e posição próprios. Os intervalos não podem se sobrepor.

### Estilização
- As opções de estilização também estilizam um `subtitle`: `--look`, `--font-family`, `--font-weight`, `--stroke-color`, `--stroke-width`, `--uppercase`, `--position-y` e `--max-words-per-line`. Um `subtitle` estilizado é cobrado pelo preço cinético; um `subtitle` simples continua no preço mais baixo.
- `--highlight-color` e `--animate` só funcionam nos estilos cinéticos. As duas são recusadas em `subtitle`.
- `--animate` vem ativada por padrão. `--no-animate` para o movimento de cada palavra e mantém o agrupamento e a cor de destaque.
- Sem `--look`, os estilos cinéticos são renderizados como `outline`, e `subtitle` é renderizado como `clean`.
- `--max-words-per-line` limita o número de palavras em uma linha de legenda, ou em uma página de `tiktok-words`, de 1 a 20. A largura do quadro, os finais de frase e as pausas de 0,5 segundo ou mais também quebram as linhas. Uma ou duas palavras dão uma leitura rápida e marcante; deixe a opção sem valor para preencher a largura. Em um subtitle com `--text`, ela só define as quebras de linha, e não tem efeito em `word-pop`.
- Uma renderização cinética ou estilizada mantém a taxa de quadros da origem, como um número inteiro de 15 a 60 fps. Uma origem com taxa de quadros variável ou muito longa é renderizada a 30 fps.

### Mecanismo de transcrição
`--transcribe-provider` escolhe o mecanismo que transcreve a fala. Um estilo cinético precisa das marcações de tempo das palavras, do `incredibly-fast-whisper`, o padrão, ou do `elevenlabs-stt`. `subtitle` só precisa das marcações de tempo das frases, então `whisper` também funciona nesse caso.

## Áudio
```bash
nodaro audio separate --audio <url> [--mode vocal_instrumental|stems] [--quality auto|fast|best] [--watch] [--poll-interval <ms>] [--json]
nodaro audio isolate --audio <url> [--watch] [--poll-interval <ms>] [--json]
nodaro audio fx --audio <url> [--preset <preset>] [--mix <0-100>] [--delay <20-2000>] [--decay <0-1>] [--eq-low <db>] [--eq-high <db>] [--watch] [--poll-interval <ms>] [--json]
nodaro audio mix --audio <url> --audio <url> ... [--volumes <csv>] [--watch] [--poll-interval <ms>] [--json]
nodaro audio adjust-volume --audio <url>|--video <url> [--volume <0-200>] [--normalize] [--fade-in <sec>] [--fade-out <sec>] [--watch] [--poll-interval <ms>] [--json]
nodaro audio combine --segment <url[@a-b]> --segment ... [--watch] [--poll-interval <ms>] [--json]
nodaro audio transcribe --audio <url> [--provider elevenlabs-stt|incredibly-fast-whisper|whisper] [--language <code>] [--diarize] [--tag-audio-events] [--word-timestamps] [--watch] [--poll-interval <ms>] [--json]
```

| Comando | O que faz | Nó |
| --- | --- | --- |
| `audio separate` | Separa os vocais do instrumental, ou divide o áudio em stems. | [**Separação de áudio** (Audio Separation)](https://nodaro.ai/docs/nodes/audio/audio-separation) |
| `audio isolate` | Mantém a voz e remove o resto. | [**Extrator de voz** (Voice Extractor)](https://nodaro.ai/docs/nodes/audio/voice-extractor) |
| `audio fx` | Aplica uma predefinição de efeito, com configurações de mixagem, delay, decaimento e equalizador. | [**Efeitos de áudio** (Audio FX)](https://nodaro.ai/docs/nodes/audio/audio-fx) |
| `audio mix` | Mixa várias faixas, com um volume por faixa. | [**Mixar áudio** (Mix Audio)](https://nodaro.ai/docs/nodes/audio/mix-audio) |
| `audio adjust-volume` | Altera o volume, normaliza e aplica fade in ou fade out. | [**Ajustar volume** (Adjust Volume)](https://nodaro.ai/docs/nodes/audio/adjust-volume) |
| `audio combine` | Junta segmentos um depois do outro. `url@a-b` pega um intervalo de tempo de um arquivo. | [**Combinar áudio** (Combine Audio)](https://nodaro.ai/docs/nodes/audio/combine-audio) |
| `audio transcribe` | Transforma fala em texto. | [**Transcrever** (Transcribe)](https://nodaro.ai/docs/nodes/audio/transcribe) |

Estas são as peças que o Modificador de voz Pro combina, disponíveis separadamente.

### Mecanismos de transcrição
| Mecanismo | Marcações de tempo das palavras | Também aceita |
| --- | --- | --- |
| `elevenlabs-stt` | Sempre | `--diarize` (quem fala quando) e `--tag-audio-events` |
| `incredibly-fast-whisper` | Com `--word-timestamps` | |
| `whisper` | Nenhuma, só segmentos de frases; `--word-timestamps` é recusado antes de qualquer crédito ser gasto | |

Se você omitir `--provider`, o mecanismo `whisper` é executado. Indique um mecanismo sempre que precisar das marcações de tempo das palavras.

O `output_data` do job concluído traz `text`, `words` (uma entrada por palavra, em milissegundos) e `json` (a transcrição normalizada, também em milissegundos). Uma lista `segments` no nível superior, em segundos, só existe com `whisper` e `incredibly-fast-whisper`; o `elevenlabs-stt` não retorna nenhuma, então leia `words`. Passe `words` para `media add-captions --captions-file` para uma renderização cinética.

## Edição
Os comandos de edição são peças editoriais para podcasts e vídeos longos.

```bash
nodaro edit silence-detect <audioUrl> [--threshold-db=-35] [--min-silence-ms <ms>] [--pad-ms <ms>] [--watch] [--poll-interval <ms>] [--json]
nodaro edit audio-sync (--source <[id=]url> ... | --sources-file <file.json>) [--reference <id>] [--watch] [--poll-interval <ms>] [--json]
nodaro edit apply-edl --edl <file.json> [--transcript <file.json>] [--source <url> ...] [--output video|audio] [--quality proxy|final] [--crossfade-ms <ms>] [--watch] [--poll-interval <ms>] [--json]
nodaro edit plan --mode tighten|clips|chapters --plan-tier economy|standard|premium --transcript <file.json> (--source <url[@audio|@video]> ... | --sources-file <file.json>) [--silence <file.json>] [--instructions <text>] [--style-guide <text>] [--count <n>] [--target-duration-sec <n>] [--target-aspect 16:9|9:16|1:1|4:5] [--platform <name>] [--watch] [--poll-interval <ms>] [--json]
```

| Comando | O que faz | Nó |
| --- | --- | --- |
| `edit silence-detect` | Encontra os trechos silenciosos de uma gravação. | [**Detectar silêncio** (Silence Detect)](https://nodaro.ai/docs/nodes/audio/silence-detect) |
| `edit audio-sync` | Alinha de 2 a 6 gravações, de áudio ou vídeo, do mesmo evento. | [**Sincronizar áudio** (Audio Sync)](https://nodaro.ai/docs/nodes/audio/audio-sync) |
| `edit plan` | Planeja uma edição a partir de uma transcrição: deixar o ritmo mais enxuto, cortar clipes ou marcar capítulos. | [**Plano de edição** (Edit Plan)](https://nodaro.ai/docs/nodes/video/edit-plan) |
| `edit apply-edl` | Renderiza uma lista de decisões de edição (EDL) como vídeo ou arquivo de áudio. | [**Aplicar EDL** (Apply EDL)](https://nodaro.ai/docs/nodes/video/apply-edl) |

`edit audio-sync` nomeia as gravações como `source-1`, `source-2` e assim por diante, a menos que você informe um id no formato `id=url`. O `output_data.json` dele tem três campos:

- `reference`: a gravação à qual as outras são alinhadas. Escolha essa gravação com `--reference`.
- `offsets`: uma entrada por gravação, com `sourceId`, `offsetMs`, `confidence` e `driftMsPerHour`.
- `notes`: observações sobre o alinhamento.

Um tempo em uma gravação é convertido para a referência com `referenceMs = sourceMs + offsetMs`.

## Frequently asked questions

### Como troco a voz de vários falantes de um vídeo pela CLI?

Execute nodaro voice recast com --video e --voices, com uma voz por falante, na ordem em que eles são detectados. Escreva keep para um falante que mantém a voz original, por exemplo --voices Rachel,keep,Aria.

### Qual mecanismo de transcrição fornece as marcações de tempo das palavras?

O elevenlabs-stt sempre retorna as marcações de tempo das palavras, e o incredibly-fast-whisper as retorna com --word-timestamps. O whisper retorna só segmentos de frases. Se você omitir --provider, o mecanismo whisper é executado, então indique um mecanismo sempre que precisar das palavras.

### still-to-video e slideshow custam créditos?

Não. nodaro media still-to-video e nodaro media slideshow renderizam o vídeo sem nenhum modelo de IA e custam 0 créditos.

### Como legendo um vídeo com palavras que eu mesmo corrigi?

Transcreva o áudio com um mecanismo que marca o tempo de cada palavra, edite as palavras no arquivo JSON salvo e depois passe o arquivo para nodaro media add-captions com --captions-file e --no-auto-transcribe.

### Quais comandos de mídia precisam do Nodaro Cloud?

voice analyze e voice export só funcionam no Nodaro Cloud. voice recast roda no Nodaro Cloud, e uma instalação self-hosted o executa pela conexão com o Nodaro Cloud.